#!./perl -Ilib -w # This file should really be extracted from a .PL file $| = 1; use strict; use Config; # for config options in the makefile use File::Path qw(remove_tree); use File::Spec::Functions qw(rel2abs no_upwards); use Getopt::Long; # for command-line parsing use Cwd; use Pod::Html 1.32; use Pod::Html::Util 1.32 qw(anchorify relativize_url); =head1 NAME installhtml - converts a collection of POD pages to HTML format. =head1 SYNOPSIS installhtml [--help] [--podpath=:...:] [--podroot=] [--htmldir=] [--htmlroot=] [--norecurse] [--recurse] [--splithead=,...,] [--splititem=,...,] [--ignore=,...,] [--verbose] =head1 DESCRIPTION I converts a collection of POD pages to a corresponding collection of HTML pages. This is used to convert the pod pages found in the perl distribution. (It is not intended as a general-purpose converter/installer of POD pages in HTML format. See L.) =head1 OPTIONS =over 4 =item B<--help> help Displays the usage. =item B<--podroot> POD search path base directory The base directory to search for all .pod and .pm files to be converted. Default is current directory. =item B<--podpath> POD search path The list of directories to search for .pod and .pm files to be converted. Default is 'podroot/lib'. =item B<--recurse> recurse on subdirectories Whether or not to convert all .pm and .pod files found in subdirectories too. Default is to not recurse. =item B<--htmldir> HTML destination directory The base directory which all HTML files will be written to. This should be a path relative to the filesystem, not the resulting URL. =item B<--htmlroot> URL base directory The base directory which all resulting HTML files will be visible at in a URL. The default is '/'. =item B<--splithead> POD files to split on =head directive Comma-separated list of pod files to split by the =head directive. The .pod suffix is optional. These files should have names specified relative to podroot. =item B<--splititem> POD files to split on =item directive Comma-separated list of all pod files to split by the =item directive. The .pod suffix is optional. I does not do the actual split, rather it invokes I, a separate program in the Perl 5 core distribution, to do the dirty work. As with --splithead, these files should have names specified relative to podroot. =item B<--splitpod> Directory containing the splitpod program The directory containing the splitpod program. The default is 'podroot/pod'. =item B<--ignore> files to be ignored Comma-separated of files that shouldn't be installed, given relative to podroot. =item B<--verbose> verbose output Self-explanatory. =back =head1 EXAMPLE The following command-line is an example of the one we use to convert perl documentation: ./installhtml --podpath=lib:ext:pod:vms \ --podroot=/usr/src/perl \ --htmldir=/perl/nmanual \ --htmlroot=/perl/nmanual \ --splithead=pod/perlipc \ --splititem=pod/perlfunc \ --recurse \ --verbose =head1 AUTHOR Chris Hall Ehallc@cs.colorado.eduE =cut my $usage; $usage =<:...: --podroot= --htmldir= --htmlroot= --norecurse --recurse --splithead=,..., --splititem=,..., --ignore=,..., --verbose --help - this message --podpath - colon-separated list of directories containing .pod and .pm files to be converted ('lib/' by default). --podroot - filesystem base directory from which all relative paths in podpath stem (default is .). --htmldir - directory to store resulting html files in relative to the filesystem (\$podroot/html by default). --htmlroot - http-server base directory from which all relative paths in podpath stem (default is /). --norecurse - don't recurse on those subdirectories listed in podpath. (default behavior). --recurse - recurse on those subdirectories listed in podpath --splithead - comma-separated list of .pod or .pm files to split. will split each file into several smaller files at every occurrence of a pod =head[1-6] directive. --splititem - comma-separated list of .pod or .pm files to split using splitpod. --splitpod - directory where the program splitpod can be found (\$podroot/pod by default). --ignore - comma-separated list of files that shouldn't be installed. --verbose - self-explanatory. END_OF_USAGE my (@podpath, $podroot, $htmldir, $htmlroot, $recurse, @splithead, @splititem, $splitpod, $verbose, $pod2html, @ignore); @podpath = ( "lib" ); # colon-separated list of directories containing .pod # and .pm files to be converted. $podroot = "."; # assume the pods we want are here $htmldir = ""; # nothing for now... $htmlroot = "/"; # default value $recurse = 0; # default behavior @splithead = (); # don't split any files by default @splititem = (); # don't split any files by default $splitpod = ""; # nothing for now. $verbose = 0; # whether or not to print debugging info $pod2html = "pod/pod2html"; usage("") unless @ARGV; # Overcome shell's p1,..,p8 limitation. # See vms/descrip_mms.template -> descrip.mms for invocation. if ( $^O eq 'VMS' ) { @ARGV = split(/\s+/,$ARGV[0]); } our %Options; # parse the command-line my $result = GetOptions( \%Options, qw( help podpath=s podroot=s htmldir=s htmlroot=s ignore=s recurse! splithead=s splititem=s splitpod=s verbose )); usage("invalid parameters") unless $result; parse_command_line(); # set these variables to appropriate values if the user didn't specify # values for them. $htmldir = "$htmlroot/html" unless $htmldir; $splitpod = "$podroot/pod" unless $splitpod; # make sure that the destination directory exists (mkdir($htmldir, 0755) || die "$0: cannot make directory $htmldir: $!\n") if ! -d $htmldir; # the following array will eventually contain files that are to be # ignored in the conversion process. these are files that have been # process by splititem or splithead and should not be converted as a # result. my @splitdirs; # split pods. It's important to do this before convert ANY pods because # it may affect some of the links @splitdirs = (); # files in these directories won't get an index split_on_head($podroot, $htmldir, \@splitdirs, \@ignore, @splithead); split_on_item($podroot, \@splitdirs, \@ignore, @splititem); # convert the pod pages found in @poddirs #warn "converting files\n" if $verbose; #warn "\@ignore\t= @ignore\n" if $verbose; foreach my $dir (@podpath) { installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore); } # now go through and create master indices for each pod we split foreach my $dir (@splititem) { print "creating index $htmldir/$dir.html\n" if $verbose; create_index("$htmldir/$dir.html", "$htmldir/$dir"); } foreach my $dir (@splithead) { (my $pod = $dir) =~ s,^.*/,,; $dir .= ".pod" unless $dir =~ /(\.pod|\.pm)$/; # let pod2html create the file runpod2html($dir, 1); # now go through and truncate after the index $dir =~ /^(.*?)(\.pod|\.pm)?$/sm; my $file = "$htmldir/$1"; print "creating index $file.html\n" if $verbose; # read in everything until what would have been the first =head # directive, patching the index as we go. open(H, '<', "$file.html") || die "$0: error opening $file.html for input: $!\n"; $/ = ""; my @data = (); while () { last if m!

NAME

!; $_ =~ s{href="#(.*)">}{ my $url = "$file/@{[anchorify(qq($1))]}.html" ; $url = relativize_url( $url, "$file.html" ) if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' ); "href=\"$url\">" ; }egi; push @data, $_; } close(H); # now rewrite the file open(H, '>', "$file.html") || die "$0: error opening $file.html for output: $!\n"; print H @data, "\n\n\n\n\n"; close(H); } remove_tree(@splitdirs, {safe=>1}); ############################################################################## sub usage { warn "$0: @_\n" if @_; die $usage; } sub parse_command_line { usage() if defined $Options{help}; $Options{help} = ""; # make -w shut up # list of directories @podpath = split(":", $Options{podpath}) if defined $Options{podpath}; # lists of files @splithead = split(",", $Options{splithead}) if defined $Options{splithead}; @splititem = split(",", $Options{splititem}) if defined $Options{splititem}; $htmldir = $Options{htmldir} if defined $Options{htmldir}; $htmlroot = $Options{htmlroot} if defined $Options{htmlroot}; $podroot = $Options{podroot} if defined $Options{podroot}; $splitpod = $Options{splitpod} if defined $Options{splitpod}; $recurse = $Options{recurse} if defined $Options{recurse}; $verbose = $Options{verbose} if defined $Options{verbose}; @ignore = map "$podroot/$_", split(",", $Options{ignore}) if defined $Options{ignore}; } sub create_index { my($html, $dir) = @_; (my $pod = $dir) =~ s,^.*/,,; # get the list of .html files in this directory opendir(DIR, $dir) || die "$0: error opening directory $dir for reading: $!\n"; my @files = sort(grep(/\.html?$/, readdir(DIR))); closedir(DIR); open(HTML, '>', $html) || die "$0: error opening $html for output: $!\n"; # for each .html file in the directory, extract the index # embedded in the file and throw it into the big index. print HTML "
\n"; foreach my $file (@files) { my $filedata = do { open(my $in, '<', "$dir/$file") || die "$0: error opening $dir/$file for input: $!\n"; local $/ = undef; <$in>; }; # pull out the NAME section my($lcp1, $lcp2) = ($filedata =~ m#

NAME

\s*

\s*(\S+)\s+-\s+(\S.*?\S)

#); defined $lcp1 or die "$0: can't find NAME section in $dir/$file\n"; my $url= "$dir/$file" ; if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' ) { $url = relativize_url( $url, $html ) ; } print HTML qq(
); print HTML "$lcp1
$lcp2
\n"; } print HTML "
\n"; close(HTML); } sub split_on_head { my($podroot, $htmldir, $splitdirs, $ignore, @splithead) = @_; my($pod, $dirname, $filename); # split the files specified in @splithead on =head[1-6] pod directives print "splitting files by head.\n" if $verbose && $#splithead >= 0; foreach $pod (@splithead) { # figure out the directory name and filename $pod =~ s,^([^/]*)$,/$1,; $pod =~ m,(.*)/(.*?)(\.pod)?$,; $dirname = $1; $filename = "$2.pod"; # since we are splitting this file it shouldn't be converted. push(@$ignore, "$podroot/$dirname/$filename"); # split the pod splitpod("$podroot/$dirname/$filename", "$podroot/$dirname", $htmldir, $splitdirs); } } sub split_on_item { my($podroot, $splitdirs, $ignore, @splititem) = @_; my($pwd, $dirname, $filename); print "splitting files by item.\n" if $verbose && $#splititem >= 0; $pwd = getcwd(); my $splitter = rel2abs("$splitpod/splitpod", $pwd); my $perl = rel2abs($^X, $pwd); foreach my $pod (@splititem) { # figure out the directory to split into $pod =~ s,^([^/]*)$,/$1,; $pod =~ m,(.*)/(.*?)(\.pod)?$,; $dirname = "$1/$2"; $filename = "$2.pod"; # since we are splitting this file it shouldn't be converted. push(@$ignore, "$podroot/$dirname.pod"); # split the pod push(@$splitdirs, "$podroot/$dirname"); -d "$podroot/$dirname" and remove_tree("$podroot/$dirname", {safe=>1}); mkdir("$podroot/$dirname", 0755) || die "$0: error creating directory $podroot/$dirname: $!\n"; chdir("$podroot/$dirname") || die "$0: error changing to directory $podroot/$dirname: $!\n"; die "$splitter not found. Use '-splitpod dir' option.\n" unless -f $splitter; system($perl, $splitter, "../$filename") && warn "$0: error running '$splitter ../$filename'" ." from $podroot/$dirname"; } chdir($pwd); } # # splitpod - splits a .pod file into several smaller .pod files # where a new file is started each time a =head[1-6] pod directive # is encountered in the input file. # sub splitpod { my($pod, $poddir, $htmldir, $splitdirs) = @_; my(@poddata, @filedata, @heads); my($file, $i, $j, $prevsec, $section, $nextsec); print "splitting $pod\n" if $verbose; # read the file in paragraphs $/ = ""; open(SPLITIN, '<', $pod) || die "$0: error opening $pod for input: $!\n"; @filedata = ; close(SPLITIN) || die "$0: error closing $pod: $!\n"; # restore the file internally by =head[1-6] sections @poddata = (); for ($i = 0, $j = -1; $i <= $#filedata; $i++) { $j++ if ($filedata[$i] =~ /^\s*=head[1-6]/); if ($j >= 0) { $poddata[$j] = "" unless defined $poddata[$j]; $poddata[$j] .= "\n$filedata[$i]" if $j >= 0; } } # create list of =head[1-6] sections so that we can rewrite # L<> links as necessary. my %heads = (); foreach $i (0..$#poddata) { $heads{anchorify($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/; } # create a directory of a similar name and store all the # files in there $pod =~ s,.*/(.*),$1,; # get the last part of the name my $dir = $pod; $dir =~ s/\.pod//g; push(@$splitdirs, "$poddir/$dir"); -d "$poddir/$dir" and remove_tree("$poddir/$dir", {safe=>1}); mkdir("$poddir/$dir", 0755) || die "$0: could not create directory $poddir/$dir: $!\n"; $poddata[0] =~ /^\s*=head[1-6]\s+(.*)/; $section = ""; $nextsec = $1; # for each section of the file create a separate pod file for ($i = 0; $i <= $#poddata; $i++) { # determine the "prev" and "next" links $prevsec = $section; $section = $nextsec; if ($i < $#poddata) { $poddata[$i+1] =~ /^\s*=head[1-6]\s+(.*)/; $nextsec = $1; } else { $nextsec = ""; } # determine an appropriate filename (this must correspond with # what pod2html will try and guess) # $poddata[$i] =~ /^\s*=head[1-6]\s+(.*)/; $file = "$dir/" . anchorify($section) . ".pod"; # create the new .pod file print "\tcreating $poddir/$file\n" if $verbose; open(SPLITOUT, '>', "$poddir/$file") || die "$0: error opening $poddir/$file for output: $!\n"; $poddata[$i] =~ s,L<([^<>]*)>, defined $heads{anchorify($1)} ? "L<$dir/$1>" : "L<$1>" ,ge; print SPLITOUT $poddata[$i]."\n\n"; print SPLITOUT "=over 4\n\n"; print SPLITOUT "=item *\n\nBack to L<$dir/\"$prevsec\">\n\n" if $prevsec; print SPLITOUT "=item *\n\nForward to L<$dir/\"$nextsec\">\n\n" if $nextsec; print SPLITOUT "=item *\n\nUp to L<$dir>\n\n"; print SPLITOUT "=back\n\n"; close(SPLITOUT) || die "$0: error closing $poddir/$file: $!\n"; } } # # installdir - takes care of converting the .pod and .pm files in the # current directory to .html files and then installing those. # sub installdir { my($dir, $recurse, $podroot, $splitdirs, $ignore) = @_; my @dirlist; # directories to recurse on my @podlist; # .pod files to install my @pmlist; # .pm files to install # should files in this directory get an index? my $doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1); opendir(DIR, "$podroot/$dir") || die "$0: error opening directory $podroot/$dir: $!\n"; while(readdir DIR) { no_upwards($_) or next; my $is_dir = -d "$podroot/$dir/$_"; next if $is_dir and not $recurse; my $target = $is_dir ? \@dirlist : s/\.pod$// ? \@podlist : s/\.pm$// ? \@pmlist : undef ; push @$target, "$dir/$_" if $target; } closedir(DIR); if ($^O eq 'VMS') { s/\.dir$//i for @dirlist } # recurse on all subdirectories we kept track of foreach $dir (@dirlist) { installdir($dir, $recurse, $podroot, $splitdirs, $ignore); } # install all the pods we found foreach my $pod (@podlist) { # check if we should ignore it. next if $pod =~ m(/t/); # comes from a test file next if grep($_ eq "$pod.pod", @$ignore); # check if a .pm files exists too if (grep($_ eq $pod, @pmlist)) { print "$0: Warning both '$podroot/$pod.pod' and " . "'$podroot/$pod.pm' exist, using pod\n"; push(@ignore, "$pod.pm"); } runpod2html("$pod.pod", $doindex); } # install all the .pm files we found foreach my $pm (@pmlist) { # check if we should ignore it. next if $pm =~ m(/t/); # comes from a test file next if grep($_ eq "$pm.pm", @ignore); runpod2html("$pm.pm", $doindex); } } # # runpod2html - invokes pod2html to convert a .pod or .pm file to a .html # file. # sub runpod2html { my($pod, $doindex) = @_; my($html, $i, $dir, @dirs); $html = $pod; $html =~ s/\.(pod|pm)$/.html/g; # make sure the destination directories exist @dirs = split("/", $html); $dir = "$htmldir/"; for ($i = 0; $i < $#dirs; $i++) { if (! -d "$dir$dirs[$i]") { mkdir("$dir$dirs[$i]", 0755) || die "$0: error creating directory $dir$dirs[$i]: $!\n"; } $dir .= "$dirs[$i]/"; } # invoke pod2html print "$podroot/$pod => $htmldir/$html\n" if $verbose; Pod::Html::pod2html( "--htmldir=$htmldir", "--htmlroot=$htmlroot", "--podpath=".join(":", @podpath), "--podroot=$podroot", "--header", ($doindex ? "--index" : "--noindex"), "--" . ($recurse ? "" : "no") . "recurse", "--infile=$podroot/$pod", "--outfile=$htmldir/$html"); die "$0: error running $pod2html: $!\n" if $?; }