New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
pod2html (Html.pm) - bugfixes and improvements #1023
Comments
From wolfgang.laun@alcatel.at(Note: I'm aware of the ongoing work concerning Brad Appleton's This was inspired by the failure of pod2html (Pod::Html.pm versions 1.01 All of file handling, scanning and caching is still as it was. I've run this on all the pod's from Tk800.015. These look quite good Perl 5.00503/pod/*.pod produce a handy set of HTML files, with many of There seems to be some confusion and/or disagreement on the pod authors' Recognition of URL's in verbatim paragraphs should probably be removed. Bugs fixed: Recognition of preformatted pod paragraphs removed from process_text as Improvements: Links to headers use full text, with only a few chars removed. Likewise, ========== Html.pm =================================================== use Pod::Functions; use Carp; use locale; # make \w work right in non-ASCII lands use strict; use Config; =head1 NAME Pod::Html - module to convert pod files to HTML =head1 SYNOPSIS use Pod::Html; =head1 DESCRIPTION Converts files from pod format (see L<perlpod>) to HTML format. It =head1 ARGUMENTS Pod::Html takes the following arguments: =over 4 =item help --help Displays the usage message. =item htmldir --htmldir=name Sets the directory in which the resulting HTML file is placed. This =item htmlroot --htmlroot=name Sets the base URL for the HTML files. When cross-references are made, =item infile --infile=name Specify the pod file to convert. Input is taken from STDIN if no =item outfile --outfile=name Specify the HTML file to create. Output goes to STDOUT if no outfile =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 =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 css --css=stylesheet Specify the URL of a cascading style sheet. =item verbose --verbose Display progress messages. =item quiet --quiet Don't display I<mostly harmless> warning messages. =back =head1 EXAMPLE pod2html("pod2html", =head1 ENVIRONMENT Uses $Config{pod2html} to setup default options. =head1 AUTHOR Tom Christiansen, E<lt>tchrist@perl.comE<gt>. =head1 SEE ALSO L<perlpod> =head1 COPYRIGHT This program is distributed under the Artistic License. =cut my my @begin_stack = (); # begin/end stack my @libpods = (); # files to search for links from C<> directives my %items_named = (); # for the multiples of the same item in perlfunc sub init_globals { @begin_stack = (); # begin/end stack @libpods = (); # files to search for links from C<> directives @items_seen = (); # These are not reinitialised here but are kept as a cache. # # have a look for all-space lines sub pod2html { init_globals(); $Is83 = 0 if (defined (&Dos::UseLFN) && Dos::UseLFN()); # cache of %pages and %items from last time we ran pod2html #undef $opt_help if defined $opt_help; # parse the command-line parameters # set some variables to their default values if necessary # read the pod a paragraph at a time # scan the pod for =head[1-6] directives and build an index unless($index) { # open the output file # put a title in the HTML file if one wasn't specified } my $block = $header ? <<END_OF_BLOCK : ''; print HTML <<END_OF_HEAD; <BODY> # load/reload/validate/cache %pages and %items # scan the pod for =item directives # put an index at the top of the file. note, if $doindex is 0 we # now convert this file $_ = $poddata[$i]; if (/^=(head[1-6])\s+(.*\S)/s) { # =head[1-6] heading } else { # experimental: check for a paragraph where all lines if( $after_item ){ # finish off any pending directives # link to page index print HTML <<END_OF_TAIL; </HTML> # close the html file warn "Finished\n" if $verbose; ############################################################################## my $usage; # see below $usage =<<END_OF_USAGE; --flush - flushes the item and directory caches. END_OF_USAGE sub parse_command_line { usage("-") if defined $opt_help; # see if the user asked for help $podfile = $opt_infile if defined $opt_infile; @podpath = split(":", $opt_podpath) if defined $opt_podpath; warn "Flushing item and directory caches\n" $htmlroot = $opt_htmlroot if defined $opt_htmlroot; $doindex = $opt_index if defined $opt_index; my $saved_cache_key; sub get_cache { # A first-level cache: my $this_cache_key = cache_key(@cache_key_args); return if $saved_cache_key and $this_cache_key eq $saved_cache_key; # load the cache of %pages and %items if possible. $tests will be # if we didn't succeed in loading the cache then we must (re)build sub cache_key { # $tests = 0; open(CACHE, "<$itemcache") || # is it the same podpath? # is it the same podroot? # load the cache if its good warn "loading item cache\n" if $verbose; warn "scanning for directory cache\n" if $verbose; # is it the same podpath? # is it the same podroot? # load the cache if its good warn "loading directory cache\n" if $verbose; close(CACHE); return 1; # unless($append) { # scan each directory listed in @podpath # scan the pods listed in @libpods for =item directives # if there is a directory then use the .pod and .pm files within it. # scan each .pod and .pm file for =item directives scan_items( \%items, "$dirname/$pod", @poddata); # use the names of files as =item directives too. scan_items( \%items, "$pod", @poddata); chdir($pwd) # cache the item list for later use print CACHE join(":", @podpath) . "\n$podroot\n"; close(CACHE); # cache the directory list for later use print CACHE join(":", @podpath) . "\n$podroot\n"; close(CACHE); # @subdirs = (); opendir(DIR, $dir) || # recurse on the subdirectories if necessary # # here we need local $ignore = 0; $listdepth = 0; # scan for =head directives, note their name, and build an index my $title = depod( $otitle ); while ($which_head != $listdepth) { $index .= "\n" . ("\t" x $listdepth) . "<LI>" . # finish off the lists # get rid of bogus lists $ignore = 1; # restore old value; return $index; # foreach # figure out what kind of item it is. # # figure out the level of the =head if( $listlevel ){ print HTML "<P>\n"; my $name = htmlify( depod( $heading ) ); # sub emit_item_tag($$$){ $EmittedItem = $item; print HTML '<STRONG>'; sub emit_li { # # lots of documents start a list without doing an =over. this is # formatting: insert a paragraph if preceding item has >1 paragraph # remove formatting instructions from the text # all the list variants: } elsif( $text =~ /\A\d+/ ){ # numbered list } else { # definition list # # # close off the list. note, I check to see if $listend[$listlevel] is # clean up item count # # # # # # # insert spaces in place of tabs # convert some special chars to HTML escapes # try and create links for all occurrences of perl.* within # Look for embedded URLs and make them into links. We don't my $urls = '(' . join ('|', qw{ $rest =~ s{ # text should be as it is (verbatim) # sub inIS_text($){ # ## Guessing at func() or [$@%&]*var references in plain text is destined my(@words, $lead, $trail); # convert double-quotes to single-quotes # keep track of leading and trailing white-space # split at space/non-space boundaries # process each word individually #### disabled. either all (including } elsif ($word =~ m,^\w+://\w,) { # put everything back together # sub process_text1($$;$){ if( $func eq 'B' ){ } elsif( $func eq 'C' ){ ## clean-up of the link target ### my $x = $par =~ /[BI]</ ? 'yes' : 'no' ; $res = emit_C( $text, $lev > 1 || ($par =~ /[BI]</) ); } elsif( $func eq 'E' ){ } elsif( $func eq 'F' ){ } elsif( $func eq 'I' ){ } elsif( $func eq 'L' ){ # some L<>'s that shouldn't be: # analyze the contents my( $page, $section, $ident ); # check for link patterns } elsif( } elsif( $par =~ /\s/ ){ # this must be a section with missing quotes } else { # now, either $section or $ident is defined. the convoluted logic RESOLVE: { # warning; show some text. # now we have an URL or just plain code } elsif( $func eq 'S' ){ } elsif( $func eq 'X' ){ } elsif( $func eq 'Z' ){ } else { } # # # need HTML-safe text if( defined( $url ) && # # # # check if we know that this is a section in this page $page83=dosify($page); } # if there is a directory by the name of the page, then assume that an # since there is no directory by the name of the page, the section will # check if there is a .pod with the page name if ($link) { } else { # my ($dest_volume,$dest_directory,$dest_file) = my ($source_volume,$source_directory,$source_file) = my $rel_path = '' ; if ( $rel_path ne '' && return $rel_path ; # my $fid = fragment_id( $item ); if( defined( $page ) ){ # Do we take it? Item could be a section! } else { # if there was a pod file that we found earlier with an appropriate # Here, we take advantage of the knowledge that $htmlfileurl confess "url has space: $url" if $url =~ /"[^"]*\s[^"]*"/; # my $source = URI::file->new_abs($source_file); # # # sub depod($){ sub depod1( # # a variable name? # some pattern matching operator? # fancy stuff... like "do { }" # honour the perlfunc manpage: func [PAR[,[ ]PAR]...] # text? normalize! # BEGIN { 1; Perl Info
|
From [Unknown Contact. See original ticket]Wolfgang Laun <Wolfgang.Laun@alcatel.at> writes:
No it doesn't. It uses HTML::Element which happens to be bundled with some other I seem to recall us at the conference discussing doing a pod2xml -- |
Migrated from rt.perl.org#1974 (status was 'resolved')
Searchable as RT1974$
The text was updated successfully, but these errors were encountered: