Update Pod-Simple to CPAN version 3.28
authorChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Sun, 12 May 2013 13:48:18 +0000 (14:48 +0100)
committerChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Sun, 12 May 2013 13:48:18 +0000 (14:48 +0100)
  [DELTA]

2013-05-04   David E. Wheeler <david@justatheory.org>
  * Release 3.28

  Removed use of 'done_testing' in t/white.t, which was added in
  v3.27. Thanks to Paul Howarth for the catch.

  Fixed inproperly calculated number of skipped tests in t/xhtml01.t
  when HTML::Entities is not intalled.

2013-05-03   David E. Wheeler <david@justatheory.org>
  * Release 3.27

  Added new warnings as defined by Pod::Checker, thanks to RJBS:
  + "=over" without "=back"
  + "L<>" starts or ends with whitespace
  + raw "|" or "/" in "L<text|link>" text

  Added ->keep_encoding_directive, which is false by default, to
  prevent formatters from emitting a document's '=encoding'
  directive in most cases. That they emitted the encoding was a bug
  introduced in v3.26 (RT #84093). Now, only the DumpAsText and
  DumpAsXML formats set it to true. Patch from Patrice Dumas.

36 files changed:
MANIFEST
Porting/Maintainers.pl
cpan/Pod-Simple/ChangeLog
cpan/Pod-Simple/README
cpan/Pod-Simple/lib/Pod/Simple.pm
cpan/Pod-Simple/lib/Pod/Simple/BlackBox.pm
cpan/Pod-Simple/lib/Pod/Simple/Checker.pm
cpan/Pod-Simple/lib/Pod/Simple/Debug.pm
cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm
cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm
cpan/Pod-Simple/lib/Pod/Simple/HTML.pm
cpan/Pod-Simple/lib/Pod/Simple/HTMLBatch.pm
cpan/Pod-Simple/lib/Pod/Simple/LinkSection.pm
cpan/Pod-Simple/lib/Pod/Simple/Methody.pm
cpan/Pod-Simple/lib/Pod/Simple/Progress.pm
cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm
cpan/Pod-Simple/lib/Pod/Simple/PullParserEndToken.pm
cpan/Pod-Simple/lib/Pod/Simple/PullParserStartToken.pm
cpan/Pod-Simple/lib/Pod/Simple/PullParserTextToken.pm
cpan/Pod-Simple/lib/Pod/Simple/PullParserToken.pm
cpan/Pod-Simple/lib/Pod/Simple/RTF.pm
cpan/Pod-Simple/lib/Pod/Simple/Search.pm
cpan/Pod-Simple/lib/Pod/Simple/SimpleTree.pm
cpan/Pod-Simple/lib/Pod/Simple/Subclassing.pod
cpan/Pod-Simple/lib/Pod/Simple/Text.pm
cpan/Pod-Simple/lib/Pod/Simple/TextContent.pm
cpan/Pod-Simple/lib/Pod/Simple/TiedOutFH.pm
cpan/Pod-Simple/lib/Pod/Simple/Transcode.pm
cpan/Pod-Simple/lib/Pod/Simple/TranscodeDumb.pm
cpan/Pod-Simple/lib/Pod/Simple/TranscodeSmart.pm
cpan/Pod-Simple/lib/Pod/Simple/XHTML.pm
cpan/Pod-Simple/lib/Pod/Simple/XMLOutStream.pm
cpan/Pod-Simple/t/html01.t
cpan/Pod-Simple/t/items.t
cpan/Pod-Simple/t/whine.t [new file with mode: 0644]
cpan/Pod-Simple/t/xhtml01.t

index 7c4ba64..922dffb 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -2230,6 +2230,7 @@ cpan/Pod-Simple/t/testlib3/squaa/Vliff.pm         Pod::Simple test file
 cpan/Pod-Simple/t/tiedfh.t                             Pod::Simple test file
 cpan/Pod-Simple/t/verbatim.t                           Pod::Simple test file
 cpan/Pod-Simple/t/verb_fmt.t                           Pod::Simple test file
+cpan/Pod-Simple/t/whine.t
 cpan/Pod-Simple/t/xhtml01.t                            Pod::Simple test file
 cpan/Pod-Simple/t/xhtml05.t                            Pod::Simple test file
 cpan/Pod-Simple/t/xhtml10.t                            Pod::Simple test file
index 6a77fbd..32ff346 100755 (executable)
@@ -1574,7 +1574,7 @@ use File::Glob qw(:case);
 
     'Pod::Simple' => {
         'MAINTAINER'   => 'arandal',
-        'DISTRIBUTION' => 'DWHEELER/Pod-Simple-3.26.tar.gz',
+        'DISTRIBUTION' => 'DWHEELER/Pod-Simple-3.28.tar.gz',
         'FILES'        => q[cpan/Pod-Simple],
         'UPSTREAM'     => 'cpan',
     },
index c6bc739..73583f6 100644 (file)
@@ -1,6 +1,29 @@
 # ChangeLog for Pod::Simple dist
 #---------------------------------------------------------------------------
 
+2013-05-04   David E. Wheeler <david@justatheory.org>
+       * Release 3.28
+
+       Removed use of 'done_testing' in t/white.t, which was added in
+       v3.27. Thanks to Paul Howarth for the catch.
+
+       Fixed inproperly calculated number of skipped tests in t/xhtml01.t
+       when HTML::Entities is not intalled.
+
+2013-05-03   David E. Wheeler <david@justatheory.org>
+       * Release 3.27
+
+       Added new warnings as defined by Pod::Checker, thanks to RJBS:
+       + "=over" without "=back"
+       + "L<>" starts or ends with whitespace
+       + raw "|" or "/" in "L<text|link>" text
+
+       Added ->keep_encoding_directive, which is false by default, to
+       prevent formatters from emitting a document's '=encoding'
+       directive in most cases. That they emitted the encoding was a bug
+       introduced in v3.26 (RT #84093). Now, only the DumpAsText and
+       DumpAsXML formats set it to true. Patch from Patrice Dumas.
+
 2013-02-27   David E. Wheeler <david@justatheory.org>
        * Release 3.26
 
index 83164e8..1ff257f 100644 (file)
@@ -1,4 +1,4 @@
-=head1 Pod::Simple version 3.26
+=head1 Pod::Simple version 3.28
 
 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
 documentation") markup language that is typically used for writing
index f1c7625..fb5438f 100644 (file)
@@ -18,7 +18,7 @@ use vars qw(
 );
 
 @ISA = ('Pod::Simple::BlackBox');
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 @Known_formatting_codes = qw(I B C L E F S X Z); 
 %Known_formatting_codes = map(($_=>1), @Known_formatting_codes);
@@ -80,6 +80,7 @@ __PACKAGE__->_accessorize(
   'bare_output',       # For some subclasses: whether to prepend
                        #  header-code and postpend footer-code
 
+  'keep_encoding_directive',  # whether to emit =encoding
   'nix_X_codes',       # whether to ignore X<...> codes
   'merge_text',        # whether to avoid breaking a single piece of
                        #  text up into several events
@@ -1064,6 +1065,12 @@ sub _treat_Ls {  # Process our dear dear friends, the L<...> sequences
         $treelet->[$i] = 'L<>';  # just make it a text node
         next;  # and move on
       }
+
+      if( (! ref $ell->[2]  && $ell->[2] =~ /\A\s/)
+        ||(! ref $ell->[-1] && $ell->[-1] =~ /\s\z/)
+      ) {
+        $self->whine( $start_line, "L<> starts or ends with whitespace" );
+      }
      
       # Catch URLs:
 
@@ -1179,6 +1186,13 @@ sub _treat_Ls {  # Process our dear dear friends, the L<...> sequences
           DEBUG > 3 and
            print "     FOUND a '|' in it.  Splitting into [$1] + [$2]\n";
 
+          if ($link_text[0] =~ m{[|/]}) {
+            $self->whine(
+              $start_line,
+              "alternative text '$link_text[0]' contains non-escaped | or /"
+            );
+          }
+
           unshift @link_text, splice @ell_content, 0, $j;
             # leaving only things at J and after
           @ell_content =  grep ref($_)||length($_), @ell_content ;
index 99b629e..a1b5708 100644 (file)
@@ -23,7 +23,7 @@ use integer; # vroom!
 use strict;
 use Carp ();
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 #use constant DEBUG => 7;
 BEGIN {
   require Pod::Simple;
@@ -804,6 +804,7 @@ sub _ponder_paragraph_buffer {
       } elsif($para_type eq '=encoding') {
         # Not actually acted on here, but we catch errors here.
         $self->_handle_encoding_second_level($para);
+        next unless $self->keep_encoding_directive;
         $para_type = 'Plain';
       } elsif($para_type eq '~Verbatim') {
         $para->[0] = 'Verbatim';
@@ -1518,6 +1519,11 @@ sub _closers_for_all_curr_open {
     if($copy[0] eq '=for') {
       $copy[0] = '=end';
     } elsif($copy[0] eq '=over') {
+      $self->whine(
+        $still_open->[1]{start_line} ,
+        "=over without closing =back"
+      );
+
       $copy[0] = '=back';
     } else {
       die "I don't know how to auto-close an open $copy[0] region";
index ecdbe72..92e1bee 100644 (file)
@@ -9,7 +9,7 @@ use Carp ();
 use Pod::Simple::Methody ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG
index dc6437e..b170bb7 100644 (file)
@@ -3,7 +3,7 @@ require 5;
 package Pod::Simple::Debug;
 use strict;
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 sub import {
   my($value,$variable);
index 8ee50a7..019dfd5 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsText;
-$VERSION = '3.26';
+$VERSION = '3.28';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
@@ -16,6 +16,7 @@ sub new {
   my $new = $self->SUPER::new(@_);
   $new->{'output_fh'} ||= *STDOUT{IO};
   $new->accept_codes('VerbatimFormatted');
+  $new->keep_encoding_directive(1);
   return $new;
 }
 
index 4c25263..ac925c0 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsXML;
-$VERSION = '3.26';
+$VERSION = '3.28';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
@@ -17,6 +17,7 @@ sub new {
   my $new = $self->SUPER::new(@_);
   $new->{'output_fh'} ||= *STDOUT{IO};
   $new->accept_codes('VerbatimFormatted');
+  $new->keep_encoding_directive(1);
   return $new;
 }
 
index 2378ad7..8a2f815 100644 (file)
@@ -10,7 +10,7 @@ use vars qw(
   $Doctype_decl  $Content_decl
 );
 @ISA = ('Pod::Simple::PullParser');
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 BEGIN {
   if(defined &DEBUG) { } # no-op
index 8448a24..e41b11e 100644 (file)
@@ -5,7 +5,7 @@ use strict;
 use vars qw( $VERSION $HTML_RENDER_CLASS $HTML_EXTENSION
  $CSS $JAVASCRIPT $SLEEPY $SEARCH_CLASS @ISA
 );
-$VERSION = '3.26';
+$VERSION = '3.28';
 @ISA = ();  # Yup, we're NOT a subclass of Pod::Simple::HTML!
 
 # TODO: nocontents stylesheets. Strike some of the color variations?
index 0b5dbaa..be1f534 100644 (file)
@@ -3,12 +3,12 @@ require 5;
 package Pod::Simple::LinkSection;
   # Based somewhat dimly on Array::Autojoin
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 use strict;
 use Pod::Simple::BlackBox;
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 use overload( # So it'll stringify nice
   '""'   => \&Pod::Simple::BlackBox::stringify_lol,
index c509077..38acaa2 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::Methody;
 use strict;
 use Pod::Simple ();
 use vars qw(@ISA $VERSION);
-$VERSION = '3.26';
+$VERSION = '3.28';
 @ISA = ('Pod::Simple');
 
 # Yes, we could use named variables, but I want this to be impose
index 86ceaac..f9cd681 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::Progress;
-$VERSION = '3.26';
+$VERSION = '3.28';
 use strict;
 
 # Objects of this class are used for noting progress of an
index 41f557c..5c13724 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::PullParser;
-$VERSION = '3.26';
+$VERSION = '3.28';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
index b4f0207..5fa4023 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 sub new {  # Class->new(tagname);
   my $class = shift;
index ec65787..3edb0ad 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 sub new {  # Class->new(tagname, optional_attrhash);
   my $class = shift;
index c237ac4..a75fd7a 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 sub new {  # Class->new(text);
   my $class = shift;
index 305ef02..bbae51b 100644 (file)
@@ -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.26';
+$VERSION = '3.28';
 use strict;
 
 sub new {  # Class->new('type', stuff...);  ## Overridden in derived classes anyway
index eff7fba..067e6b9 100644 (file)
@@ -8,7 +8,7 @@ package Pod::Simple::RTF;
 
 use strict;
 use vars qw($VERSION @ISA %Escape $WRAP %Tagmap);
-$VERSION = '3.26';
+$VERSION = '3.28';
 use Pod::Simple::PullParser ();
 BEGIN {@ISA = ('Pod::Simple::PullParser')}
 
index 216ad9b..15cb292 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::Search;
 use strict;
 
 use vars qw($VERSION $MAX_VERSION_WITHIN $SLEEPY);
-$VERSION = '3.26';   ## Current version of this package
+$VERSION = '3.28';   ## Current version of this package
 
 BEGIN { *DEBUG = sub () {0} unless defined &DEBUG; }   # set DEBUG level
 use Carp ();
index 025b922..0b42a22 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '3.26';
+$VERSION = '3.28';
 BEGIN {
   @ISA = ('Pod::Simple');
   *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG;
index 720ba66..7a7976b 100644 (file)
@@ -12,22 +12,22 @@ Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
   use strict;
 
   sub _handle_element_start {
-    my($parser, $element_name, $attr_hash_r) = @_;
-    ...
+       my($parser, $element_name, $attr_hash_r) = @_;
+       ...
   }
 
   sub _handle_element_end {
-    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.
-    ...
+       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.
+       ...
   }
 
   sub _handle_text {
-    my($parser, $text) = @_;
-    ...
+       my($parser, $text) = @_;
+       ...
   }
   1;
 
@@ -105,13 +105,13 @@ TODO describe
 Parsing a document produces this event structure:
 
   <Document start_line="543">
-    ...all events...
+       ...all events...
   </Document>
 
 The value of the I<start_line> attribute will be the line number of the first
 Pod directive in the document.
 
-If there is no Pod in the given document, then the 
+If there is no Pod in the given document, then the
 event structure will be this:
 
   <Document contentless="1" start_line="543">
@@ -126,9 +126,9 @@ last line in the file.
 Parsing a plain (non-verbatim, non-directive, non-data) paragraph in
 a Pod document produces this event structure:
 
-    <Para start_line="543">
-      ...all events in this paragraph...
-    </Para>
+       <Para start_line="543">
+         ...all events in this paragraph...
+       </Para>
 
 The value of the I<start_line> attribute will be the line number of the start
 of the paragraph.
@@ -140,14 +140,14 @@ For example, parsing this paragraph of Pod:
 
 produces this event structure:
 
-    <Para start_line="129">
-      The value of the 
-      <I>
-        start_line
-      </I>
-       attribute will be the line number of the first Pod directive
-      in the document.
-    </Para>
+       <Para start_line="129">
+         The value of the
+         <I>
+               start_line
+         </I>
+          attribute will be the line number of the first Pod directive
+         in the document.
+       </Para>
 
 =item events with an element_name of B, C, F, or I.
 
@@ -157,9 +157,9 @@ S<BE<lt>E<lt> ... E<gt>E<gt>>,
 or S<BE<lt>E<lt>E<lt>E<lt> ... E<gt>E<gt>E<gt>E<gt>>, etc.)
 produces this event structure:
 
-      <B>
-        ...stuff...
-      </B>
+         <B>
+               ...stuff...
+         </B>
 
 Currently, there are no attributes conveyed.
 
@@ -175,9 +175,9 @@ any attributes.
 Normally, parsing an SE<lt>...E<gt> sequence produces this event
 structure, just as if it were a B/C/F/I code:
 
-      <S>
-        ...stuff...
-      </S>
+         <S>
+               ...stuff...
+         </S>
 
 However, Pod::Simple (and presumably all derived parsers) offers the
 C<nbsp_for_S> option which, if enabled, will suppress all S events, and
@@ -191,9 +191,9 @@ means non-breaking space.
 Normally, parsing an XE<lt>...E<gt> sequence produces this event
 structure, just as if it were a B/C/F/I code:
 
-      <X>
-        ...stuff...
-      </X>
+         <X>
+               ...stuff...
+         </X>
 
 However, Pod::Simple (and presumably all derived parsers) offers the
 C<nix_X_codes> option which, if enabled, will suppress all X events
@@ -219,7 +219,7 @@ When a LE<lt>I<some_url>E<gt> code is parsed, it produces this event
 structure:
 
   <L content-implicit="yes" raw="that_url" to="that_url" type="url">
-    that_url
+       that_url
   </L>
 
 The C<type="url"> attribute is always specified for this type of
@@ -232,14 +232,14 @@ For example, this Pod source:
 produces this event structure:
 
   <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/
+       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" raw="manpage(section)" to="manpage(section)" type="man">
-    manpage(section)
+       manpage(section)
   </L>
 
 The C<type="man"> attribute is always specified for this type of
@@ -252,7 +252,7 @@ For example, this Pod source:
 produces this event structure:
 
   <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
-    crontab(5)
+       crontab(5)
   </L>
 
 In the rare cases where a man page link has a specified, that text appears
@@ -263,7 +263,7 @@ in a I<section> attribute. For example, this Pod source:
 will produce this event structure:
 
   <L content-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
-    "ENVIRONMENT" in crontab(5)
+       "ENVIRONMENT" in crontab(5)
   </L>
 
 In the rare case where the Pod document has code like
@@ -283,7 +283,7 @@ For example, this Pod source:
 will produce this event structure:
 
   <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
-    hell itself!
+       hell itself!
   </L>
 
 The last type of L structure is for links to/within Pod documents. It is
@@ -295,7 +295,7 @@ In the most common case, the simple case of a LE<lt>podpageE<gt> code
 produces this event structure:
 
   <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
-    podpage
+       podpage
   </L>
 
 For example, this Pod source:
@@ -305,7 +305,7 @@ For example, this Pod source:
 produces this event structure:
 
   <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
-    Net::Ping
+       Net::Ping
   </L>
 
 In cases where there is link-text explicitly specified, it
@@ -318,7 +318,7 @@ case discussed above.  For example, this Pod source:
 produces this event structure:
 
   <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
-    Perl Error Messages
+       Perl Error Messages
   </L>
 
 In cases of links to a section in the current Pod document,
@@ -330,7 +330,7 @@ For example, this Pod source:
 produces this event structure:
 
   <L content-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
-    "Member Data"
+       "Member Data"
   </L>
 
 As another example, this Pod source:
@@ -340,7 +340,7 @@ As another example, this Pod source:
 produces this event structure:
 
   <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
-    the various attributes
+       the various attributes
   </L>
 
 In cases of links to a section in a different Pod document,
@@ -352,7 +352,7 @@ For example, this Pod source:
 produces this event structure:
 
   <L content-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
-    "Basic BLOCKs and Switch Statements" in perlsyn
+       "Basic BLOCKs and Switch Statements" in perlsyn
   </L>
 
 As another example, this Pod source:
@@ -362,7 +362,7 @@ As another example, this Pod source:
 produces this event structure:
 
   <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
-    SWITCH statements
+       SWITCH statements
   </L>
 
 Incidentally, note that we do not distinguish between these syntaxes:
@@ -375,7 +375,7 @@ Incidentally, note that we do not distinguish between these syntaxes:
 That is, they all produce the same event structure (for the most part), namely:
 
   <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
-    &#34;Member Data&#34;
+       &#34;Member Data&#34;
   </L>
 
 The I<raw> attribute depends on what the raw content of the C<LE<lt>E<gt>> is,
@@ -389,7 +389,7 @@ by the following C<LE<lt>E<gt>> 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>
+       click B<here>
   </L>
 
 Specifically, notice that the formatting codes are present and unescaped
@@ -411,7 +411,7 @@ When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
 produces this event structure:
 
   <Verbatim start_line="543" xml:space="preserve">
-    ...text...
+       ...text...
   </Verbatim>
 
 The value of the I<start_line> attribute will be the line number of the
@@ -427,7 +427,7 @@ When a "=head1 ..." directive is parsed, it produces this event
 structure:
 
   <head1>
-    ...stuff...
+       ...stuff...
   </head1>
 
 For example, a directive consisting of this:
@@ -437,26 +437,33 @@ For example, a directive consisting of this:
 will produce this event structure:
 
   <head1 start_line="543">
-    Options to 
-    <C>
-      new
-    </C>
-     et al.
+       Options to
+       <C>
+         new
+       </C>
+        et al.
   </head1>
 
 "=head2" thru "=head4" directives are the same, except for the element
 names in the event structure.
 
+=item events with an element_name of encoding
+
+In the default case, the events corresponding to C<=encoding> directives
+are not emitted. They are emitted if C<keep_encoding_directive> is true.
+In that case they produce event structures like
+L</"events with an element_name of head1 .. head4"> above.
+
 =item events with an element_name of over-bullet
 
 When an "=over ... Z<>=back" block is parsed where the items are
 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...
+       <item-bullet start_line="545">
+         ...Stuff...
+       </item-bullet>
+       ...more item-bullets...
   </over-bullet fake-closer="1">
 
 The attribute I<fake-closer> is only present if it is a true value; it is not
@@ -509,12 +516,12 @@ For example, this Pod source:
 produces this event structure:
 
   <over-bullet indent="4" start_line="10">
-    <item-bullet start_line="12">
-      Stuff
-    </item-bullet>
-    <item-bullet start_line="14">
-      Bar <I>baz</I>!
-    </item-bullet>
+       <item-bullet start_line="12">
+         Stuff
+       </item-bullet>
+       <item-bullet start_line="14">
+         Bar <I>baz</I>!
+       </item-bullet>
   </over-bullet>
 
 =item events with an element_name of over-number
@@ -523,10 +530,10 @@ When an "=over ... Z<>=back" block is parsed where the items are
 a numbered list, it will produce this event structure:
 
   <over-number indent="4" start_line="543">
-    <item-number number="1" start_line="545">
-      ...Stuff...
-    </item-number>
-    ...more item-number...
+       <item-number number="1" start_line="545">
+         ...Stuff...
+       </item-number>
+       ...more item-number...
   </over-bullet>
 
 This is like the "over-bullet" event structure; but note that the contents
@@ -550,12 +557,12 @@ an "=over ... Z<>=back" block is parsed where the items are
 a list of text "subheadings", it will produce this event structure:
 
   <over-text indent="4" start_line="543">
-    <item-text>
-      ...stuff...
-    </item-text>
-    ...stuff (generally Para or Verbatim elements)...
-    <item-text>
-    ...more item-text and/or stuff...
+       <item-text>
+         ...stuff...
+       </item-text>
+       ...stuff (generally Para or Verbatim elements)...
+       <item-text>
+       ...more item-text and/or stuff...
   </over-text>
 
 The I<indent> and I<fake-closer> attributes are as with the other over-* events.
@@ -577,22 +584,22 @@ For example, this Pod source:
 produces this event structure:
 
   <over-text indent="4" start_line="20">
-    <item-text start_line="22">
-      Foo
-    </item-text>
-    <Para start_line="24">
-      Stuff
-    </Para>
-    <item-text start_line="26">
-      Bar
-        <I>
-          baz
-        </I>
-      !
-    </item-text>
-    <Para start_line="28">
-      Quux
-    </Para>
+       <item-text start_line="22">
+         Foo
+       </item-text>
+       <Para start_line="24">
+         Stuff
+       </Para>
+       <item-text start_line="26">
+         Bar
+               <I>
+                 baz
+               </I>
+         !
+       </item-text>
+       <Para start_line="28">
+         Quux
+       </Para>
   </over-text>
 
 
@@ -605,7 +612,7 @@ an "=over ... Z<>=back" block is parsed where there are no items,
 it will produce this event structure:
 
   <over-block indent="4" start_line="543">
-    ...stuff (generally Para or Verbatim elements)...
+       ...stuff (generally Para or Verbatim elements)...
   </over-block>
 
 The I<indent> and I<fake-closer> attributes are as with the other over-* events.
@@ -628,15 +635,15 @@ For example, this Pod source:
 will produce this event structure:
 
   <over-block indent="4" start_line="2">
-    <Para start_line="4">
-      For cutting off our trade with all parts of the world
-    </Para>
-    <Para start_line="6">
-      For transporting us beyond seas to be tried for pretended offenses
-    </Para>
-    <Para start_line="8">
-      He is at this time transporting large armies of [...more text...]
-    </Para>
+       <Para start_line="4">
+         For cutting off our trade with all parts of the world
+       </Para>
+       <Para start_line="6">
+         For transporting us beyond seas to be tried for pretended offenses
+       </Para>
+       <Para start_line="8">
+         He is at this time transporting large armies of [...more text...]
+       </Para>
   </over-block>
 
 =item events with an element_name of over-empty
@@ -666,12 +673,12 @@ For example, this Pod source:
 will produce this event structure:
 
   <over-block indent="4" start_line="1">
-    <over-empty indent="4" start_line="3">
-    </over-empty>
+       <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 
+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
@@ -714,15 +721,15 @@ the ones described in the I<perlpod>.
 
 As the parser sees sections like:
 
-    =for html  <img src="fig1.jpg">
+       =for html  <img src="fig1.jpg">
 
 or
 
-    =begin html
+       =begin html
 
-      <img src="fig1.jpg">
+         <img src="fig1.jpg">
 
-    =end html
+       =end html
 
 ...the parser will ignore these sections unless your subclass has
 specified that it wants to see sections targeted to "html" (or whatever
@@ -749,7 +756,7 @@ beyond just the standard ones (I B C L F S X, plus the two weird ones
 you don't actually see in the parse tree, Z and E). For example, to also
 accept codes "N", "R", and "W":
 
-    $parser->accept_codes( qw( N R W ) );
+       $parser->accept_codes( qw( N R W ) );
 
 B<TODO: document how this interacts with =extend, and long element names>
 
@@ -769,11 +776,11 @@ all), or as verbatim (mostly just expanding tabs), or as processed text
 For example, to accept a new directive "=method", you'd presumably
 use:
 
-    $parser->accept_directive_as_processed("method");
+       $parser->accept_directive_as_processed("method");
 
 so that you could have Pod lines like:
 
-    =method I<$whatever> thing B<um>
+       =method I<$whatever> thing B<um>
 
 Making up your own directives breaks compatibility with other Pod
 formatters, in a way that using "=for I<target> ..." lines doesn't;
@@ -787,11 +794,11 @@ Setting this attribute to a true value (and by default it is false) will
 turn "SE<lt>...E<gt>" sequences into sequences of words separated by
 C<\xA0> (non-breaking space) characters. For example, it will take this:
 
-    I like S<Dutch apple pie>, don't you?
+       I like S<Dutch apple pie>, don't you?
 
 and treat it as if it were:
 
-    I like DutchE<nbsp>appleE<nbsp>pie, don't you?
+       I like DutchE<nbsp>appleE<nbsp>pie, don't you?
 
 This is handy for output formats that don't have anything quite like an
 "SE<lt>...E<gt>" code, but which do have a code for non-breaking space.
@@ -808,7 +815,7 @@ L<perlpodspec> requires output formats (wherever possible) to note
 this detail in a comment in the output format.  For example, for
 some kind of SGML output format:
 
-    print OUT "<!-- \n", $parser->version_report, "\n -->";
+       print OUT "<!-- \n", $parser->version_report, "\n -->";
 
 
 =item C<< $parser->pod_para_count() >>
@@ -829,6 +836,15 @@ ignores any "XE<lt>...E<gt>" sequences in the document being parsed.
 Many formats don't actually use the content of these codes, so have
 no reason to process them.
 
+=item C<< $parser->keep_encoding_directive(  I<SOMEVALUE>  ) >>
+
+This attribute, when set to a true value (it is false by default)
+will keep C<=encoding> and its content in the event structure. Most
+formats don't actually need to process the content of an C<=encoding>
+directive, even when this directive sets the encoding and the
+processor makes use of the encoding information. Indeed, it is
+possible to know the encoding without processing the directive
+content.
 
 =item C<< $parser->merge_text(  I<SOMEVALUE>  ) >>
 
@@ -837,7 +853,7 @@ makes sure that only one event (or token, or node) will be created
 for any single contiguous sequence of text.  For example, consider
 this somewhat contrived example:
 
-    I just LOVE Z<>hotE<32>apple pie!
+       I just LOVE Z<>hotE<32>apple pie!
 
 When that is parsed and events are about to be called on it, it may
 actually seem to be four different text events, one right after another:
@@ -853,10 +869,10 @@ This specifies code that should be called when a code line is seen
 that no code should be called.  If you provide a routine, it should
 start out like this:
 
-    sub get_code_line {  # or whatever you'll call it
-      my($line, $line_number, $parser) = @_;
-      ...
-    }
+       sub get_code_line {  # or whatever you'll call it
+         my($line, $line_number, $parser) = @_;
+         ...
+       }
 
 Note, however, that sometimes the Pod events aren't processed in exactly
 the same order as the code lines are -- i.e., if you have a file with
@@ -1053,5 +1069,3 @@ Yes, L<...> is hard.
 
 
 =cut
-
-
index 7971227..bd1a541 100644 (file)
@@ -6,7 +6,7 @@ use Carp ();
 use Pod::Simple::Methody ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION $FREAKYMODE);
-$VERSION = '3.26';
+$VERSION = '3.28';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG
index ca29d54..6788df6 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 @ISA = ('Pod::Simple');
 
 sub new {
index 1428e30..0b2fb2f 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::TiedOutFH;
 use Symbol ('gensym');
 use Carp ();
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
index e0faa4c..9e83504 100644 (file)
@@ -2,7 +2,7 @@
 require 5;
 package Pod::Simple::Transcode;
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 BEGIN {
   if(defined &DEBUG) {;} # Okay
index 374dfb2..4749e9a 100644 (file)
@@ -5,7 +5,7 @@ require 5;
 package Pod::Simple::TranscodeDumb;
 use strict;
 use vars qw($VERSION %Supported);
-$VERSION = '3.26';
+$VERSION = '3.28';
 # This module basically pretends it knows how to transcode, except
 #  only for null-transcodings!  We use this when Encode isn't
 #  available.
index f1fc640..06fdb9f 100644 (file)
@@ -9,7 +9,7 @@ use strict;
 use Pod::Simple;
 require Encode;
 use vars qw($VERSION );
-$VERSION = '3.26';
+$VERSION = '3.28';
 
 sub is_dumb  {0}
 sub is_smart {1}
index b38a408..df896e6 100644 (file)
@@ -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.26';
+$VERSION = '3.28';
 use Pod::Simple::Methody ();
 @ISA = ('Pod::Simple::Methody');
 
index 7dc604e..47496e2 100644 (file)
@@ -5,7 +5,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '3.26';
+$VERSION = '3.28';
 BEGIN {
   @ISA = ('Pod::Simple');
   *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG;
@@ -20,6 +20,7 @@ sub new {
   my $self = shift;
   my $new = $self->SUPER::new(@_);
   $new->{'output_fh'} ||= *STDOUT{IO};
+  $new->keep_encoding_directive(1);
   #$new->accept_codes('VerbatimFormatted');
   return $new;
 }
index 5ad848e..16e6c5d 100644 (file)
@@ -115,7 +115,7 @@ SUBCLASS: {
 ok(
     My::Pod::HTML->_out(
         sub{  $_[0]->bare_output(1)  },
-        "=pod\n\n=over\n\n=item Foo\n\n",
+        "=pod\n\n=over\n\n=item Foo\n\n=back\n",
     ),
     "\n<dl>\n<dt><a name=\"howdy\"\n>Foo</a></dt>\n</dl>\n",
 );
index 630ef87..f76cf59 100644 (file)
@@ -189,18 +189,22 @@ ok( $x->_out( join "\n\n", '', '',
 $d = 11;
 print "# Now checking that document-end closes things right...\n";
 
-ok( $x->_out( join "\n\n", '', '', 
-  '=over',
-    '=item *',
-    'Stuff',
-    '=cut',
-    'Stuff',
+ok( $x->_out(
+  # We know there'd be a warning about implicit =back; disable it!
+  sub { $_[0]->no_whining(1); },
+  join( "\n\n", '', '',
     '=over',
-      '=item 1.',
-        '=over 19',
-        'Gleiven',
-        'Squim F<.thingrc>!',
-  '', ''
+      '=item *',
+      'Stuff',
+      '=cut',
+      'Stuff',
+      '=over',
+        '=item 1.',
+          '=over 19',
+          'Gleiven',
+          'Squim F<.thingrc>!',
+    '', '',
+  ),
   ), join '',
    '<Document>',
    '<over-bullet indent="4">',
diff --git a/cpan/Pod-Simple/t/whine.t b/cpan/Pod-Simple/t/whine.t
new file mode 100644 (file)
index 0000000..668c909
--- /dev/null
@@ -0,0 +1,69 @@
+use strict;
+use warnings;
+use Test::More tests => 4;
+
+{
+  package Pod::Simple::ErrorFinder;
+  use base 'Pod::Simple::DumpAsXML'; # arbitrary choice -- rjbs, 2013-04-16
+
+  my @errors;
+  sub whine {
+    my ($self, @rest) = @_;
+    push @errors, [ @rest ];
+    $self->SUPER::whine(@rest);
+  }
+
+  sub scream {
+    my ($self, @rest) = @_;
+    push @errors, [ @rest ];
+    $self->SUPER::scream(@rest);
+  }
+
+  sub errors_for_input {
+    my ($class, $input, $mutor) = @_;
+    @errors = ();
+
+    my $parser = $class->new;
+    my $output = '';
+    $parser->output_string( \$output );
+    $parser->parse_string_document( $input );
+
+    @errors = sort { $a->[0] <=> $b->[0]
+                  || $a->[1] cmp $b->[1] } @errors;
+
+    return @errors;
+  }
+}
+
+sub errors { Pod::Simple::ErrorFinder->errors_for_input(@_) }
+
+{
+  my @errors = errors("=over 4\n\n=item 1\n\nHey\n\n");
+  is_deeply(
+    \@errors,
+    [ [ 1, "=over without closing =back" ] ],
+    "no closing =back",
+  );
+}
+
+{
+  for my $l_code ('L< foo>', 'L< bar>') {
+    my $input = "=pod\n\nAmbiguous space: $l_code\n";
+    my @errors = errors("$input");
+    is_deeply(
+      \@errors,
+      [ [ 3, "L<> starts or ends with whitespace" ] ],
+      "warning for space in $l_code",
+    );
+  }
+}
+
+{
+  my $input = "=pod\n\nAmbiguous slash: L<I/O Operators|op/io>\n";
+  my @errors = errors("$input");
+  is_deeply(
+    \@errors,
+    [ [ 3, "alternative text 'I/O Operators' contains non-escaped | or /" ] ],
+    "warning for / in text part of L<>",
+  );
+}
index b31260b..fd177ed 100644 (file)
@@ -8,8 +8,8 @@ BEGIN {
 
 use strict;
 use lib '../lib';
-#use Test::More tests => 56;
-use Test::More 'no_plan';
+use Test::More tests => 61;
+#use Test::More 'no_plan';
 
 use_ok('Pod::Simple::XHTML') or exit;
 
@@ -662,7 +662,7 @@ EOHTML
 
 SKIP: for my $use_html_entities (0, 1) {
   if ($use_html_entities and not $Pod::Simple::XHTML::HAS_HTML_ENTITIES) {
-    skip("HTML::Entities not installed", 1);
+    skip("HTML::Entities not installed", 3);
   }
   local $Pod::Simple::XHTML::HAS_HTML_ENTITIES = $use_html_entities;
   initialize($parser, $results);
@@ -698,6 +698,14 @@ is($results, <<"EOHTML", 'HTML Entities should be only for specified characters'
 
 EOHTML
 
+  # Keep =encoding out of content.
+  initialize($parser, $results);
+  $parser->parse_string_document("=encoding utf-8\n\n=head1 NAME\n");
+  is($results, <<"EOHTML", 'Encoding should not be in content')
+<h1 id="NAME">NAME</h1>
+
+EOHTML
+
 }