Upgrade to Pod-Simple 3.23

MANIFEST

@@ -2086,6 +2086,10 @@ cpan/Pod-Simple/t/corpus/8859_7.pod			Pod::Simple test file
 cpan/Pod-Simple/t/corpus/8859_7.xml			Pod::Simple test file
 cpan/Pod-Simple/t/corpus/cp1256.txt			Pod::Simple test file
 cpan/Pod-Simple/t/corpus/cp1256.xml			Pod::Simple test file
+cpan/Pod-Simple/t/corpus/encwarn01.txt			Pod::Simple test file
+cpan/Pod-Simple/t/corpus/encwarn01.xml			Pod::Simple test file
+cpan/Pod-Simple/t/corpus/encwarn02.txt			Pod::Simple test file
+cpan/Pod-Simple/t/corpus/encwarn02.xml			Pod::Simple test file
 cpan/Pod-Simple/t/corpus/fet_cont.txt			Pod::Simple test file
 cpan/Pod-Simple/t/corpus/fet_cont.xml			Pod::Simple test file
 cpan/Pod-Simple/t/corpus/fet_dup.txt			Pod::Simple test file
@@ -2203,6 +2207,7 @@ 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
 cpan/Pod-Simple/t/xhtml15.t				Pod::Simple test file
+cpan/Pod-Simple/t/xhtml20.t				Pod::Simple test file
 cpan/Pod-Simple/t/x_nixer.t				Pod::Simple test file
 cpan/Socket/Makefile.PL			Socket extension makefile writer
 cpan/Socket/Socket.pm			Socket extension Perl module

Porting/Maintainers.pl

@@ -1546,7 +1546,7 @@ package Maintainers;
 
     'Pod::Simple' => {
         'MAINTAINER'   => 'arandal',
-        'DISTRIBUTION' => 'DWHEELER/Pod-Simple-3.20.tar.gz',
+        'DISTRIBUTION' => 'DWHEELER/Pod-Simple-3.23.tar.gz',
         'FILES'        => q[cpan/Pod-Simple],
         'UPSTREAM'     => 'cpan',
     },

cpan/Pod-Simple/ChangeLog

@@ -1,6 +1,71 @@
 # ChangeLog for Pod::Simple dist
 #---------------------------------------------------------------------------
 
+2012-08-14   David E. Wheeler <david@justatheory.org>
+	* Release 3.23
+
+	Eliminated nested elements in table of contents (index) items
+	output of Pod::Simple::XHTML. This was especially problematic for
+	headers that included links, as the TOC then got nested anchor
+	elements, which simply would not work. Thanks to Ben Bullock for
+	the report and test case (RT #77686).
+
+	Fixed semantically invalid nested XHTML generated by
+	Pod::Simple::XHTML since v3.21. Gisle Aas.
+
+	Improved support for nested "C< >" tags in Pod::Simple::XHTML.
+	Gisle Aas.
+
+	No longer tries to decode a string with the "utf8" flag set, as
+	the double-decoding only triggered an error. Grant McLean.
+
+	Added documentation note that the API expects encoded text
+	(octets). Grant McLean.
+
+	Added "parse_characters()" option to specify that strings to are
+	already decoded from octets into characters. Grant McLean.
+
+2012-05-27   David E. Wheeler <david@justatheory.org>
+	* Release 3.22
+
+	Fix but where Pod::Simple would whine about non-ASCII bytes in
+	code or comments. Now only does so for Pod (in the absence of an
+	"=encoding" tag. Broken in 3.21. Grant McLean.
+
+2012-05-23   David E. Wheeler <david@justatheory.org>
+	* Release 3.21
+
+	NOTE: COMPATABILITY CHANGE: The 'codes_in_verbatim' option in
+	Pod::Simple::XHTML is no longer enabled by default. This brings it
+	agreement with the other formatting classes, and eliminates
+	unexpected behavior in XHTML-formatted Pod. Users who depended on
+	this functionality can still get it by enabling
+	'codes_in_verbatim' in their code.
+
+	Fixed some typos in the documentation. Thanks to Jonathan Yu via
+	the Debian packagers via Florian Ragwitz (RT #75532).
+
+	Now emit a warning the first time a non-ASCII byte is encountered
+	when no "=encoding" has been seen. Grant McLean.
+
+	When a non-ASCII byte is encounted before an "=encoding" line has
+	been seen, a heuristic (as described in perlpodspec) is applied to
+	select UTF-8 encoding if the non-ASCII bytes form a valid UTF-8
+	byte sequence, or Latin-1 otherwise. Grant McLean.
+
+	Added 'handle_code' method to Pod::Simple::XHTML. This allows
+	subclasses to override the handling of verbatim blocks, and makes
+	for a more cohesive interface, to boot. Gisle Aas.
+
+	Subsequent text segments are now joined together and passed as a
+	single unit to text handling code. This makes it easier for custom
+	handlers to process complete blocks of text in a single call to
+	'handle_text', rather than in dribs and drabs. Gisle Aas.
+
+	Replaced naive text wrapping code in Pod::Simple::DumpAsXML with
+	Text::Wrap, which was already used for similar purposes elsewhere
+	in Pod::Simple. Gisle Aas.
+
 2012-03-01   David E. Wheeler <david@justatheory.org>
 	* Release 3.20
 

cpan/Pod-Simple/README

@@ -1,4 +1,4 @@
-=head1 Pod::Simple version 3.20
+=head1 Pod::Simple version 3.23
 
 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
 documentation") markup language that is typically used for writing

cpan/Pod-Simple/lib/Pod/Simple.pm

@@ -18,7 +18,7 @@ use vars qw(
 );
 
 @ISA = ('Pod::Simple::BlackBox');
-$VERSION = '3.20';
+$VERSION = '3.23';
 
 @Known_formatting_codes = qw(I B C L E F S X Z); 
 %Known_formatting_codes = map(($_=>1), @Known_formatting_codes);
@@ -87,6 +87,8 @@ __PACKAGE__->_accessorize(
   'preserve_whitespace', # whether to try to keep whitespace as-is
   'strip_verbatim_indent', # What indent to strip from verbatim
 
+  'parse_characters',  # Whether parser should expect chars rather than octets
+
  'content_seen',      # whether we've seen any real Pod content
  'errors_seen',       # TODO: document.  whether we've seen any errors (fatal or not)
 

cpan/Pod-Simple/lib/Pod/Simple.pod

@@ -14,6 +14,8 @@ documentation") markup language that is typically used for writing
 documentation for Perl and for Perl modules. The Pod format is explained
 L<perlpod>; the most common formatter is called C<perldoc>.
 
+Be sure to read L</ENCODING> if your Pod contains non-ASCII characters.
+
 Pod formatters can use Pod::Simple to parse Pod documents and render them into
 plain text, HTML, or any number of other formats. Typically, such formatters
 will be subclasses of Pod::Simple, and so they will inherit its methods, like
@@ -121,6 +123,14 @@ most likely to use.
 
 =over
 
+=item C<< $parser->parse_characters( I<SOMEVALUE> ) >>
+
+The Pod parser normally expects to read octets and to convert those octets
+to characters based on the C<=encoding> declaration in the Pod source.  Set
+this option to a true value to indicate that the Pod source is already a Perl
+character stream.  This tells the parser to ignore any C<=encoding> command
+and to skip all the code paths involving decoding octets.
+
 =item C<< $parser->no_whining( I<SOMEVALUE> ) >>
 
 If you set this attribute to a true value, you will suppress the
@@ -322,6 +332,21 @@ Log an error unless C<< $parser->no_whining( TRUE ); >>.
 
 =back
 
+=head1 ENCODING
+
+The Pod::Simple parser expects to read B<octets>.  The parser will decode the
+octets into Perl's internal character string representation using the value of
+the C<=encoding> declaration in the POD source.
+
+If the POD source does not include an C<=encoding> declaration, the parser will
+attempt to guess the encoding (selecting one of UTF-8 or Latin-1) by examining
+the first non-ASCII bytes and applying the heuristic described in
+L<perlpodspec>.
+
+If you set the C<parse_characters> option to a true value the parser will
+expect characters rather than octets; will ignore any C<=encoding>; and will
+make no attempt to decode the input.
+
 =head1 CAVEATS
 
 This is just a beta release -- there are a good number of things still

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.20';
+$VERSION = '3.23';
 #use constant DEBUG => 7;
 BEGIN {
   require Pod::Simple;
@@ -123,6 +123,9 @@ sub parse_lines {             # Usage: $parser->parse_lines(@lines)
       }
     }
 
+    if(!$self->parse_characters && !$self->{'encoding'}) {
+      $self->_try_encoding_guess($line)
+    }
 
     DEBUG > 5 and print "# Parsing line: [$line]\n";
 
@@ -176,6 +179,7 @@ sub parse_lines {             # Usage: $parser->parse_lines(@lines)
 
     # HERE WE CATCH =encoding EARLY!
     if( $line =~ m/^=encoding\s+\S+\s*$/s ) {
+      next if $self->parse_characters;   # Ignore this line
       $line = $self->_handle_encoding_line( $line );
     }
 
@@ -269,6 +273,8 @@ sub parse_lines {             # Usage: $parser->parse_lines(@lines)
 sub _handle_encoding_line {
   my($self, $line) = @_;
 
+  return if $self->parse_characters;
+
   # The point of this routine is to set $self->{'_transcoder'} as indicated.
 
   return $line unless $line =~ m/^=encoding\s+(\S+)\s*$/s;
@@ -395,6 +401,28 @@ sub _handle_encoding_second_level {
   return;
 }
 
+sub _try_encoding_guess {
+  my ($self,$line) = @_;
+
+  if(!$self->{'in_pod'}  and  $line !~ /^=/m) {
+    return;  # don't whine about non-ASCII bytes in code/comments
+  }
+
+  return unless $line =~ /[^\x00-\x7f]/;  # Look for non-ASCII byte
+
+  my $encoding = $line =~ /[\xC0-\xFD][\x80-\xBF]/ ? 'UTF-8' : 'ISO8859-1';
+  $self->_handle_encoding_line( "=encoding $encoding" );
+  $self->{'_transcoder'} && $self->{'_transcoder'}->($line);
+
+  my ($word) = $line =~ /(\S*[^\x00-\x7f]\S*)/;
+
+  $self->whine(
+    $self->{'line_count'},
+    "Non-ASCII character seen before =encoding in '$word'. Assuming $encoding"
+  );
+
+}
+
 #~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`~`
 
 {
@@ -1459,10 +1487,12 @@ sub _traverse_treelet_bit {  # for use only by the routine above
   my $scratch;
   $self->_handle_element_start(($scratch=$name), shift @_);
 
-  foreach my $x (@_) {
-    if(ref($x)) {
+  while (@_) {
+    my $x = shift;
+    if (ref($x)) {
       &_traverse_treelet_bit($self, @$x);
     } else {
+      $x .= shift while @_ && !ref($_[0]);
       $self->_handle_text($x);
     }
   }

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.20';
+$VERSION = '3.23';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG

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.20';
+$VERSION = '3.23';
 
 sub import {
   my($value,$variable);

cpan/Pod-Simple/lib/Pod/Simple/DumpAsText.pm

@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsText;
-$VERSION = '3.20';
+$VERSION = '3.23';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 

cpan/Pod-Simple/lib/Pod/Simple/DumpAsXML.pm

@@ -1,13 +1,14 @@
 
 require 5;
 package Pod::Simple::DumpAsXML;
-$VERSION = '3.20';
+$VERSION = '3.23';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
 use strict;
 
 use Carp ();
+use Text::Wrap qw(wrap);
 
 BEGIN { *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG }
 
@@ -49,15 +50,8 @@ sub _handle_text {
     my $indent = '  ' x $_[0]{'indent'};
     my $text = $_[1];
     _xml_escape($text);
-    $text =~  # A not-totally-brilliant wrapping algorithm:
-      s/(
-         [^\n]{55}         # Snare some characters from a line
-         [^\n\ ]{0,50}     #  and finish any current word
-        )
-        \x20{1,10}(?!\n)   # capture some spaces not at line-end
-       /$1\n$indent/gx     # => line-break here
-    ;
-
+    local $Text::Wrap::huge = 'overflow';
+    $text = wrap('', $indent, $text);
     print {$_[0]{'output_fh'}} $indent, $text, "\n";
   }
   return;

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.20';
+$VERSION = '3.23';
 
 BEGIN {
   if(defined &DEBUG) { } # no-op

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.20';
+$VERSION = '3.23';
 @ISA = ();  # Yup, we're NOT a subclass of Pod::Simple::HTML!
 
 # TODO: nocontents stylesheets. Strike some of the color variations?

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.20';
+$VERSION = '3.23';
 
 use strict;
 use Pod::Simple::BlackBox;
 use vars qw($VERSION );
-$VERSION = '3.20';
+$VERSION = '3.23';
 
 use overload( # So it'll stringify nice
   '""'   => \&Pod::Simple::BlackBox::stringify_lol,

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.20';
+$VERSION = '3.23';
 @ISA = ('Pod::Simple');
 
 # Yes, we could use named variables, but I want this to be impose

cpan/Pod-Simple/lib/Pod/Simple/Progress.pm

@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::Progress;
-$VERSION = '3.20';
+$VERSION = '3.23';
 use strict;
 
 # Objects of this class are used for noting progress of an

cpan/Pod-Simple/lib/Pod/Simple/PullParser.pm

@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::PullParser;
-$VERSION = '3.20';
+$VERSION = '3.23';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 

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.20';
+$VERSION = '3.23';
 
 sub new {  # Class->new(tagname);
   my $class = shift;

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.20';
+$VERSION = '3.23';
 
 sub new {  # Class->new(tagname, optional_attrhash);
   my $class = shift;

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.20';
+$VERSION = '3.23';
 
 sub new {  # Class->new(text);
   my $class = shift;