diff options
Diffstat (limited to 'gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple')
26 files changed, 579 insertions, 169 deletions
diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm index 9917898cff7..c17cfd0ad51 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm @@ -23,7 +23,7 @@ use integer; # vroom! use strict; use Carp (); use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; #use constant DEBUG => 7; BEGIN { require Pod::Simple; @@ -42,6 +42,7 @@ sub parse_lines { # Usage: $parser->parse_lines(@lines) my $code_handler = $self->{'code_handler'}; my $cut_handler = $self->{'cut_handler'}; + my $wl_handler = $self->{'whiteline_handler'}; $self->{'line_count'} ||= 0; my $scratch; @@ -88,8 +89,8 @@ sub parse_lines { # Usage: $parser->parse_lines(@lines) DEBUG > 2 and print "First line: [$source_line]\n"; if( ($line = $source_line) =~ s/^\xEF\xBB\xBF//s ) { - DEBUG and print "UTF-8 BOM seen. Faking a '=encode utf8'.\n"; - $self->_handle_encoding_line( "=encode utf8" ); + DEBUG and print "UTF-8 BOM seen. Faking a '=encoding utf8'.\n"; + $self->_handle_encoding_line( "=encoding utf8" ); $line =~ tr/\n\r//d; } elsif( $line =~ s/^\xFE\xFF//s ) { @@ -191,7 +192,12 @@ sub parse_lines { # Usage: $parser->parse_lines(@lines) # TODO: add to docs: Note: this may cause cuts to be processed out # of order relative to pods, but in order relative to code. - } elsif($line =~ m/^\s*$/s) { # it's a blank line + } elsif($line =~ m/^(\s*)$/s) { # it's a blank line + if (defined $1 and $1 =~ /[^\S\r\n]/) { # it's a white line + $wl_handler->(map $_, $line, $self->{'line_count'}, $self) + if $wl_handler; + } + if(!$self->{'start_of_pod_block'} and @$paras and $paras->[-1][0] eq '~Verbatim') { DEBUG > 1 and print "Saving blank line at line ${$self}{'line_count'}\n"; push @{$paras->[-1]}, $line; @@ -519,7 +525,7 @@ sub _ponder_paragraph_buffer { # don't require any lookahead, but all others (bullets # and numbers) do. -# TODO: winge about many kinds of directives in non-resolving =for regions? +# TODO: whinge about many kinds of directives in non-resolving =for regions? # TODO: many? like what? =head1 etc? $para = shift @$paras; @@ -592,7 +598,8 @@ sub _ponder_paragraph_buffer { if($para_type eq '=item') { my $over; - unless(@$curr_open and ($over = $curr_open->[-1])->[0] eq '=over') { + unless(@$curr_open and + $over = (grep { $_->[0] eq '=over' } @$curr_open)[-1]) { $self->whine( $para->[1]{'start_line'}, "'=item' outside of any '=over'" @@ -917,7 +924,7 @@ sub _ponder_begin { $para->[1]{'title'} = $title if ($title); $para->[1]{'target'} = $target; # without any ':' $content = $target; # strip off the title - + $content =~ s/^:!/!:/s; my $neg; # whether this is a negation-match $neg = 1 if $content =~ s/^!//s; @@ -983,7 +990,7 @@ sub _ponder_end { $content =~ s/^\s+//s; $content =~ s/\s+$//s; DEBUG and print "Ogling '=end $content' directive\n"; - + unless(length($content)) { $self->whine( $para->[1]{'start_line'}, @@ -1039,7 +1046,7 @@ sub _ponder_end { # what's that for? $self->{'content_seen'} ||= 1; - $self->_handle_element_end( my $scratch = 'for' ); + $self->_handle_element_end( my $scratch = 'for', $para->[1]); } DEBUG > 1 and print "Popping $curr_open->[-1][0] $curr_open->[-1][1]{'target'} because of =end $content\n"; pop @$curr_open; @@ -1092,7 +1099,18 @@ sub _ponder_pod { "=pod directives shouldn't be over one line long! Ignoring all " . (@$para - 2) . " lines of content" ) if @$para > 3; - # Content is always ignored. + + # Content ignored unless 'pod_handler' is set + if (my $pod_handler = $self->{'pod_handler'}) { + my ($line_num, $line) = map $_, $para->[1]{'start_line'}, $para->[2]; + $line = $line eq '' ? "=pod" : "=pod $line"; # imitate cut_handler output + $pod_handler->($line, $line_num, $self); + } + + # The surrounding methods set content_seen, so let us remain consistent. + # I do not know why it was not here before -- should it not be here? + # $self->{'content_seen'} ||= 1; + return; } @@ -1105,10 +1123,13 @@ sub _ponder_over { $list_type = $self->_get_initial_item_type($paras->[0]); } elsif($paras->[0][0] eq '=back') { - # Ignore empty lists. TODO: make this an option? - shift @$paras; - return 1; - + # Ignore empty lists by default + if ($self->{'parse_empty_lists'}) { + $list_type = 'empty'; + } else { + shift @$paras; + return 1; + } } elsif($paras->[0][0] eq '~end') { $self->whine( $para->[1]{'start_line'}, @@ -1169,7 +1190,7 @@ sub _ponder_back { #my $over = pop @$curr_open; $self->{'content_seen'} ||= 1; $self->_handle_element_end( my $scratch = - 'over-' . ( (pop @$curr_open)->[1]{'~type'} ) + 'over-' . ( (pop @$curr_open)->[1]{'~type'} ), $para->[1] ); } else { DEBUG > 1 and print "=back found without a matching =over. Stack: (", @@ -1185,7 +1206,8 @@ sub _ponder_back { sub _ponder_item { my ($self,$para,$curr_open,$paras) = @_; my $over; - unless(@$curr_open and ($over = $curr_open->[-1])->[0] eq '=over') { + unless(@$curr_open and + $over = (grep { $_->[0] eq '=over' } @$curr_open)[-1]) { $self->whine( $para->[1]{'start_line'}, "'=item' outside of any '=over'" @@ -1383,7 +1405,7 @@ sub _ponder_Verbatim { for(my $i = 2; $i < @$para; $i++) { foreach my $line ($para->[$i]) { # just for aliasing # Strip indentation. - $line =~ s/^\E$indent// if $indent + $line =~ s/^\Q$indent// if $indent && !($self->{accept_codes} && $self->{accept_codes}{VerbatimFormatted}); while( $line =~ # Sort of adapted from Text::Tabs -- yes, it's hardwired in that @@ -1471,7 +1493,9 @@ sub _closers_for_all_curr_open { $copy[-1] = '' unless defined $copy[-1]; # since =over's don't have targets } - + + $copy[1]{'fake-closer'} = 1; + DEBUG and print "Queuing up fake-o event: ", pretty(\@copy), "\n"; unshift @closers, \@copy; } @@ -1638,6 +1662,10 @@ sub _treelet_from_formatting_codes { my @stack; my @lineage = ($treelet); + my $raw = ''; # raw content of L<> fcode before splitting/processing + # XXX 'raw' is not 100% accurate: all surrounding whitespace is condensed + # into just 1 ' '. Is this the regex's doing or 'raw's? + my $inL = 0; DEBUG > 4 and print "Paragraph:\n$para\n\n"; @@ -1709,7 +1737,13 @@ sub _treelet_from_formatting_codes { } push @lineage, [ substr($1,0,1), {}, ]; # new node object push @{ $lineage[-2] }, $lineage[-1]; - + if ('L' eq substr($1,0,1)) { + $raw = $inL ? $raw.$1 : ''; # reset raw content accumulator + $inL = 1; + } else { + $raw .= $1 if $inL; + } + } elsif(defined $4) { DEBUG > 3 and print "Found apparent complex end-text code \"$3$4\"\n"; # This is where it gets messy... @@ -1743,6 +1777,14 @@ sub _treelet_from_formatting_codes { pop @stack; pop @lineage; + + unless (@stack) { # not in an L if there are no open fcodes + $inL = 0; + if (ref $lineage[-1][-1] && $lineage[-1][-1][0] eq 'L') { + $lineage[-1][-1][1]{'raw'} = $raw + } + } + $raw .= $3.$4 if $inL; } elsif(defined $5) { DEBUG > 3 and print "Found apparent simple end-text code \"$5\"\n"; @@ -1764,10 +1806,21 @@ sub _treelet_from_formatting_codes { push @{ $lineage[-1] }, $5; } + unless (@stack) { # not in an L if there are no open fcodes + $inL = 0; + if (ref $lineage[-1][-1] && $lineage[-1][-1][0] eq 'L') { + $lineage[-1][-1][1]{'raw'} = $raw + } + } + $raw .= $5 if $inL; + } elsif(defined $6) { DEBUG > 3 and print "Found stuff \"$6\"\n"; push @{ $lineage[-1] }, $6; - + $raw .= $6 if $inL; + # XXX does not capture multiplace whitespaces -- 'raw' ends up with + # at most 1 leading/trailing whitespace, why not all of it? + } else { # should never ever ever ever happen DEBUG and print "AYYAYAAAAA at line ", __LINE__, "\n"; @@ -1795,7 +1848,7 @@ sub _treelet_from_formatting_codes { "Unterminated $x sequence", ); } - + return $treelet; } @@ -1911,7 +1964,7 @@ sub pretty { # adopted from Class::Classless # A rather unsubtle method of blowing away all the state information # from a parser object so it can be reused. Provided as a utility for -# backward compatibilty in Pod::Man, etc. but not recommended for +# backward compatibility in Pod::Man, etc. but not recommended for # general use. sub reinit { diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm index 26a60237236..c97267a86ba 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm @@ -9,7 +9,7 @@ use Carp (); use Pod::Simple::Methody (); use Pod::Simple (); use vars qw( @ISA $VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; @ISA = ('Pod::Simple::Methody'); BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG) ? \&Pod::Simple::DEBUG diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm index 1349be32cb6..57733028427 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm @@ -3,7 +3,7 @@ require 5; package Pod::Simple::Debug; use strict; use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; sub import { my($value,$variable); diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm index 91554341e35..5e2d7ebf5ff 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::DumpAsText; -$VERSION = '3.14'; +$VERSION = '3.20'; use Pod::Simple (); BEGIN {@ISA = ('Pod::Simple')} diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm index d83f8d33f55..e43422bbd7c 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::DumpAsXML; -$VERSION = '3.14'; +$VERSION = '3.20'; use Pod::Simple (); BEGIN {@ISA = ('Pod::Simple')} @@ -114,7 +114,7 @@ L<Pod::Simple>. L<Pod::Simple::XMLOutStream> is rather like this class. Pod::Simple::XMLOutStream's output is space-padded in a way that's better for sending to an XML processor (that is, it has -no ignoreable whitespace). But +no ignorable whitespace). But Pod::Simple::DumpAsXML's output is much more human-readable, being (more-or-less) one token per line, with line-wrapping. diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm index b1a75cb4e39..12fad403589 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm @@ -10,7 +10,7 @@ use vars qw( $Doctype_decl $Content_decl ); @ISA = ('Pod::Simple::PullParser'); -$VERSION = '3.14'; +$VERSION = '3.20'; BEGIN { if(defined &DEBUG) { } # no-op @@ -81,7 +81,7 @@ __PACKAGE__->_accessorize( # out of apparently longstanding habit) 'html_css', # URL of CSS file to point to - 'html_javascript', # URL of CSS file to point to + 'html_javascript', # URL of Javascript file to point to 'force_title', # should already be &-escaped 'default_title', # should already be &-escaped @@ -491,8 +491,11 @@ sub _do_middle_main_loop { $name = $self->do_section($name, $token) if defined $name; print $fh "<a "; - print $fh "class='u' href='#___top' title='click to go to top of document'\n" - if $tagname =~ m/^head\d$/s; + if ($tagname =~ m/^head\d$/s) { + print $fh "class='u'", $self->index + ? " href='#___top' title='click to go to top of document'\n" + : "\n"; + } if(defined $name) { my $esc = esc( $self->section_name_tidy( $name ) ); @@ -685,6 +688,8 @@ sub section_escape { sub section_name_tidy { my($self, $section) = @_; + $section =~ s/^\s+//; + $section =~ s/\s+$//; $section =~ tr/ /_/; $section =~ tr/\x00-\x1F\x80-\x9F//d if 'A' eq chr(65); # drop crazy characters $section = $self->unicode_escape_url($section); @@ -897,25 +902,176 @@ TODO =head1 CALLING FROM PERL -TODO make a new object, set any options, and use parse_from_file +=head2 Minimal code + + use Pod::Simple::HTML; + my $p = Pod::Simple::HTML->new; + $p->output_string(\my $html); + $p->parse_file('path/to/Module/Name.pm'); + open my $out, '>', 'out.html' or die "Cannot open 'out.html': $!\n"; + print $out $html; + +=head2 More detailed example + + use Pod::Simple::HTML; + +Set the content type: + + $Pod::Simple::HTML::Content_decl = q{<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >}; + + my $p = Pod::Simple::HTML->new; + +Include a single javascript source: + + $p->html_javascript('http://abc.com/a.js'); + +Or insert multiple javascript source in the header +(or for that matter include anything, thought this is not recommended) + + $p->html_javascript(' + <script type="text/javascript" src="http://abc.com/b.js"></script> + <script type="text/javascript" src="http://abc.com/c.js"></script>'); + +Include a single css source in the header: + + $p->html_css('/style.css'); + +or insert multiple css sources: + $p->html_css(' + <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="http://remote.server.com/jquery.css"> + <link rel="stylesheet" type="text/css" title="pod_stylesheet" href="/style.css">'); + +Tell the parser where should the output go. In this case it will be placed in the $html variable: + + my $html; + $p->output_string(\$html); + +Parse and process a file with pod in it: + + $p->parse_file('path/to/Module/Name.pm'); =head1 METHODS TODO all (most?) accessorized methods +The following variables need to be set B<before> the call to the ->new constructor. + +Set the string that is included before the opening <html> tag: + + $Pod::Simple::HTML::Doctype_decl = qq{<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd">\n}; + +Set the content-type in the HTML head: (defaults to ISO-8859-1) + + $Pod::Simple::HTML::Content_decl = q{<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" >}; + +Set the value that will be ebedded in the opening tags of F, C tags and verbatim text. +F maps to <em>, C maps to <code>, Verbatim text maps to <pre> (Computerese defaults to "") + + $Pod::Simple::HTML::Computerese = ' class="some_class_name'; + +=head2 html_css + +=head2 html_javascript + +=head2 title_prefix + +=head2 title_postfix + +=head2 html_header_before_title + +This includes everything before the <title> opening tag including the Document type +and including the opening <title> tag. The following call will set it to be a simple HTML +file: + + $p->html_header_before_title('<html><head><title>'); + +=head2 html_h_level + +Normally =head1 will become <h1>, =head2 will become <h2> etc. +Using the html_h_level method will change these levels setting the h level +of =head1 tags: + + $p->html_h_level(3); + +Will make sure that =head1 will become <h3> and =head2 will become <h4> etc... + + +=head2 index + +Set it to some true value if you want to have an index (in reality a table of contents) +to be added at the top of the generated HTML. + + $p->index(1); + +=head2 html_header_after_title + +Includes the closing tag of </title> and through the rest of the head +till the opening of the body + + $p->html_header_after_title('</title>...</head><body id="my_id">'); + +=head2 html_footer + +The very end of the document: + + $p->html_footer( qq[\n<!-- end doc -->\n\n</body></html>\n] ); =head1 SUBCLASSING -TODO +Can use any of the methods described above but for further customization +one needs to override some of the methods: + + package My::Pod; + use strict; + use warnings; + + use base 'Pod::Simple::HTML'; + + # needs to return a URL string such + # http://some.other.com/page.html + # #anchor_in_the_same_file + # /internal/ref.html + sub do_pod_link { + # My::Pod object and Pod::Simple::PullParserStartToken object + my ($self, $link) = @_; + + say $link->tagname; # will be L for links + say $link->attr('to'); # + say $link->attr('type'); # will be 'pod' always + say $link->attr('section'); + + # Links local to our web site + if ($link->tagname eq 'L' and $link->attr('type') eq 'pod') { + my $to = $link->attr('to'); + if ($to =~ /^Padre::/) { + $to =~ s{::}{/}g; + return "/docs/Padre/$to.html"; + } + } - can just set any of: html_css html_javascript title_prefix - 'html_header_before_title', - 'html_header_after_title', - 'html_footer', + # all other links are generated by the parent class + my $ret = $self->SUPER::do_pod_link($link); + return $ret; + } -maybe override do_pod_link + 1; + +Meanwhile in script.pl: + + use My::Pod; + + my $p = My::Pod->new; + + my $html; + $p->output_string(\$html); + $p->parse_file('path/to/Module/Name.pm'); + open my $out, '>', 'out.html' or die; + print $out $html; + +TODO maybe override do_beginning do_end @@ -952,7 +1108,7 @@ merchantability or fitness for a particular purpose. =head1 ACKNOWLEDGEMENTS -Thanks to L<Hurricane Electrict|http://he.net/> for permission to use its +Thanks to L<Hurricane Electric|http://he.net/> for permission to use its L<Linux man pages online|http://man.he.net/> site for man page links. Thanks to L<search.cpan.org|http://search.cpan.org/> for permission to use the diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm index 227c23b7f9f..52e77bcc1b8 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm @@ -5,7 +5,7 @@ use strict; use vars qw( $VERSION $HTML_RENDER_CLASS $HTML_EXTENSION $CSS $JAVASCRIPT $SLEEPY $SEARCH_CLASS @ISA ); -$VERSION = '3.14'; +$VERSION = '3.20'; @ISA = (); # Yup, we're NOT a subclass of Pod::Simple::HTML! # TODO: nocontents stylesheets. Strike some of the color variations? @@ -726,7 +726,7 @@ sub _gen_css_wad { 'whtgrng', # white_with_green_on_grey 'grygrnw', # grey_with_green_on_white ) { - my $outname = "$variation\_"; + my $outname = $variation; my $this_css = join "\n", "/* This file is autogenerated. Do not edit. $outname */\n", "\@import url(\"./_$variation.css\");", @@ -735,7 +735,7 @@ sub _gen_css_wad { ; my $name = $outname; $name =~ tr/-_/ /; - $self->add_css( "$outname.css", 0, $name, 0, 0, \$this_css); + $self->add_css( "_$outname.css", 0, $name, 0, 0, \$this_css); } return; @@ -1082,7 +1082,7 @@ Example: % mkdir out_html % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html (to convert the pod from Perl's @INC - files under the directory ../htmlversion) + files under the directory ./out_html) (Note that the command line there contains a literal atsign-I-N-C. This is handled as a special case by batch_convert, in order to save you having @@ -1095,7 +1095,7 @@ Example: % chmod og-rx ../seekrut % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go . ../htmlversion (to convert the pod under the current dir into HTML - files under the directory ../htmlversion) + files under the directory ./seekrut) Example: @@ -1141,7 +1141,7 @@ directory: =item $batchconv->batch_convert( 'somedir:someother:also' , ...); -This specifies that you want the dirs "somedir", "somother", and "also" +This specifies that you want the dirs "somedir", "someother", and "also" scanned, just as if you'd passed the arrayref C<[qw( somedir someother also)]>. Note that a ":"-separator is normal under Unix, but Under MSWin, you'll need C<'somedir;someother;also'> @@ -1226,7 +1226,7 @@ If you set this to a false value, no contents file will be written. This specifies what string should be put at the beginning of the contents page. The default is a string more or less like this: - + <html> <head><title>Perl Documentation</title></head> <body class='contentspage'> diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm index e426b2c547f..5aa5bc19897 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm @@ -3,12 +3,12 @@ require 5; package Pod::Simple::LinkSection; # Based somewhat dimly on Array::Autojoin use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; use strict; use Pod::Simple::BlackBox; use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; use overload( # So it'll stringify nice '""' => \&Pod::Simple::BlackBox::stringify_lol, @@ -114,7 +114,7 @@ Output: ], 'Pod::Simple::LinkSection' ), 'baz' ], 'Pod::Simple::LinkSection' ); - + But stringify it and you get just the text content: % perl -MData::Dumper -e diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm index bed3e8662b2..4113daf2351 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm @@ -4,7 +4,7 @@ package Pod::Simple::Methody; use strict; use Pod::Simple (); use vars qw(@ISA $VERSION); -$VERSION = '3.14'; +$VERSION = '3.20'; @ISA = ('Pod::Simple'); # Yes, we could use named variables, but I want this to be impose @@ -32,7 +32,7 @@ sub _handle_element_end { ( $_[0]->can( 'end_' . $_[1] ) || return )->( - $_[0] + $_[0], $_[2] ); } @@ -51,12 +51,12 @@ Pod::Simple::Methody -- turn Pod::Simple events into method calls use strict; package SomePodFormatter; use base qw(Pod::Simple::Methody); - + sub handle_text { my($self, $text) = @_; ... } - + sub start_head1 { my($self, $attrs) = @_; ... @@ -65,7 +65,7 @@ Pod::Simple::Methody -- turn Pod::Simple events into method calls my($self) = @_; ... } - + ...and start_/end_ methods for whatever other events you want to catch. =head1 DESCRIPTION diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm index 7de46d5696b..e85084a1c26 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::Progress; -$VERSION = '3.14'; +$VERSION = '3.20'; use strict; # Objects of this class are used for noting progress of an diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm index c27d0cbeb0e..c9726fd564a 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::PullParser; -$VERSION = '3.14'; +$VERSION = '3.20'; use Pod::Simple (); BEGIN {@ISA = ('Pod::Simple')} @@ -231,6 +231,8 @@ sub unget_token { sub set_source { my $self = shift @_; return $self->{'source_fh'} unless @_; + Carp::croak("Cannot assign new source to pull parser; create a new instance, instead") + if $self->{'source_fh'} || $self->{'source_scalar_ref'} || $self->{'source_arrayref'}; my $handle; if(!defined $_[0]) { Carp::croak("Can't use empty-string as a source for set_source"); @@ -453,7 +455,7 @@ sub _get_titled_section { $self->unget_token(@to_unget); if(DEBUG) { - if(defined $title) { print " Returing title <$title>\n" } + if(defined $title) { print " Returning title <$title>\n" } else { print "Returning title <>\n" } } @@ -532,7 +534,7 @@ And elsewhere: package SomePodProcessor; use strict; use base qw(Pod::Simple::PullParser); - + sub run { my $self = shift; Token: @@ -623,14 +625,14 @@ process the token-stream from the beginning. For example, suppose you have a document that starts out: =head1 NAME - + Hoo::Boy::Wowza -- Stuff B<wow> yeah! $parser->get_title on that document will return "Hoo::Boy::Wowza -- Stuff wow yeah!". If the document starts with: =head1 Name - + Hoo::Boy::W00t -- Stuff B<w00t> yeah! Then you'll need to pass the C<nocase> option in order to recognize "Name": @@ -648,7 +650,7 @@ the title seems to be of the form "SomeModuleName -- description". For example, suppose you have a document that starts out: =head1 NAME - + Hoo::Boy::Wowza -- Stuff B<wow> yeah! then $parser->get_short_title on that document will return @@ -657,14 +659,14 @@ then $parser->get_short_title on that document will return But if the document starts out: =head1 NAME - + Hooboy, stuff B<wow> yeah! then $parser->get_short_title on that document will return "Hooboy, stuff wow yeah!". If the document starts with: =head1 Name - + Hoo::Boy::W00t -- Stuff B<w00t> yeah! Then you'll need to pass the C<nocase> option in order to recognize "Name": @@ -769,6 +771,7 @@ Pod::Simple is maintained by: =back =cut + JUNK: sub _old_get_title { # some witchery in here @@ -833,7 +836,7 @@ sub _old_get_title { # some witchery in here $self->unget_token(@to_unget); if(DEBUG) { - if(defined $title) { print " Returing title <$title>\n" } + if(defined $title) { print " Returning title <$title>\n" } else { print "Returning title <>\n" } } diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm index 67a625d8877..a45aba18bae 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm @@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken (); use strict; use vars qw(@ISA $VERSION); @ISA = ('Pod::Simple::PullParserToken'); -$VERSION = '3.14'; +$VERSION = '3.20'; sub new { # Class->new(tagname); my $class = shift; diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm index 37d68ef6196..e9fbaa2b5ec 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm @@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken (); use strict; use vars qw(@ISA $VERSION); @ISA = ('Pod::Simple::PullParserToken'); -$VERSION = '3.14'; +$VERSION = '3.20'; sub new { # Class->new(tagname, optional_attrhash); my $class = shift; diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm index ed6340d598a..34985fdfb03 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm @@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken (); use strict; use vars qw(@ISA $VERSION); @ISA = ('Pod::Simple::PullParserToken'); -$VERSION = '3.14'; +$VERSION = '3.20'; sub new { # Class->new(text); my $class = shift; @@ -61,14 +61,14 @@ as calling $token->text would do. Or, if you want to alter the value, you can even do things like this: for ( ${ $token->text_r } ) { # Aliases it with $_ !! - + s/ The / the /g; # just for example - + if( 'A' eq chr(65) ) { # (if in an ASCII world) tr/\xA0/ /; tr/\xAD//d; } - + ...or however you want to alter the value... } diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm index 2234ccf7ade..b323ece2a32 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm @@ -3,7 +3,7 @@ require 5; package Pod::Simple::PullParserToken; # Base class for tokens gotten from Pod::Simple::PullParser's $parser->get_token @ISA = (); -$VERSION = '3.14'; +$VERSION = '3.20'; use strict; sub new { # Class->new('type', stuff...); ## Overridden in derived classes anyway @@ -56,10 +56,10 @@ Given a $parser that's an object of class Pod::Simple::PullParser } elsif($token->is_text) { ...access $token->text, $token->text_r, etc... - + } elsif($token->is_end) { ...access $token->tagname... - + } } diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm index f476d37b249..0d184e3a66b 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm @@ -8,7 +8,7 @@ package Pod::Simple::RTF; use strict; use vars qw($VERSION @ISA %Escape $WRAP %Tagmap); -$VERSION = '3.14'; +$VERSION = '3.20'; use Pod::Simple::PullParser (); BEGIN {@ISA = ('Pod::Simple::PullParser')} diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm index 32db4b6a51d..3671af121f0 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm @@ -6,7 +6,7 @@ use strict; use Carp (); use Pod::Simple (); use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS); -$VERSION = '3.14'; +$VERSION = '3.20'; BEGIN { @ISA = ('Pod::Simple'); *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG; @@ -67,15 +67,15 @@ Pod::Simple::SimpleTree -- parse Pod into a simple parse tree =head1 SYNOPSIS % cat ptest.pod - + =head1 PIE - + I like B<pie>! - + % perl -MPod::Simple::SimpleTree -MData::Dumper -e \ "print Dumper(Pod::Simple::SimpleTree->new->parse_file(shift)->root)" \ ptest.pod - + $VAR1 = [ 'Document', { 'start_line' => 1 }, diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod index f2011d5a5ce..792d1be5a24 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod @@ -17,7 +17,11 @@ Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass } sub _handle_element_end { - my($parser, $element_name) = @_; + my($parser, $element_name, $attr_hash_r) = @_; + # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin" + # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is + # mostly useless. It is documented where "over-*" and "begin" events are + # documented. ... } @@ -214,7 +218,7 @@ There are, at first glance, three kinds of L links: URL, man, and pod. When a LE<lt>I<some_url>E<gt> code is parsed, it produces this event structure: - <L content-implicit="yes" to="that_url" type="url"> + <L content-implicit="yes" raw="that_url" to="that_url" type="url"> that_url </L> @@ -227,14 +231,14 @@ For example, this Pod source: produces this event structure: - <L content-implicit="yes" to="http://www.perl.com/CPAN/authors/" type="url"> + <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url"> http://www.perl.com/CPAN/authors/ </L> When a LE<lt>I<manpage(section)>E<gt> code is parsed (and these are fairly rare and not terribly useful), it produces this event structure: - <L content-implicit="yes" to="manpage(section)" type="man"> + <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man"> manpage(section) </L> @@ -247,7 +251,7 @@ For example, this Pod source: produces this event structure: - <L content-implicit="yes" to="crontab(5)" type="man"> + <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man"> crontab(5) </L> @@ -258,7 +262,7 @@ in a I<section> attribute. For example, this Pod source: will produce this event structure: - <L content-implicit="yes" section="ENVIRONMENT" to="crontab(5)" type="man"> + <L content-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man"> "ENVIRONMENT" in crontab(5) </L> @@ -275,10 +279,10 @@ some link text.) For example, this Pod source: L<hell itself!|crontab(5)> - + will produce this event structure: - <L to="crontab(5)" type="man"> + <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man"> hell itself! </L> @@ -290,7 +294,7 @@ specified for this type of L code. In the most common case, the simple case of a LE<lt>podpageE<gt> code produces this event structure: - <L content-implicit="yes" to="Net::Ping" type="pod"> + <L content-implicit="yes" raw="podpage" to="podpage" type="pod"> podpage </L> @@ -300,7 +304,7 @@ For example, this Pod source: produces this event structure: - <L content-implicit="yes" to="Net::Ping" type="pod"> + <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod"> Net::Ping </L> @@ -313,7 +317,7 @@ case discussed above. For example, this Pod source: produces this event structure: - <L to="perldiag" type="pod"> + <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod"> Perl Error Messages </L> @@ -325,7 +329,7 @@ For example, this Pod source: produces this event structure: - <L content-implicit="yes" section="Member Data" type="pod"> + <L content-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod"> "Member Data" </L> @@ -335,7 +339,7 @@ As another example, this Pod source: produces this event structure: - <L section="Member Data" type="pod"> + <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod"> the various attributes </L> @@ -347,7 +351,7 @@ For example, this Pod source: produces this event structure: - <L content-implicit="yes" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> + <L content-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> "Basic BLOCKs and Switch Statements" in perlsyn </L> @@ -357,7 +361,7 @@ As another example, this Pod source: produces this event structure: - <L section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> + <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> SWITCH statements </L> @@ -368,12 +372,33 @@ Incidentally, note that we do not distinguish between these syntaxes: L</Member Data> L<Member Data> [deprecated syntax] -That is, they all produce the same event structure, namely: +That is, they all produce the same event structure (for the most part), namely: - <L content-implicit="yes" section="Member Data" type="pod"> + <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod"> "Member Data" </L> +The I<raw> attribute depends on what the raw content of the L<> is, so that is +why the event structure is the same "for the most part". + +If you have not guessed it yet, the I<raw> attribute contains the raw, +original, unescaped content of the L<> formatting code. In addition to the +examples above, take notice of the following event structure produced by +the following L<> formatting code. + + L<click B<here>|page/About the C<-M> switch> + + <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod"> + click B<here> + </L> + +Specifically, notice that the formatting codes are present and unescaped +in I<raw>. + +There is a known bug in the I<raw> attribute where any surrounding whitespace +is condensed into a single ' '. For example, given LE<60> linkE<62>, I<raw> +will be " link". + =item events with an element_name of E or Z While there are Pod codes EE<lt>...E<gt> and ZE<lt>E<gt>, these @@ -425,14 +450,43 @@ names in the event structure. =item events with an element_name of over-bullet When an "=over ... Z<>=back" block is parsed where the items are -a bulletted list, it will produce this event structure: +a bulleted list, it will produce this event structure: <over-bullet indent="4" start_line="543"> <item-bullet start_line="545"> ...Stuff... </item-bullet> ...more item-bullets... - </over-bullet> + </over-bullet fake-closer="1"> + +The attribute I<fake-closer> is only present if it is a true value; it is not +present if it is a false value. It is shown in the above example to illustrate +where the attribute is (in the B<closing> tag). It signifies that the C<=over> +did not have a matching C<=back>, and thus Pod::Simple had to create a fake +closer. + +For example, this Pod source: + + =over + + =item * + + Something + + =back + +Would produce an event structure that does B<not> have the I<fake-closer> +attribute, whereas this Pod source: + + =over + + =item * + + Gasp! An unclosed =over block! + +would. The rest of the over-* examples will not demonstrate this attribute, +but they all can have it. See L<Pod::Checker>'s source for an example of this +attribute being used. The value of the I<indent> attribute is whatever value is after the "=over" directive, as in "=over 8". If no such value is specified @@ -490,7 +544,7 @@ message might be issued to the user. =item events with an element_name of over-text -These events are are somewhat unlike the other over-* +These events are somewhat unlike the other over-* structures, as far as what their contents are. When an "=over ... Z<>=back" block is parsed where the items are a list of text "subheadings", it will produce this event structure: @@ -504,20 +558,20 @@ a list of text "subheadings", it will produce this event structure: ...more item-text and/or stuff... </over-text> -The I<indent> attribute is as with the other over-* events. +The I<indent> and I<fake-closer> attributes are as with the other over-* events. For example, this Pod source: =over - + =item Foo - + Stuff - + =item Bar I<baz>! - + Quux - + =back produces this event structure: @@ -545,7 +599,7 @@ produces this event structure: =item events with an element_name of over-block -These events are are somewhat unlike the other over-* +These events are somewhat unlike the other over-* structures, as far as what their contents are. When an "=over ... Z<>=back" block is parsed where there are no items, it will produce this event structure: @@ -554,23 +608,23 @@ it will produce this event structure: ...stuff (generally Para or Verbatim elements)... </over-block> -The I<indent> attribute is as with the other over-* events. +The I<indent> and I<fake-closer> attributes are as with the other over-* events. For example, this Pod source: =over - + For cutting off our trade with all parts of the world - + For transporting us beyond seas to be tried for pretended offenses - + He is at this time transporting large armies of foreign mercenaries to complete the works of death, desolation and tyranny, already begun with circumstances of cruelty and perfidy scarcely paralleled in the most barbarous ages, and totally unworthy the head of a civilized nation. - - =cut - + + =back + will produce this event structure: <over-block indent="4" start_line="2"> @@ -585,6 +639,41 @@ will produce this event structure: </Para> </over-block> +=item events with an element_name of over-empty + +B<Note: These events are only triggered if C<parse_empty_lists()> is set to a +true value.> + +These events are somewhat unlike the other over-* structures, as far as what +their contents are. When an "=over ... Z<>=back" block is parsed where there +is no content, it will produce this event structure: + + <over-empty indent="4" start_line="543"> + </over-empty> + +The I<indent> and I<fake-closer> attributes are as with the other over-* events. + +For example, this Pod source: + + =over + + =over + + =back + + =back + +will produce this event structure: + + <over-block indent="4" start_line="1"> + <over-empty indent="4" start_line="3"> + </over-empty> + </over-block> + +Note that the outer C<=over> is a block because it has no C<=item>s but still +has content: the inner C<=over>. The inner C<=over>, in turn, is completely +empty, and is treated as such. + =item events with an element_name of item-bullet See L</"events with an element_name of over-bullet">, above. @@ -615,7 +704,7 @@ Pod::Simple provides a lot of methods that aren't generally interesting to the end user of an existing Pod formatter, but some of which you might find useful in writing a Pod formatter. They are listed below. The first several methods (the accept_* methods) are for declaring the -capabilites of your parser, notably what C<=for I<targetname>> sections +capabilities of your parser, notably what C<=for I<targetname>> sections it's interested in, what extra NE<lt>...E<gt> codes it accepts beyond the ones described in the I<perlpod>. @@ -673,7 +762,7 @@ B<TODO: document how this interacts with =extend, and long element names> In the unlikely situation that you need to tell the parser that you will accept additional directives ("=foo" things), you need to first set the -parset to treat its content as data (i.e., not really processed at +parser to treat its content as data (i.e., not really processed at all), or as verbatim (mostly just expanding tabs), or as processed text (parsing formatting codes like BE<lt>...E<gt>). @@ -783,6 +872,21 @@ This is just like the code_handler attribute, except that it's for unlikely to be interesting, but this is included for completeness. +=item C<< $parser->pod_handler( I<CODE_REF> ) >> + +This is just like the code_handler attribute, except that it's for +"=pod" lines, not code lines. The same caveats apply. "=pod" lines are +unlikely to be interesting, but this is included for completeness. + + +=item C<< $parser->whiteline_handler( I<CODE_REF> ) >> + +This is just like the code_handler attribute, except that it's for +lines that are seemingly blank but have whitespace (" " and/or "\t") on them, +not code lines. The same caveats apply. These lines are unlikely to be +interesting, but this is included for completeness. + + =item C<< $parser->whine( I<linenumber>, I<complaint string> ) >> This notes a problem in the Pod, which will be reported to in the "Pod @@ -793,7 +897,7 @@ C<complain_stderr>. =item C<< $parser->scream( I<linenumber>, I<complaint string> ) >> This notes an error like C<whine> does, except that it is not -suppressable with C<no_whining>. This should be used only for very +suppressible with C<no_whining>. This should be used only for very serious errors. @@ -806,7 +910,7 @@ C<die>! =item C<< $parser->hide_line_numbers( I<SOMEVALUE> ) >> -Some subclasses that indescriminately dump event attributes (well, +Some subclasses that indiscriminately dump event attributes (well, except for ones beginning with "~") can use this object attribute for refraining to dump the "start_line" attribute. @@ -847,8 +951,13 @@ conventions as two spaces after periods will be preserved by the parser. This is primarily useful for output formats that treat whitespace as significant (such as text or *roff, but not HTML). -=back +=item C<< $parser->parse_empty_lists( I<SOMEVALUE> ) >> + +If this attribute is set to true, the parser will not ignore empty +C<=over>/C<=back> blocks. The type of C<=over> will be I<empty>, documented +above, L<events with an element_name of over-empty>. +=back =head1 SEE ALSO @@ -887,6 +996,8 @@ L<Pod::Simple::Text> -- a simple plaintext formatter for Pod L<Pod::Simple::TextContent> -- like Pod::Simple::Text, but makes no effort for indent or wrap the text being formatted +L<Pod::Simple::HTML> -- a simple HTML formatter for Pod + L<perlpod|perlpod> L<perlpodspec|perlpodspec> diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Text.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Text.pm index 81fde4e7a70..3032d0fcd57 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Text.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Text.pm @@ -6,7 +6,7 @@ use Carp (); use Pod::Simple::Methody (); use Pod::Simple (); use vars qw( @ISA $VERSION $FREAKYMODE); -$VERSION = '3.14'; +$VERSION = '3.20'; @ISA = ('Pod::Simple::Methody'); BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG) ? \&Pod::Simple::DEBUG @@ -71,7 +71,7 @@ sub end_L { if (my $link = delete $_[0]{'Link'}) { # Append the URL to the output unless it's already present. $_[0]{'Thispara'} .= " <$link->{to}>" - unless $_[0]{'Thispara'} =~ /\b\E$link->{to}/; + unless $_[0]{'Thispara'} =~ /\b\Q$link->{to}/; } } diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm index 914c7fd166c..dea1cde7ccf 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm @@ -6,7 +6,7 @@ use strict; use Carp (); use Pod::Simple (); use vars qw( @ISA $VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; @ISA = ('Pod::Simple'); sub new { diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm index c5d4483b283..9f2a224a278 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm @@ -4,7 +4,7 @@ package Pod::Simple::TiedOutFH; use Symbol ('gensym'); use Carp (); use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm index 258d0d76760..892436db7f0 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm @@ -2,7 +2,7 @@ require 5; package Pod::Simple::Transcode; use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; BEGIN { if(defined &DEBUG) {;} # Okay diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm index d1c320d5d1a..33030903430 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm @@ -5,7 +5,7 @@ require 5; package Pod::Simple::TranscodeDumb; use strict; use vars qw($VERSION %Supported); -$VERSION = '3.14'; +$VERSION = '3.20'; # This module basically pretends it knows how to transcode, except # only for null-transcodings! We use this when Encode isn't # available. diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm index bab59fc8972..a66dedd03bc 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm @@ -9,7 +9,7 @@ use strict; use Pod::Simple; require Encode; use vars qw($VERSION ); -$VERSION = '3.14'; +$VERSION = '3.20'; sub is_dumb {0} sub is_smart {1} diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm index 6a8fb7e97e4..9d31db0badd 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm @@ -23,13 +23,29 @@ This is a subclass of L<Pod::Simple::Methody> and inherits all its methods. The implementation is entirely different than L<Pod::Simple::HTML>, but it largely preserves the same interface. +=head2 Minimal code + + use Pod::Simple::XHTML; + my $psx = Pod::Simple::XHTML->new; + $psx->output_string(\my $html); + $psx->parse_file('path/to/Module/Name.pm'); + open my $out, '>', 'out.html' or die "Cannot open 'out.html': $!\n"; + print $out $html; + +You can also control the character encoding and entities. For example, if +you're sure that the POD is properly encoded (using the C<=encoding> command), +you can prevent high-bit characters from being encoded as HTML entities and +declare the output character set as UTF-8 before parsing, like so: + + $psx->html_charset('UTF-8'); + $psx->html_encode_chars('&<>">'); + =cut package Pod::Simple::XHTML; use strict; use vars qw( $VERSION @ISA $HAS_HTML_ENTITIES ); -$VERSION = '3.14'; -use Carp (); +$VERSION = '3.20'; use Pod::Simple::Methody (); @ISA = ('Pod::Simple::Methody'); @@ -46,10 +62,17 @@ my %entities = ( ); sub encode_entities { - return HTML::Entities::encode_entities( $_[0] ) if $HAS_HTML_ENTITIES; + my $self = shift; + my $ents = $self->html_encode_chars; + return HTML::Entities::encode_entities( $_[0], $ents ) if $HAS_HTML_ENTITIES; + if (defined $ents) { + $ents =~ s,(?<!\\)([]/]),\\$1,g; + $ents =~ s,(?<!\\)\\\z,\\\\,; + } else { + $ents = join '', keys %entities; + } my $str = $_[0]; - my $ents = join '', keys %entities; - $str =~ s/([$ents])/'&' . $entities{$1} . ';'/ge; + $str =~ s/([$ents])/'&' . ($entities{$1} || sprintf '#x%X', ord $1) . ';'/ge; return $str; } @@ -107,6 +130,12 @@ not set by default. A document type tag for the file. This option is not set by default. +=head2 html_charset + +The charater set to declare in the Content-Type meta tag created by default +for C<html_header_tags>. Note that this option will be ignored if the value of +C<html_header_tags> is changed. Defaults to "ISO-8859-1". + =head2 html_header_tags Additional arbitrary HTML tags for the header of the document. The @@ -117,6 +146,15 @@ default value is just a content type header tag: Add additional meta tags here, or blocks of inline CSS or JavaScript (wrapped in the appropriate tags). +=head3 html_encode_chars + +A string containing all characters that should be encoded as HTML entities, +specified using the regular expression character class syntax (what you find +within brackets in regular expressions). This value will be passed as the +second argument to the C<encode_entities> fuction of L<HTML::Entities>. IF +L<HTML::Entities> is not installed, then any characters other than C<&<>"'> +will be encoded numerically. + =head2 html_h_level This is the level of HTML "Hn" element to which a Pod "head1" corresponds. For @@ -156,6 +194,16 @@ to the empty string. Whether to add a table-of-contents at the top of each page (called an index for the sake of tradition). +=head2 anchor_items + +Whether to anchor every definition C<=item> directive. This needs to be +enabled if you want to be able to link to specific C<=item> directives, which +are output as C<< <dt> >> elements. Disabled by default. + +=head2 backlink + +Whether to turn every =head1 directive into a link pointing to the top +of the page (specifically, the opening body tag). =cut @@ -165,10 +213,11 @@ __PACKAGE__->_accessorize( 'man_url_prefix', 'man_url_postfix', 'title_prefix', 'title_postfix', - 'html_css', + 'html_css', 'html_javascript', 'html_doctype', - 'html_header_tags', + 'html_charset', + 'html_encode_chars', 'html_h_level', 'title', # Used internally for the title extracted from the content 'default_title', @@ -176,6 +225,8 @@ __PACKAGE__->_accessorize( 'html_header', 'html_footer', 'index', + 'anchor_items', + 'backlink', 'batch_mode', # whether we're in batch mode 'batch_mode_current_level', # When in batch mode, how deep the current module is: 1 for "LWP", @@ -198,14 +249,15 @@ sub new { $new->{'output_fh'} ||= *STDOUT{IO}; $new->perldoc_url_prefix('http://search.cpan.org/perldoc?'); $new->man_url_prefix('http://man.he.net/man'); - $new->html_header_tags('<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />'); + $new->html_charset('ISO-8859-1'); $new->nix_X_codes(1); $new->codes_in_verbatim(1); $new->{'scratch'} = ''; $new->{'to_index'} = []; $new->{'output'} = []; $new->{'saved'} = []; - $new->{'ids'} = {}; + $new->{'ids'} = { '_podtop_' => 1 }; # used in <body> + $new->{'in_li'} = []; $new->{'__region_targets'} = []; $new->{'__literal_targets'} = {}; @@ -214,6 +266,14 @@ sub new { return $new; } +sub html_header_tags { + my $self = shift; + return $self->{html_header_tags} = shift if @_; + return $self->{html_header_tags} + ||= '<meta http-equiv="Content-Type" content="text/html; charset=' + . $self->html_charset . '" />'; +} + #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =head2 handle_text @@ -225,7 +285,7 @@ want to override this if you are adding a custom element type that does more than just display formatted text. Perhaps adding a way to generate HTML tables from an extended version of POD. -So, let's say you want add a custom element called 'foo'. In your +So, let's say you want to add a custom element called 'foo'. In your subclass's C<new> method, after calling C<SUPER::new> you'd call: $new->accept_targets_as_text( 'foo' ); @@ -270,7 +330,7 @@ sub handle_text { # escape special characters in HTML (<, >, &, etc) $_[0]{'scratch'} .= $_[0]->__in_literal_xhtml_region ? $_[1] - : encode_entities( $_[1] ); + : $_[0]->encode_entities( $_[1] ); } sub start_Para { $_[0]{'scratch'} = '<p>' } @@ -282,28 +342,24 @@ sub start_head3 { $_[0]{'in_head'} = 3 } sub start_head4 { $_[0]{'in_head'} = 4 } sub start_item_number { - $_[0]{'scratch'} = "</li>\n" if $_[0]{'in_li'}; + $_[0]{'scratch'} = "</li>\n" if ($_[0]{'in_li'}->[-1] && pop @{$_[0]{'in_li'}}); $_[0]{'scratch'} .= '<li><p>'; - $_[0]{'in_li'} = 1 + push @{$_[0]{'in_li'}}, 1; } sub start_item_bullet { - $_[0]{'scratch'} = "</li>\n" if $_[0]{'in_li'}; + $_[0]{'scratch'} = "</li>\n" if ($_[0]{'in_li'}->[-1] && pop @{$_[0]{'in_li'}}); $_[0]{'scratch'} .= '<li><p>'; - $_[0]{'in_li'} = 1 + push @{$_[0]{'in_li'}}, 1; } sub start_item_text { - if ($_[0]{'in_dd'}[ $_[0]{'dl_level'} ]) { - $_[0]{'scratch'} = "</dd>\n"; - $_[0]{'in_dd'}[ $_[0]{'dl_level'} ] = 0; - } - $_[0]{'scratch'} .= '<dt>'; + # see end_item_text } -sub start_over_bullet { $_[0]{'scratch'} = '<ul>'; $_[0]->emit } +sub start_over_bullet { $_[0]{'scratch'} = '<ul>'; push @{$_[0]{'in_li'}}, 0; $_[0]->emit } sub start_over_block { $_[0]{'scratch'} = '<ul>'; $_[0]->emit } -sub start_over_number { $_[0]{'scratch'} = '<ol>'; $_[0]->emit } +sub start_over_number { $_[0]{'scratch'} = '<ol>'; push @{$_[0]{'in_li'}}, 0; $_[0]->emit } sub start_over_text { $_[0]{'scratch'} = '<dl>'; $_[0]{'dl_level'}++; @@ -314,14 +370,16 @@ sub start_over_text { sub end_over_block { $_[0]{'scratch'} .= '</ul>'; $_[0]->emit } sub end_over_number { - $_[0]{'scratch'} = "</li>\n" if delete $_[0]{'in_li'}; + $_[0]{'scratch'} = "</li>\n" if ( pop @{$_[0]{'in_li'}} ); $_[0]{'scratch'} .= '</ol>'; + pop @{$_[0]{'in_li'}}; $_[0]->emit; } sub end_over_bullet { - $_[0]{'scratch'} = "</li>\n" if delete $_[0]{'in_li'}; + $_[0]{'scratch'} = "</li>\n" if ( pop @{$_[0]{'in_li'}} ); $_[0]{'scratch'} .= '</ul>'; + pop @{$_[0]{'in_li'}}; $_[0]->emit; } @@ -352,7 +410,10 @@ sub _end_head { my $id = $_[0]->idify($_[0]{scratch}); my $text = $_[0]{scratch}; - $_[0]{'scratch'} = qq{<h$h id="$id">$text</h$h>}; + $_[0]{'scratch'} = $_[0]->backlink && ($h - $add == 0) + # backlinks enabled && =head1 + ? qq{<a href="#_podtop_"><h$h id="$id">$text</h$h></a>} + : qq{<h$h id="$id">$text</h$h>}; $_[0]->emit; push @{ $_[0]{'to_index'} }, [$h, $id, $text]; } @@ -366,13 +427,27 @@ sub end_item_bullet { $_[0]{'scratch'} .= '</p>'; $_[0]->emit } sub end_item_number { $_[0]{'scratch'} .= '</p>'; $_[0]->emit } sub end_item_text { - $_[0]{'scratch'} .= "</dt>\n<dd>"; + # idify and anchor =item content if wanted + my $dt_id = $_[0]{'anchor_items'} + ? ' id="'. $_[0]->idify($_[0]{'scratch'}) .'"' + : ''; + + # reset scratch + my $text = $_[0]{scratch}; + $_[0]{'scratch'} = ''; + + if ($_[0]{'in_dd'}[ $_[0]{'dl_level'} ]) { + $_[0]{'scratch'} = "</dd>\n"; + $_[0]{'in_dd'}[ $_[0]{'dl_level'} ] = 0; + } + + $_[0]{'scratch'} .= qq{<dt$dt_id>$text</dt>\n<dd>}; $_[0]{'in_dd'}[ $_[0]{'dl_level'} ] = 1; $_[0]->emit; } # This handles =begin and =for blocks of all kinds. -sub start_for { +sub start_for { my ($self, $flags) = @_; push @{ $self->{__region_targets} }, $flags->{target_matching}; @@ -386,7 +461,7 @@ sub start_for { $self->emit; } -sub end_for { +sub end_for { my ($self) = @_; $self->{'scratch'} .= '</div>' unless $self->__in_literal_xhtml_region; @@ -395,24 +470,29 @@ sub end_for { $self->emit; } -sub start_Document { +sub start_Document { my ($self) = @_; if (defined $self->html_header) { $self->{'scratch'} .= $self->html_header; $self->emit unless $self->html_header eq ""; } else { - my ($doctype, $title, $metatags); + my ($doctype, $title, $metatags, $bodyid); $doctype = $self->html_doctype || ''; $title = $self->force_title || $self->title || $self->default_title || ''; $metatags = $self->html_header_tags || ''; - if ($self->html_css) { - $metatags .= "\n<link rel='stylesheet' href='" . - $self->html_css . "' type='text/css'>"; + if (my $css = $self->html_css) { + $metatags .= $css; + if ($css !~ /<link/) { + # this is required to be compatible with Pod::Simple::BatchHTML + $metatags .= '<link rel="stylesheet" href="' + . $self->encode_entities($css) . '" type="text/css" />'; + } } if ($self->html_javascript) { - $metatags .= "\n<script type='text/javascript' src='" . + $metatags .= qq{\n<script type="text/javascript" src="} . $self->html_javascript . "'></script>"; } + $bodyid = $self->backlink ? ' id="_podtop_"' : ''; $self->{'scratch'} .= <<"HTML"; $doctype <html> @@ -420,7 +500,7 @@ $doctype <title>$title</title> $metatags </head> -<body> +<body$bodyid> HTML $self->emit; } @@ -500,10 +580,12 @@ sub end_I { $_[0]{'scratch'} .= '</i>' } sub start_L { my ($self, $flags) = @_; my ($type, $to, $section) = @{$flags}{'type', 'to', 'section'}; - my $url = $type eq 'url' ? $to + my $url = $self->encode_entities( + $type eq 'url' ? $to : $type eq 'pod' ? $self->resolve_pod_page_link($to, $section) : $type eq 'man' ? $self->resolve_man_page_link($to, $section) - : undef; + : undef + ); # If it's an unknown type, use an attribute-less <a> like HTML.pm. $self->{'scratch'} .= '<a' . ($url ? ' href="'. $url . '">' : '>'); @@ -511,8 +593,8 @@ sub start_L { sub end_L { $_[0]{'scratch'} .= '</a>' } -sub start_S { $_[0]{'scratch'} .= '<nobr>' } -sub end_S { $_[0]{'scratch'} .= '</nobr>' } +sub start_S { $_[0]{'scratch'} .= '<span style="white-space: nowrap;">' } +sub end_S { $_[0]{'scratch'} .= '</span>' } sub emit { my($self) = @_; @@ -547,14 +629,14 @@ sub resolve_pod_page_link { my ($self, $to, $section) = @_; return undef unless defined $to || defined $section; if (defined $section) { - $section = '#' . $self->idify($section, 1); + $section = '#' . $self->idify($self->encode_entities($section), 1); return $section unless defined $to; } else { $section = '' } return ($self->perldoc_url_prefix || '') - . encode_entities($to) . $section + . $self->encode_entities($to) . $section . ($self->perldoc_url_postfix || ''); } @@ -583,7 +665,7 @@ sub resolve_man_page_link { my ($page, $part) = $to =~ /^([^(]+)(?:[(](\d+)[)])?$/; return undef unless $page; return ($self->man_url_prefix || '') - . ($part || 1) . "/" . encode_entities($page) + . ($part || 1) . "/" . $self->encode_entities($page) . ($self->man_url_postfix || ''); } @@ -627,6 +709,7 @@ sub idify { for ($t) { s/<[^>]+>//g; # Strip HTML. s/&[^;]+;//g; # Strip entities. + s/^\s+//; s/\s+$//; # Strip white space. s/^([^a-zA-Z]+)$/pod$1/; # Prepend "pod" if no valid chars. s/^[^a-zA-Z]+//; # First char must be a letter. s/[^-a-zA-Z0-9_:.]+/-/g; # All other chars must be valid. @@ -655,6 +738,10 @@ sub batch_mode_page_object_init { return $self; } +sub html_header_after_title { +} + + 1; __END__ @@ -689,7 +776,7 @@ merchantability or fitness for a particular purpose. =head1 ACKNOWLEDGEMENTS -Thanks to L<Hurricane Electrict|http://he.net/> for permission to use its +Thanks to L<Hurricane Electric|http://he.net/> for permission to use its L<Linux man pages online|http://man.he.net/> site for man page links. Thanks to L<search.cpan.org|http://search.cpan.org/> for permission to use the diff --git a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm index 2e6b42834e0..bbb815a5527 100644 --- a/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm +++ b/gnu/usr.bin/perl/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm @@ -5,7 +5,7 @@ use strict; use Carp (); use Pod::Simple (); use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS); -$VERSION = '3.14'; +$VERSION = '3.20'; BEGIN { @ISA = ('Pod::Simple'); *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG; |