X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/385588b3949e695a02c8ea1dd00fe789d6044de3..fca1d8b34fac5a740ae67bc3b873bc01cd76a8a9:/pod/pod2html.PL diff --git a/pod/pod2html.PL b/pod/pod2html.PL index 602a866..366dc16 100644 --- a/pod/pod2html.PL +++ b/pod/pod2html.PL @@ -2,6 +2,7 @@ use Config; use File::Basename qw(&basename &dirname); +use Cwd; # List explicitly here the variables you want Configure to # generate. Metaconfig only looks for shell variables, so you @@ -12,6 +13,7 @@ use File::Basename qw(&basename &dirname); # This forces PL files to create target in same directory as PL file. # This is so that make depend always knows where to find PL derivatives. +$origdir = cwd; chdir dirname($0); $file = basename($0, '.PL'); $file .= '.com' if $^O eq 'VMS'; @@ -32,522 +34,150 @@ $Config{startperl} # In the following, perl variables are not expanded during extraction. print OUT <<'!NO!SUBS!'; +=pod -# -# pod2html - convert pod format to html -# Version 1.15 -# usage: pod2html [podfiles] -# Will read the cwd and parse all files with .pod extension -# if no arguments are given on the command line. -# -# Many helps, suggestions, and fixes from the perl5 porters, and all over. -# Bill Middleton - wjm@metronet.com -# -# Please send patches/fixes/features to me -# -# -# -*RS = */; -*ERRNO = *!; - -################################################################################ -# Invoke with various levels of debugging possible -################################################################################ -while ($ARGV[0] =~ /^-d(.*)/) { - shift; - $Debug{ lc($1 || shift) }++; -} - -# ck for podnames on command line -while ($ARGV[0]) { - push(@Pods,shift); -} - -################################################################################ -# CONFIGURE -# -# The beginning of the url for the anchors to the other sections. -# Edit $type to suit. It's configured for relative url's now. -# Other possibilities are: -# $type = '; - close($podfh); - $RS = "\n"; - - $all[0] =~ s/^=//; - for (@all) { s/=$// } - $Podnames{$pod} = 1; - $in_list = 0; - $html = $pod.".html"; - if ($count) { # give us a html and rcs header - open(HTML,">$html") || die "can't create $html: $ERRNO"; - print HTML '',"\n",'',"\n"; - print HTML "
" unless $NO_NS; - print HTML "$pod"; - print HTML "
" unless $NO_NS; - print HTML "\n\n"; - } - for ($i = 0; $i <= $#all; $i++) { # decide what to do with each chunk - $all[$i] =~ /^(\w+)\s*(.*)\n?([^\0]*)$/ ; - ($cmd, $title, $rest) = ($1,$2,$3); - if ($cmd eq "item") { - if ($count ) { # producing html - do_list("over",$all[$i],\$in_list,\$depth) unless $depth; - do_item($title,$rest,$in_list); - } - else { - # scan item - scan_thing("item",$title,$pod); - } - } - elsif ($cmd =~ /^head([12])/) { - $num = $1; - if ($count) { # producing html - do_hdr($num,$title,$rest,$depth); - } - else { - # header scan - scan_thing($cmd,$title,$pod); # skip head1 - } - } - elsif ($cmd =~ /^over/) { - $count and $depth and do_list("over",$all[$i+1],\$in_list,\$depth); - } - elsif ($cmd =~ /^back/) { - if ($count) { # producing html - ($depth) or next; # just skip it - do_list("back",$all[$i+1],\$in_list,\$depth); - do_rest($title.$rest); - } - } - elsif ($cmd =~ /^cut/) { - next; - } - elsif ($cmd =~ /^for/) { # experimental pragma html - if ($count) { # producing html - if ($title =~ s/^html//) { - $in_html =1; - do_rest($title.$rest); - } - } - } - elsif ($cmd =~ /^begin/) { # experimental pragma html - if ($count) { # producing html - if ($title =~ s/^html//) { - print HTML $title,"\n",$rest; - } - elsif ($title =~ /^end/) { - next; - } - } - } - elsif ($Debug{"misc"}) { - warn("unrecognized header: $cmd"); - } - } - # close open lists without '=back' stmts - if ($count) { # producing html - while ($depth) { - do_list("back",$all[$i+1],\$in_list,\$depth); - } - print HTML "\n\n\n"; - } - } -} - -sub do_list{ # setup a list type, depending on some grok logic - my($which,$next_one,$list_type,$depth) = @_; - my($key); - if ($which eq "over") { - unless ($next_one =~ /^item\s+(.*)/) { - warn "Bad list, $1\n" if $Debug{"misc"}; - } - $key = $1; - - if ($key =~ /^1\.?/) { - $$list_type = "OL"; - } elsif ($key =~ /\*\s*$/) { - $$list_type = "UL"; - } elsif ($key =~ /\*?\s*\w/) { - $$list_type = "DL"; - } else { - warn "unknown list type for item $key" if $Debug{"misc"}; - } - - print HTML qq{\n}; - print HTML $$list_type eq 'DL' ? qq{
} : qq{<$$list_type>}; - $$depth++; - } - elsif ($which eq "back") { - print HTML qq{\n\n}; - $$depth--; - } -} - -sub do_hdr{ # headers - my($num,$title,$rest,$depth) = @_; - print HTML qq{

\n} if $num == 1; - process_thing(\$title,"NAME"); - print HTML qq{\n }; - print HTML $title; - print HTML qq{\n}; - do_rest($rest); -} - -sub do_item{ # list items - my($title,$rest,$list_type) = @_; - my $bullet_only = $title eq '*' and $list_type eq 'UL'; - process_thing(\$title,"NAME"); - if ($list_type eq "DL") { - print HTML qq{\n
\n}; - print HTML $title; - print HTML qq{\n\n}; - print HTML qq{
\n}; - } - else { - print HTML qq{\n
  • }; - unless ($bullet_only or $list_type eq "OL") { - print HTML $title,"\n"; - } - } - do_rest($rest); -} - -sub do_rest{ # the rest of the chunk handled here - my($rest) = @_; - my(@lines,$p,$q,$line,,@paras,$inpre); - @paras = split(/\n\n\n*/,$rest); - for ($p = 0; $p <= $#paras; $p++) { - $paras[$p] =~ s/^\n//mg; - @lines = split(/\n/,$paras[$p]); - if ($in_html) { # handle =for html paragraphs - print HTML $paras[0]; - $in_html = 0; - next; - } - elsif ($lines[0] =~ /^\s+\w*\t.*/) { # listing or unordered list - print HTML qq{
      }; - foreach $line (@lines) { - ($line =~ /^\s+(\w*)\t(.*)/) && (($key,$rem) = ($1,$2)); - print HTML defined($Podnames{$key}) - ? "
    • $type$key.html\">$key<\/A>\t$rem
      • \n" - : "
    • $line
      • \n"; - } - print HTML qq{
    \n}; - } - elsif ($lines[0] =~ /^\s/) { # preformatted code - if ($paras[$p] =~/>>|<\n}; - $inpre=1; - } - else { # Still cant beat XMP. Yes, I know - print HTML qq{\n\n}; # it's been obsoleted... suggestions? - $inpre = 0; - } - while (defined($paras[$p])) { - @lines = split(/\n/,$paras[$p]); - foreach $q (@lines) { # mind your p's and q's here :-) - if ($paras[$p] =~ />>|<</) { - if ($inpre) { - process_thing(\$q,"HTML"); - } - else { - print HTML qq{\n\n}; - print HTML qq{
    \n};
-			    $inpre=1;
-			    process_thing(\$q,"HTML");
-			}
-		    }
-		    1 while $q =~  s/\t+/' 'x (length($&) * 8 - length($`) % 8)/e;
-		    print HTML  $q,"\n";
-		}
-		last if $paras[$p+1] !~ /^\s/;
-		$p++;
-	    }
-	    print HTML ($inpre==1) ? (qq{\n
    \n}) : (qq{\n\n}); - } - else { # other text - @lines = split(/\n/,$paras[$p]); - foreach $line (@lines) { - process_thing(\$line,"HTML"); - print HTML qq{$line\n}; - } - } - print HTML qq{

    }; - } -} - -sub process_thing{ # process a chunk, order important - my($thing,$htype) = @_; - pre_escapes($thing); - find_refs($thing,$htype); - post_escapes($thing); -} - -sub scan_thing{ # scan a chunk for later references - my($cmd,$title,$pod) = @_; - $_ = $title; - s/\n$//; - s/E<(\d+)>/&#$1;/g; - s/E<(.*?)>/&$1;/g; - # remove any formatting information for the headers - s/[SFCBI]<(.*?)>/$1/g; - # the "don't format me" thing - s/Z<>//g; - if ($cmd eq "item") { - /^\*/ and return; # skip bullets - /^\d+\./ and return; # skip numbers - s/(-[a-z]).*/$1/i; - trim($_); - return if defined $A->{$pod}->{"Items"}->{$_}; - $A->{$pod}->{"Items"}->{$_} = gensym($pod, $_); - $A->{$pod}->{"Items"}->{(split(' ',$_))[0]}=$A->{$pod}->{"Items"}->{$_}; - Debug("items", "item $_"); - if (!/^-\w$/ && /([%\$\@\w]+)/ && $1 ne $_ - && !defined($A->{$pod}->{"Items"}->{$_}) && ($_ ne $1)) - { - $A->{$pod}->{"Items"}->{$1} = $A->{$pod}->{"Items"}->{$_}; - Debug("items", "item $1 REF TO $_"); - } - if ( m{^(tr|y|s|m|q[qwx])/.*[^/]} ) { - my $pf = $1 . '//'; - $pf .= "/" if $1 eq "tr" || $1 eq "y" || $1 eq "s"; - if ($pf ne $_) { - $A->{$pod}->{"Items"}->{$pf} = $A->{$pod}->{"Items"}->{$_}; - Debug("items", "item $pf REF TO $_"); - } - } - } - elsif ($cmd =~ /^head[12]/) { - return if defined($A->{$pod}->{"Headers"}->{$_}); - $A->{$pod}->{"Headers"}->{$_} = gensym($pod, $_); - Debug("headers", "header $_"); - } - else { - warn "unrecognized header: $cmd" if $Debug; - } -} - - -sub picrefs { - my($char, $bigkey, $lilkey,$htype) = @_; - my($key,$ref,$podname); - for $podname ($pod,@inclusions) { - for $ref ( "Items", "Headers" ) { - if (defined $A->{$podname}->{$ref}->{$bigkey}) { - $value = $A->{$podname}->{$ref}->{$key = $bigkey}; - Debug("subs", "bigkey is $bigkey, value is $value\n"); - } - elsif (defined $A->{$podname}->{$ref}->{$lilkey}) { - $value = $A->{$podname}->{$ref}->{$key = $lilkey}; - return "" if $lilkey eq ''; - Debug("subs", "lilkey is $lilkey, value is $value\n"); - } - } - if (length($key)) { - ($pod2, $num) = $value =~ /^(.*)_(\S+_\d+)$/; - if ($htype eq "NAME") { - return "\n\n$bigkey\n" - } - else { - return "\n$type$pod2.html\#".$value."\">$bigkey<\/A>\n"; - } - } - } - if ($char =~ /[IF]/) { - return "$bigkey"; - } elsif ($char =~ /C/) { - return "$bigkey"; - } else { - return "$bigkey"; - } -} - -sub find_refs { - my($thing,$htype) = @_; - my($orig) = $$thing; - # LREF: a manpage(3f) we don't know about - for ($$thing) { - #s:L<([a-zA-Z][^\s\/]+)(\([^\)]+\))>:the I<$1>$2 manpage:g; - s@(\S+?://\S*[^.,;!?\s])@noremap(qq{$1})@ge; - s,([a-z0-9_.-]+\@([a-z0-9_-]+\.)+([a-z0-9_-]+)),noremap(qq{$1}),gie; - s/L<([^>]*)>/lrefs($1,$htype)/ge; - s/([CIBF])<(\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge; - s/(S)<([^\/]\W*?(-?\w*).*?)>/picrefs($1, $2, $3, $htype)/ge; - s/((\w+)\(\))/picrefs("I", $1, $2,$htype)/ge; - s/([\$\@%](?!&[gl]t)([\w:]+|\W\b))/varrefs($1,$htype)/ge; - } - if ($$thing eq $orig && $htype eq "NAME") { - $$thing = picrefs("I", $$thing, "", $htype); - } - -} - -sub lrefs { - my($page, $item) = split(m#/#, $_[0], 2); - my($htype) = $_[1]; - my($podname); - my($section) = $page =~ /\((.*)\)/; - my $selfref; - if ($page =~ /^[A-Z]/ && $item) { - $selfref++; - $item = "$page/$item"; - $page = $pod; - } elsif (!$item && $page =~ /[^a-z\-]/ && $page !~ /^\$.$/) { - $selfref++; - $item = $page; - $page = $pod; - } - $item =~ s/\(\)$//; - if (!$item) { - if (!defined $section && defined $Podnames{$page}) { - return "\n$type$page.html\">\nthe $page manpage<\/A>\n"; - } else { - (warn "Bizarre entry $page/$item") if $Debug; - return "the $_[0] manpage\n"; - } - } - - if ($item =~ s/"(.*)"/$1/ || ($item =~ /[^\w\/\-]/ && $item !~ /^\$.$/)) { - $text = "$item"; - $ref = "Headers"; - } else { - $text = "$item"; - $ref = "Items"; - } - for $podname ($pod, @inclusions) { - undef $value; - if ($ref eq "Items") { - if (defined($value = $A->{$podname}->{$ref}->{$item})) { - ($pod2,$num) = split(/_/,$value,2); - return (($pod eq $pod2) && ($htype eq "NAME")) - ? "\n\n$text\n" - : "\n$type$pod2.html\#".$value."\">$text<\/A>\n"; - } - } - elsif ($ref eq "Headers") { - if (defined($value = $A->{$podname}->{$ref}->{$item})) { - ($pod2,$num) = split(/_/,$value,2); - return (($pod eq $pod2) && ($htype eq "NAME")) - ? "\n\n$text\n" - : "\n$type$pod2.html\#".$value."\">$text<\/A>\n"; - } - } - } - warn "No $ref reference for $item (@_)" if $Debug; - return $text; -} - -sub varrefs { - my ($var,$htype) = @_; - for $podname ($pod,@inclusions) { - if ($value = $A->{$podname}->{"Items"}->{$var}) { - ($pod2,$num) = split(/_/,$value,2); - Debug("vars", "way cool -- var ref on $var"); - return (($pod eq $pod2) && ($htype eq "NAME")) # INHERIT $_, $pod - ? "\n\n$var\n" - : "\n$type$pod2.html\#".$value."\">$var<\/A>\n"; - } - } - Debug( "vars", "bummer, $var not a var"); - return "$var"; -} - -sub gensym { - my ($podname, $key) = @_; - $key =~ s/\s.*//; - ($key = lc($key)) =~ tr/a-z/_/cs; - my $name = "${podname}_${key}_0"; - $name =~ s/__/_/g; - while ($sawsym{$name}++) { - $name =~ s/_?(\d+)$/'_' . ($1 + 1)/e; - } - return $name; -} - -sub pre_escapes { # twiddle these, and stay up late :-) - my($thing) = @_; - for ($$thing) { - s/([\200-\377])/noremap("&#".ord($1).";")/ge; - s/"(.*?)"/``$1''/gs; - s/&/noremap("&")/ge; - s/</\&#$1\;/g; # embedded numeric special - s/E<([^\/][^<>]*)>/\&$1\;/g; # embedded special - } -} -sub noremap { # adding translator for hibit chars soon - my $hide = $_[0]; - $hide =~ tr/\000-\177/\200-\377/; - $hide; -} - - -sub post_escapes { - my($thing) = @_; - for ($$thing) { - s/([^GM])>>/$1\>\;\>\;/g; - s/([^D][^"MGA])>/$1\>\;/g; - tr/\200-\377/\000-\177/; - } -} - -sub Debug { - my $level = shift; - print STDERR @_,"\n" if $Debug{$level}; -} - -sub dumptable { - my $t = shift; - print STDERR "TABLE DUMP $t\n"; - foreach $k (sort keys %$t) { - printf STDERR "%-20s <%s>\n", $t->{$k}, $k; - } -} -sub trim { - for (@_) { - s/^\s+//; - s/\s\n?$//; - } -} +=head1 NAME + +pod2html - convert .pod files to .html files + +=head1 SYNOPSIS + + pod2html --help --htmlroot= --infile= --outfile= + --podpath=:...: --podroot= + --libpods=:...: --recurse --norecurse --verbose + --index --noindex --title= + +=head1 DESCRIPTION + +Converts files from pod format (see L) to HTML format. + +=head1 ARGUMENTS + +pod2html takes the following arguments: + +=over 4 + +=item help + + --help + +Displays the usage message. + +=item htmlroot + + --htmlroot=name + +Sets the base URL for the HTML files. When cross-references are made, +the HTML root is prepended to the URL. + +=item infile + + --infile=name + +Specify the pod file to convert. Input is taken from STDIN if no +infile is specified. + +=item outfile + + --outfile=name + +Specify the HTML file to create. Output goes to STDOUT if no outfile +is specified. + +=item podroot + + --podroot=name + +Specify the base directory for finding library pods. + +=item podpath + + --podpath=name:...:name + +Specify which subdirectories of the podroot contain pod files whose +HTML converted forms can be linked-to in cross-references. + +=item libpods + + --libpods=name:...:name + +List of page names (eg, "perlfunc") which contain linkable C<=item>s. + +=item netscape + + --netscape + +Use Netscape HTML directives when applicable. + +=item nonetscape + + --nonetscape + +Do not use Netscape HTML directives (default). + +=item index + + --index + +Generate an index at the top of the HTML file (default behaviour). + +=item noindex + + --noindex + +Do not generate an index at the top of the HTML file. + + +=item recurse + + --recurse + +Recurse into subdirectories specified in podpath (default behaviour). + +=item norecurse + + --norecurse + +Do not recurse into subdirectories specified in podpath. + +=item title + + --title=title + +Specify the title of the resulting HTML file. + +=item verbose + + --verbose + +Display progress messages. + +=back + +=head1 AUTHOR + +Tom Christiansen, Etchrist@perl.comE. + +=head1 BUGS + +See L for a list of known bugs in the translator. + +=head1 SEE ALSO + +L, L + +=head1 COPYRIGHT + +This program is distributed under the Artistic License. + +=cut + +use Pod::Html; + +pod2html @ARGV; !NO!SUBS! close OUT or die "Can't close $file: $!"; chmod 0755, $file or die "Can't reset permissions for $file: $!\n"; exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':'; +chdir $origdir;