http://qs1969.pair.com?node_id=72809
Category: HTML Utility
Author/Contact Info rudif@bluemail.ch
Description: ActiveState Perl installer creates a html tree and a TOC file for access to the perl documentation from a browser.
The PPM updates this tree and the TOC when installing packages.

However, in several circumstances you may wish to use this script here, to convert pod found in module files to html and/or to update the TOC:
  1. you added html files found on the web
  2. you installed a module from CPAN whose files contain pod
  3. you installed your own scripts or modules containing pod
Update: the ryddler's 'quick and dirty utility' that I started from was originally posted right here at PM. Thanks to $code or die for making the connection.

#! perl -w

use strict; 

use ActivePerl::DocTools; 
use Config;
use File::Copy; 
use File::Find; 
use File::Path; 
use File::stat;
use Getopt::Long;
use Pod::Find; 
use Pod::Html; 
use Pod::Usage;


my %opts = (query=>0, verbose=>0, force=>0, help=>0, man=>0, listro=>0
+,);
my $ok = GetOptions(\%opts, keys %opts);
                       
pod2usage(0) unless $ok;
pod2usage(0) if $opts{help};
pod2usage(-exitstatus => 0, -verbose => 2) if $opts{man};


$|++;


my $stylesheet = 'Active.css';

my $podroot  = "$Config{installprefix}"; # usually C:/perl on Win32
my $htmlroot = "$Config{installhtmldir}"; # usually C:/perl/html on Wi
+n32

$podroot =~ s#\\#/#g;
$htmlroot =~ s#\\#/#g;


if ($opts{listro}) {
    listReadonlyHtmls();
    exit;
}


my $logfile = "$Config{installhtmldir}/htmllog.txt"; 
open LOGFILE, ">>$logfile" || die "couldn't open LOGFILE $logfile\n"; 
print LOGFILE scalar localtime(), "\n"; 

findAndConvertPods(); 
print LOGFILE "-" x 60, "\n"; 
close LOGFILE; 
printf STDERR "Updated logfile $logfile\n";

ActivePerl::DocTools::WriteTOC(); 



sub findAndConvertPods {
    print STDERR "Finding files containing pod in $podroot\n" if $opts
+{verbose};
    my %pods = Pod::Find::pod_find({ -verbose => $opts{verbose},  }, "
+$podroot"); 
    my $pods = keys %pods;
    printf STDERR "Found $pods files\n";

    # convert pods unless query
    #
    my $converted = 0;
    foreach(sort keys %pods) { 
        print STDERR "    $_ podfile\n" if $opts{verbose};
        convertPod2html($_) && ++$converted; 
    } 
    printf STDERR "$converted files %sconverted to html.\n", $opts{que
+ry} ? 'should be ' : '';
} 


sub convertPod2html { 
    my $podfile = shift; 
    $podfile =~ s#\\#/#g; 
    if ($podfile =~ m!$podroot/(.*)/(\w+)\.p(od|l|m)$!i) { 
        my $path = $1; 
        my $name = $2; 
        my $outfile = "$htmlroot/$path/$name.html";
        my $action = '';
        if (! -e $outfile) { 
            $action = 'created';
        }
        elsif (stat($podfile)->mtime > stat($outfile)->mtime || $opts{
+force}) {
            $action = 'updated';
        }
        if ($action) {
            if ($opts{query}) {
                $action = "should be $action";
            }
            else {
                (my $stylesheetpath = "$path") =~ s#\w+(/?)#..$1#g;
                mkpath("$htmlroot/$path"); 
                pod2html(    "--infile=$podfile", 
                            "--outfile=$outfile", 
                            "--header", 
                            "--podroot=$podroot", 
                            "--podpath=site/lib:lib", 
                            "--htmlroot=$htmlroot",
                            "--css=$stylesheetpath/$stylesheet", 
                ); 
            }
            print LOGFILE "-- $outfile $action\n";
            print STDERR"-- $outfile $action\n" if $opts{verbose};
            return 1;
        }
    } 
    return 0;
} 
  

sub listReadonlyHtmls {
    my $html = 0;
    my $htmlro = 0;
    find( sub { 
                ++$html if /\.html?$/; 
                ++$htmlro unless -w; 
#                printf "$File::Find::name %d\n", -s;
                print STDERR "$File::Find::name RO\n" unless -w;
    }, $htmlroot);
    print STDERR "Found $html html files ($htmlro read-only).\n";
}

__END__
  


=head1 NAME

UpdateHtmlDoc.pl 

=head1 SYNOPSIS

UpdateHtmlDoc  [options]
  
 Updates html doc files and TOC in the ActiveState Perl directory tree
+.

 Options:
    -force          forces update of all html files
    -help           prints brief help message and exits
    -listro         lists read-only html files and exits
    -man            prints full documentation and exits
    -query          only lists html files that need to be created or u
+pdated
    -verbose        prints detail of operations

=head1 DESCRIPTION

Finds pod content in .pod, .pm and .pl files in Perl tree
directories lib, site\lib and bin.

Creates or updates the corresponding html files in corresponding subdi
+rectories of
perl\html directory.

Updates the TOC file.

=head1 MOTIVATION

ActiveState Perl installer creates a html tree and a TOC file for acce
+ss 
to the perl documentation from a browser.
The PPM updates this tree and the TOC when installing packages.

However, in several circumstances you may wish to use this script,
to convert pod found in module files to html and/or to update the TOC:

=over 4

=item *

you added html files found on the web

=item *

you installed a module from CPAN whose files contain pod

=item *

you installed your own scripts or modules containing pod

=back


=head1 PATCH

The module Toc.pm from ActiveState (perl/site/lib/ActivePerl/DocTools/
+Toc.pm)
indexes only files under lib and site/lib. 

To include files from perl\bin directory, you need to patch Toc.pm 

 my @checkdirs = qw(bin lib site/lib); ### RF added bin 

 $TOCdir =~ s#.*bin/(.*)$#$1#;  ### RF added bin 
 $TOCdir =~ s#.*?lib/(.*)$#$1#; 
 $TOCdir =~ s#/#::#g; 
  

=head1 LIMITATIONS

This script was tested only on Win2k with Perl 5.6.0 (build 623). 
Please let me know if you find any problems. 

=head1 SEE ALSO

perl(1).

=head1 AUTHOR

Rudi Farkas rudif@bluemail.ch  15 Apr 2001

Based on ideas and code from 'a quick and dirty utility' 
script posted to perl-win32-users@listserv.ActiveState.com by
ryddler@cu-online.com on 13 Mar 2001.

=cut