diff options
Diffstat (limited to 'cpan/Pod-Simple/lib')
28 files changed, 252 insertions, 73 deletions
diff --git a/cpan/Pod-Simple/lib/Pod/Simple.pm b/cpan/Pod-Simple/lib/Pod/Simple.pm index d75c761bde..0dc726d8ed 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple.pm @@ -18,7 +18,7 @@ use vars qw( ); @ISA = ('Pod::Simple::BlackBox'); -$VERSION = '3.18'; +$VERSION = '3.19'; @Known_formatting_codes = qw(I B C L E F S X Z); %Known_formatting_codes = map(($_=>1), @Known_formatting_codes); @@ -93,10 +93,15 @@ __PACKAGE__->_accessorize( 'codes_in_verbatim', # for PseudoPod extensions 'code_handler', # coderef to call when a code (non-pod) line is seen - 'cut_handler', # coderef to call when a =cut line is seen + 'cut_handler', # ... when a =cut line is seen + 'pod_handler', # ... when a =pod line is seen + 'whiteline_handler', # ... when a line with only whitespace is seen #Called like: # $code_handler->($line, $self->{'line_count'}, $self) if $code_handler; # $cut_handler->($line, $self->{'line_count'}, $self) if $cut_handler; + # $pod_handler->($line, $self->{'line_count'}, $self) if $pod_handler; + # $wl_handler->($line, $self->{'line_count'}, $self) if $wl_handler; + 'parse_empty_lists', # whether to acknowledge empty =over/=back blocks ); @@ -975,7 +980,7 @@ sub _treat_Zs { # Nix Z<...>'s # possibly a man page name (like "crontab(5)" is). # -############# Not implemented, I guess. +############# The "raw" attribute that is already there. # Sixth: # The raw original L<...> content, before text is split on "|", "/", etc, # and before E<...> codes are expanded. @@ -1345,6 +1350,10 @@ sub _treat_Es { DEBUG > 1 and print "Ogling E<$content>\n"; + # XXX E<>'s contents *should* be a valid char in the scope of the current + # =encoding directive. Defaults to iso-8859-1, I believe. Fix this in the + # future sometime. + $charnum = Pod::Escapes::e2charnum($content); DEBUG > 1 and print " Considering E<$content> with char ", defined($charnum) ? $charnum : "undef", ".\n"; diff --git a/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm b/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm index d8dfce4411..a89e5ed19c 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm +++ b/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.18'; +$VERSION = '3.19'; #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; @@ -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; @@ -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'" @@ -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'" @@ -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; } diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm b/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm index 7f28f1e31c..35910d6bc1 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Checker.pm +++ b/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.18'; +$VERSION = '3.19'; @ISA = ('Pod::Simple::Methody'); BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG) ? \&Pod::Simple::DEBUG diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm b/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm index 037900d3db..e5827ec0ad 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Debug.pm +++ b/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.18'; +$VERSION = '3.19'; sub import { my($value,$variable); diff --git a/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm b/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm index 42e8d7aef1..a4af8b25e2 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::DumpAsText; -$VERSION = '3.18'; +$VERSION = '3.19'; use Pod::Simple (); BEGIN {@ISA = ('Pod::Simple')} diff --git a/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm b/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm index 9fb039d6fb..672fb4ceca 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::DumpAsXML; -$VERSION = '3.18'; +$VERSION = '3.19'; use Pod::Simple (); BEGIN {@ISA = ('Pod::Simple')} diff --git a/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm b/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm index b1063bb80b..8e9849a2db 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/HTML.pm +++ b/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.18'; +$VERSION = '3.19'; BEGIN { if(defined &DEBUG) { } # no-op diff --git a/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm b/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm index 49ffd0cc45..7e107eed47 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm +++ b/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.18'; +$VERSION = '3.19'; @ISA = (); # Yup, we're NOT a subclass of Pod::Simple::HTML! # TODO: nocontents stylesheets. Strike some of the color variations? diff --git a/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm b/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm index e04a503f61..5959e2d4a7 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm +++ b/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.18'; +$VERSION = '3.19'; use strict; use Pod::Simple::BlackBox; use vars qw($VERSION ); -$VERSION = '3.18'; +$VERSION = '3.19'; use overload( # So it'll stringify nice '""' => \&Pod::Simple::BlackBox::stringify_lol, diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm b/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm index 6733394b42..11d487dda0 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Methody.pm +++ b/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.18'; +$VERSION = '3.19'; @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] ); } diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm b/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm index 9afa1ab9fe..ce418823a5 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/Progress.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::Progress; -$VERSION = '3.18'; +$VERSION = '3.19'; use strict; # Objects of this class are used for noting progress of an diff --git a/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm b/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm index dd2b776f62..ba554ad89e 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm @@ -1,7 +1,7 @@ require 5; package Pod::Simple::PullParser; -$VERSION = '3.18'; +$VERSION = '3.19'; use Pod::Simple (); BEGIN {@ISA = ('Pod::Simple')} diff --git a/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm b/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm index a14fced9e0..86b948b6b6 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm +++ b/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.18'; +$VERSION = '3.19'; sub new { # Class->new(tagname); my $class = shift; diff --git a/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm b/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm index 8f5bd59bdc..e7742b0f6f 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm +++ b/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.18'; +$VERSION = '3.19'; sub new { # Class->new(tagname, optional_attrhash); my $class = shift; diff --git a/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm b/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm index c376ead23d..47f3b3de0c 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm +++ b/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.18'; +$VERSION = '3.19'; sub new { # Class->new(text); my $class = shift; diff --git a/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm b/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm index 56b58186e2..0e6a8814f0 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm +++ b/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.18'; +$VERSION = '3.19'; use strict; sub new { # Class->new('type', stuff...); ## Overridden in derived classes anyway diff --git a/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm b/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm index 19dc759ea9..26843db410 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/RTF.pm +++ b/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.18'; +$VERSION = '3.19'; use Pod::Simple::PullParser (); BEGIN {@ISA = ('Pod::Simple::PullParser')} diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Search.pm b/cpan/Pod-Simple/lib/Pod/Simple/Search.pm index 823c6528fc..656df9b08d 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Search.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/Search.pm @@ -4,7 +4,7 @@ package Pod::Simple::Search; use strict; use vars qw($VERSION $MAX_VERSION_WITHIN $SLEEPY); -$VERSION = '3.18'; ## Current version of this package +$VERSION = '3.19'; ## Current version of this package BEGIN { *DEBUG = sub () {0} unless defined &DEBUG; } # set DEBUG level use Carp (); diff --git a/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm b/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm index fdea4a19b3..8eb18accbb 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm +++ b/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.18'; +$VERSION = '3.19'; BEGIN { @ISA = ('Pod::Simple'); *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG; diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod b/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod index 793c790730..532e653a46 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod +++ b/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> @@ -278,7 +282,7 @@ For example, this Pod source: 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="podpage" 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 @@ -432,7 +457,36 @@ a bulleted list, it will produce this event structure: ...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,7 +558,7 @@ 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: @@ -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,7 +608,7 @@ 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: @@ -569,7 +623,7 @@ For example, this Pod source: 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: @@ -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. @@ -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 @@ -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 diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Text.pm b/cpan/Pod-Simple/lib/Pod/Simple/Text.pm index 04b01b2a0d..21c7a40cb7 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Text.pm +++ b/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.18'; +$VERSION = '3.19'; @ISA = ('Pod::Simple::Methody'); BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG) ? \&Pod::Simple::DEBUG diff --git a/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm b/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm index 447fd9cacc..33be7b2258 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm +++ b/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.18'; +$VERSION = '3.19'; @ISA = ('Pod::Simple'); sub new { diff --git a/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm b/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm index 1f09805292..95686116a6 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm +++ b/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.18'; +$VERSION = '3.19'; #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm b/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm index 17b73ae5b6..9ecf85aec8 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm @@ -2,7 +2,7 @@ require 5; package Pod::Simple::Transcode; use vars qw($VERSION ); -$VERSION = '3.18'; +$VERSION = '3.19'; BEGIN { if(defined &DEBUG) {;} # Okay diff --git a/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm b/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm index d75ba6886f..4031ca3db2 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm +++ b/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.18'; +$VERSION = '3.19'; # 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/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm b/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm index a97df580c9..de193fa0c5 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm +++ b/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.18'; +$VERSION = '3.19'; sub is_dumb {0} sub is_smart {1} diff --git a/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm b/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm index f528a77831..5fc9f2aab0 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm +++ b/cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm @@ -45,7 +45,7 @@ declare the output character set as UTF-8 before parsing, like so: package Pod::Simple::XHTML; use strict; use vars qw( $VERSION @ISA $HAS_HTML_ENTITIES ); -$VERSION = '3.18'; +$VERSION = '3.19'; use Pod::Simple::Methody (); @ISA = ('Pod::Simple::Methody'); @@ -480,12 +480,16 @@ sub start_Document { $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_"' : ''; @@ -734,6 +738,10 @@ sub batch_mode_page_object_init { return $self; } +sub html_header_after_title { +} + + 1; __END__ diff --git a/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm b/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm index 4326ec4345..61473e317e 100644 --- a/cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm +++ b/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.18'; +$VERSION = '3.19'; BEGIN { @ISA = ('Pod::Simple'); *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG; |