X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/de0d1a7847c16bea152243fdffd9a1bc0e6d8f8a..3d460042b1251a4b5e3b583fa6be358554dd3bcc:/installhtml?ds=sidebyside diff --git a/installhtml b/installhtml old mode 100755 new mode 100644 index 84cabee..75d6adc --- a/installhtml +++ b/installhtml @@ -1,11 +1,13 @@ -#!/usr/bin/perl -w +#!./perl -Ilib -w +# This file should really be extracted from a .PL file + +use strict; use Config; # for config options in the makefile +use File::Spec::Functions qw(rel2abs no_upwards); use Getopt::Long; # for command-line parsing use Cwd; -use Pod::Html; - -umask 022; +use Pod::Html 'anchorify'; =head1 NAME @@ -16,7 +18,7 @@ installhtml - converts a collection of POD pages to HTML format. installhtml [--help] [--podpath=:...:] [--podroot=] [--htmldir=] [--htmlroot=] [--norecurse] [--recurse] [--splithead=,...,] [--splititem=,...,] - [--libpods=,...,] [--verbose] + [--ignore=,...,] [--verbose] =head1 DESCRIPTION @@ -32,15 +34,20 @@ pages found in the perl distribution. 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/.'. +Default is 'podroot/.'. -=item B<--podroot> POD search path base directory +=item B<--recurse> recurse on subdirectories -The base directory to search for all .pod and .pm files to be converted. -Default is current directory. +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 @@ -50,29 +57,29 @@ 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<--recurse> recurse on subdirectories - -Whether or not to convert all .pm and .pod files found in subdirectories -too. Default is to not recurse. +a URL. The default is '/'. =item B<--splithead> POD files to split on =head directive -Colon-separated list of pod files to split by the =head directive. These -files should have names specified relative to podroot. +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 -Colon-separated list of all pod files to split by the =item directive. -I does not do the actual split, rather it invokes I -to do the dirty work. As with --splithead, these files should have names -specified relative to podroot. +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 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<--libpods> library PODs for LEE links +=item B<--ignore> files to be ignored -Colon-separated list of "library" pod files. This is the same list that -will be passed to pod2html when any pod is converted. +Comma-separated of files that shouldn't be installed, given relative +to podroot. =item B<--verbose> verbose output @@ -86,28 +93,27 @@ 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.pod \ - --splititem=pod/perlfunc \ - --libpods=perlfunc:perlguts:perlvar:perlrun:perlop \ - --recurse \ - --verbose + --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 -=head1 TODO - =cut +my $usage; + $usage =<:...: --podroot= --htmldir= --htmlroot= --norecurse --recurse --splithead=,..., --splititem=,..., - --libpods=,..., --verbose + --ignore=,..., --verbose --help - this message --podpath - colon-separated list of directories containing .pod and @@ -115,12 +121,9 @@ Usage: $0 --help --podpath=:...: --podroot= --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). + to the filesystem (\$podroot/html by default). --htmlroot - http-server base directory from which all relative paths in podpath stem (default is /). - --libpods - comma-separated list of files to search for =item pod - directives in as targets of C<> and implicit links (empty - by default). --norecurse - don't recurse on those subdirectories listed in podpath. (default behavior). --recurse - recurse on those subdirectories listed in podpath @@ -129,13 +132,16 @@ Usage: $0 --help --podpath=:...: --podroot= of a pod =head[1-6] directive. --splititem - comma-separated list of .pod or .pm files to split using splitpod. - --splitpod - where the program splitpod can be found (\$podroot/pod by - default). + --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 -@libpods = (); +my (@podpath, $podroot, $htmldir, $htmlroot, $recurse, @splithead, + @splititem, $splitpod, $verbose, $pod2html, @ignore); + @podpath = ( "." ); # colon-separated list of directories containing .pod # and .pm files to be converted. $podroot = "."; # assume the pods we want are here @@ -146,19 +152,26 @@ $recurse = 0; # default behavior @splititem = (); # don't split any files by default $splitpod = ""; # nothing for now. -$verbose = 0; # whether or not to print debugging info +$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]); } + +use vars qw( %Options ); # parse the command-line -$result = GetOptions( qw( +my $result = GetOptions( \%Options, qw( help podpath=s podroot=s htmldir=s htmlroot=s - libpods=s + ignore=s recurse! splithead=s splititem=s @@ -184,38 +197,38 @@ $splitpod = "$podroot/pod" unless $splitpod; # ignored in the conversion process. these are files that have been # process by splititem or splithead and should not be converted as a # result. -@ignore = (); - +my @splitdirs; -# split pods. its important to do this before convert ANY pods because -# it may effect some of the links +# 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); +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 $dir (@podpath) { +foreach my $dir (@podpath) { installdir($dir, $recurse, $podroot, \@splitdirs, \@ignore); } # now go through and create master indices for each pod we split -foreach $dir (@splititem) { +foreach my $dir (@splititem) { print "creating index $htmldir/$dir.html\n" if $verbose; create_index("$htmldir/$dir.html", "$htmldir/$dir"); } -foreach $dir (@splithead) { +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; - $file = "$htmldir/$1"; + my $file = "$htmldir/$1"; print "creating index $file.html\n" if $verbose; # read in everything until what would have been the first =head @@ -223,18 +236,23 @@ foreach $dir (@splithead) { open(H, "<$file.html") || die "$0: error opening $file.html for input: $!\n"; $/ = ""; - @data = (); + my @data = (); while () { - last if /NAME=/; - s,HREF="#(.*)">,HREF="$file/$1.html">,g; + last if /name="name"/i; + $_ =~ s{href="#(.*)">}{ + my $url = "$pod/$1.html" ; + $url = Pod::Html::relativize_url( $url, "$file.html" ) + if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' ); + "href=\"$url\">" ; + }egi; push @data, $_; - } + } close(H); - # now rewrite the file + # now rewrite the file open(H, ">$file.html") || die "$0: error opening $file.html for output: $!\n"; - print H "@data\n"; + print H "@data", "\n"; close(H); } @@ -248,35 +266,36 @@ sub usage { sub parse_command_line { - usage() if defined $opt_help; - $opt_help = ""; # make -w shut up + usage() if defined $Options{help}; + $Options{help} = ""; # make -w shut up # list of directories - @podpath = split(":", $opt_podpath) if defined $opt_podpath; + @podpath = split(":", $Options{podpath}) if defined $Options{podpath}; # lists of files - @splithead = split(",", $opt_splithead) if defined $opt_splithead; - @splititem = split(",", $opt_splititem) if defined $opt_splititem; - @libpods = split(",", $opt_libpods) if defined $opt_libpods; + @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}; - $htmldir = $opt_htmldir if defined $opt_htmldir; - $htmlroot = $opt_htmlroot if defined $opt_htmlroot; - $podroot = $opt_podroot if defined $opt_podroot; - $splitpod = $opt_splitpod if defined $opt_splitpod; + $recurse = $Options{recurse} if defined $Options{recurse}; + $verbose = $Options{verbose} if defined $Options{verbose}; - $recurse = $opt_recurse if defined $opt_recurse; - $verbose = $opt_verbose if defined $opt_verbose; + @ignore = map "$podroot/$_", split(",", $Options{ignore}) if defined $Options{ignore}; } sub create_index { my($html, $dir) = @_; - my(@files, @filedata, @index, $file); + (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"; - @files = sort(grep(/\.html$/, readdir(DIR))); + my @files = sort(grep(/\.html?$/, readdir(DIR))); closedir(DIR); open(HTML, ">$html") || @@ -285,31 +304,28 @@ sub create_index { # 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 $file (@files) { - $/ = ""; + foreach my $file (@files) { - open(IN, "<$dir/$file") || - die "$0: error opening $dir/$file for input: $!\n"; - @filedata = ; - close(IN); + 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 - ($name) = grep(/NAME=/, @filedata); - $name =~ m,/H1>\s(\S+)\s[\s-]*(.*?)\s*$,sm; - print HTML qq(); - print HTML "
$1
$2\n" if defined $1; -# print HTML qq($1
\n") if defined $1; - - next; - - @index = grep(/.*/s, - @filedata); - for (@index) { - s/(\s*\s*)/$2/s; - s,#,$dir/$file#,g; - # print HTML "$_\n"; - print HTML "$_\n

\n"; + 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= "$pod/$file" ; + if ( ! defined $Options{htmlroot} || $Options{htmlroot} eq '' ) { + $url = Pod::Html::relativize_url( "$pod/$file", $html ) ; } + + print HTML qq(
); + print HTML "$lcp1
$lcp2
\n"; } print HTML "
\n"; @@ -326,7 +342,7 @@ sub split_on_head { foreach $pod (@splithead) { # figure out the directory name and filename $pod =~ s,^([^/]*)$,/$1,; - $pod =~ m,(.*?)/(.*?)(\.pod)?$,; + $pod =~ m,(.*)/(.*?)(\.pod)?$,; $dirname = $1; $filename = "$2.pod"; @@ -346,10 +362,12 @@ sub split_on_item { print "splitting files by item.\n" if $verbose && $#splititem >= 0; $pwd = getcwd(); - foreach $pod (@splititem) { + 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)?$,; + $pod =~ m,(.*)/(.*?)(\.pod)?$,; $dirname = "$1/$2"; $filename = "$2.pod"; @@ -364,7 +382,11 @@ sub split_on_item { } chdir("$podroot/$dirname") || die "$0: error changing to directory $podroot/$dirname: $!\n"; - system("./splitpod", "../$filename"); + 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); } @@ -402,15 +424,15 @@ sub splitpod { # create list of =head[1-6] sections so that we can rewrite # L<> links as necessary. - %heads = (); + my %heads = (); foreach $i (0..$#poddata) { - $heads{htmlize($1)} = 1 if $poddata[$i] =~ /=head[1-6]\s+(.*)/; + $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 - $dir = $pod; + my $dir = $pod; $dir =~ s/\.pod//g; push(@$splitdirs, "$poddir/$dir"); mkdir("$poddir/$dir", 0755) || @@ -436,15 +458,15 @@ sub splitpod { # determine an appropriate filename (this must correspond with # what pod2html will try and guess) # $poddata[$i] =~ /^\s*=head[1-6]\s+(.*)/; - $file = "$dir/" . htmlize($section) . ".pod"; + $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{htmlize($1)} ? "L<$dir/$1>" : "L<$1>" - ,ge; + 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; @@ -463,56 +485,58 @@ sub splitpod { # sub installdir { my($dir, $recurse, $podroot, $splitdirs, $ignore) = @_; - my(@dirlist, @podlist, @pmlist, $doindex); - @dirlist = (); # directories to recurse on - @podlist = (); # .pod files to install - @pmlist = (); # .pm files to install + 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? - $doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1); + my $doindex = (grep($_ eq "$podroot/$dir", @$splitdirs) ? 0 : 1); opendir(DIR, "$podroot/$dir") || die "$0: error opening directory $podroot/$dir: $!\n"; - # find the directories to recurse on - @dirlist = map { "$dir/$_" } - grep(-d "$podroot/$dir/$_" && !/^\.{1,2}/, readdir(DIR)) if $recurse; - rewinddir(DIR); - - # find all the .pod files within the directory - @podlist = map { /^(.*)\.pod$/; "$dir/$1" } - grep(! -d "$podroot/$dir/$_" && /\.pod$/, readdir(DIR)); - rewinddir(DIR); - - # find all the .pm files within the directory - @pmlist = map { /^(.*)\.pm$/; "$dir/$1" } - grep(! -d "$podroot/$dir/$_" && /\.pm$/, readdir(DIR)); + 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 $pod (@podlist) { + foreach my $pod (@podlist) { # check if we should ignore it. - next if grep($_ eq "$podroot/$pod.pod", @$ignore); + 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.pm", @pmlist)) { - print "$0: Warning both `$podroot/$pod.pod' and " - . "`$podroot/$pod.pm' exist, using pod\n"; + 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 $pm (@pmlist) { + 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); @@ -544,17 +568,14 @@ sub runpod2html { # invoke pod2html print "$podroot/$pod => $htmldir/$html\n" if $verbose; -#system("./pod2html", - Pod::Html'pod2html( - #Pod::Html'pod2html($pod2html, + Pod::Html::pod2html( + "--htmldir=$htmldir", "--htmlroot=$htmlroot", "--podpath=".join(":", @podpath), - "--podroot=$podroot", "--netscape", + "--podroot=$podroot", + "--header", ($doindex ? "--index" : "--noindex"), "--" . ($recurse ? "" : "no") . "recurse", - ($#libpods >= 0) ? "--libpods=" . join(":", @libpods) : "", "--infile=$podroot/$pod", "--outfile=$htmldir/$html"); die "$0: error running $pod2html: $!\n" if $?; } - -sub htmlize { htmlify(0, @_) }