This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update Pod-Simple to CPAN version 3.16
authorChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Tue, 15 Mar 2011 16:47:47 +0000 (16:47 +0000)
committerChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Tue, 15 Mar 2011 16:47:47 +0000 (16:47 +0000)
  [DELTA]

  2011-03-14   David E. Wheeler <david@justatheory.org>
        * Release 3.16

        Fixed invalid HTML generated for nested lists by Pod::Simple::XHTML
        (Fitz Elliott).

        Replaced the invalid "<nobr>" tag -- created for "S<>" -- with
        '<span style="white-space: nowrap;">' (Fitz Elliott).

        Fixed some nerbles in our own Pod (Michael Stevens)

        Improved the "Minimal code" example in Pod::Simple::HTML. The key
        is to use pase_file(), not parse_from_file() (which should
        otherwise be undocumented, and is just there for Pod::Parser
        compatibility. Thanks to prodding from Ævar Arnfjörð Bjarmason (RT
        #65428).

        Added the html_charset() and html_encode_chars() attributes to
        Pod::Simple::XHTML. Inspired by a bug report from Agent Zhang
        (章亦春) (RT #29587).

        Added "Minimal code" example to the Pod::Simple::XHTML documentation.

        Fixed mispelling of the "=encoding" markup in the parser (it was
        spelled "=encode"). Thanks to "TTY" for the patch. (RT #24820).

37 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/corpus/fet_dup.txt
cpan/Pod-Simple/t/output.t [new file with mode: 0644]
cpan/Pod-Simple/t/strpvbtm.t
cpan/Pod-Simple/t/xhtml01.t
pod/perldelta.pod

index e7aa42f..2e62c32 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -2012,6 +2012,7 @@ cpan/Pod-Simple/t/junk1.pod                               Pod::Simple test file
 cpan/Pod-Simple/t/junk2o.txt                           Pod::Simple test file
 cpan/Pod-Simple/t/junk2.pod                            Pod::Simple test file
 cpan/Pod-Simple/t/linkclas.t                           Pod::Simple test file
+cpan/Pod-Simple/t/output.t                             Pod::Simple test file
 cpan/Pod-Simple/t/perlcygo.txt                         Pod::Simple test file
 cpan/Pod-Simple/t/perlcyg.pod                          Pod::Simple test file
 cpan/Pod-Simple/t/perlfaqo.txt                         Pod::Simple test file
index 52b097e..eea805d 100755 (executable)
@@ -1297,7 +1297,7 @@ use File::Glob qw(:case);
     'Pod::Simple' =>
        {
        'MAINTAINER'    => 'arandal',
-       'DISTRIBUTION'  => 'DWHEELER/Pod-Simple-3.15.tar.gz',
+       'DISTRIBUTION'  => 'DWHEELER/Pod-Simple-3.16.tar.gz',
        'FILES'         => q[cpan/Pod-Simple],
        # XXX these two files correspond to similar ones in blead under
        # pod/, but the blead ones have newer changes, and also seem to
index 2c55d55..721513a 100644 (file)
@@ -1,8 +1,34 @@
 # ChangeLog for Pod::Simple dist
 #---------------------------------------------------------------------------
 
+2011-03-14   David E. Wheeler <david@justatheory.org>
+       * Release 3.16
+
+       Fixed invalid HTML generated for nested lists by Pod::Simple::XHTML
+       (Fitz Elliott).
+
+       Replaced the invalid "<nobr>" tag -- created for "S<>" -- with
+       '<span style="white-space: nowrap;">' (Fitz Elliott).
+
+       Fixed some nerbles in our own Pod (Michael Stevens)
+
+       Improved the "Minimal code" example in Pod::Simple::HTML. The key
+       is to use pase_file(), not parse_from_file() (which should
+       otherwise be undocumented, and is just there for Pod::Parser
+       compatibility. Thanks to prodding from Ævar Arnfjörð Bjarmason (RT
+       #65428).
+
+       Added the html_charset() and html_encode_chars() attributes to
+       Pod::Simple::XHTML. Inspired by a bug report from Agent Zhang
+       (章亦春) (RT #29587).
+
+       Added "Minimal code" example to the Pod::Simple::XHTML documentation.
+
+       Fixed mispelling of the "=encoding" markup in the parser (it was
+       spelled "=encode"). Thanks to "TTY" for the patch. (RT #24820).
+
 2010-11-11   David E. Wheeler <david@justatheory.org>
-       * Release 3.15
+       * Release 3.16
 
        Removed "perlpod.pod" and "perlpodspec.pod". These now just live
        in the Perl core.
        Fixed the output of entities in L<> tags by Pod::Simple::XHTML.
 
        Fixed the output of POD links from Pod::Simple::XHTML so that the
-       section part (/foo) is turned into a proper fragment identfier (#foo)
+       section part (/foo) is turned into a proper fragment identifier (#foo)
        in the resulting search.cpan.org link.
 
        Pod::Simple::Text now outputs URLs for links created in the
index 2562fd9..7f86422 100644 (file)
@@ -1,4 +1,4 @@
-=head1 Pod::Simple version 3.15
+=head1 Pod::Simple version 3.16
 
 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
 documentation") markup language that is typically used for writing
index bd03190..909a2ec 100644 (file)
@@ -18,7 +18,7 @@ use vars qw(
 );
 
 @ISA = ('Pod::Simple::BlackBox');
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 @Known_formatting_codes = qw(I B C L E F S X Z); 
 %Known_formatting_codes = map(($_=>1), @Known_formatting_codes);
@@ -474,7 +474,7 @@ sub whine {
   return $self->_complain_errata(@_);
 }
 
-sub scream {    # like whine, but not suppressable
+sub scream {    # like whine, but not suppressible
   #my($self,$line,$complaint) = @_;
   my $self = shift(@_);
   ++$self->{'errors_seen'};
index 8ea9ee9..4765744 100644 (file)
@@ -23,7 +23,7 @@ use integer; # vroom!
 use strict;
 use Carp ();
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 #use constant DEBUG => 7;
 BEGIN {
   require Pod::Simple;
@@ -88,8 +88,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 ) {
@@ -519,7 +519,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;
@@ -1911,7 +1911,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 {
index 3bfd67f..6aca389 100644 (file)
@@ -9,7 +9,7 @@ use Carp ();
 use Pod::Simple::Methody ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG
index a620204..b3de557 100644 (file)
@@ -3,7 +3,7 @@ require 5;
 package Pod::Simple::Debug;
 use strict;
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 sub import {
   my($value,$variable);
index 327b9a8..5609c71 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsText;
-$VERSION = '3.15';
+$VERSION = '3.16';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
index 84f5c8b..beef7ca 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsXML;
-$VERSION = '3.15';
+$VERSION = '3.16';
 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.
 
index 21bf7c2..9d7d069 100644 (file)
@@ -10,7 +10,7 @@ use vars qw(
   $Doctype_decl  $Content_decl
 );
 @ISA = ('Pod::Simple::PullParser');
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 BEGIN {
   if(defined &DEBUG) { } # no-op
@@ -902,10 +902,10 @@ TODO
 =head2 Minimal code
 
   use Pod::Simple::HTML;
-  my $html;
-  $p->output_string(\$html);
-  $p->parse_from_file('path/to/Module/Name.pm');
-  open my $out, '>', 'out.html' or die;
+  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
@@ -946,7 +946,7 @@ Tell the parser where should the output go. In this case it will be placed in th
 
 Parse and process a file with pod in it:
 
-  $p->parse_from_file('path/to/Module/Name.pm');
+  $p->parse_file('path/to/Module/Name.pm');
 
 =head1 METHODS
 
@@ -1005,7 +1005,7 @@ to be added at the top of the generated HTML.
 
 =head2 html_header_after_title
 
-Includes the closing tag of </title> and throught the rest of the head
+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">');
@@ -1064,7 +1064,7 @@ Meanwhile in script.pl:
 
   my $html;
   $p->output_string(\$html);
-  $p->parse_from_file('path/to/Module/Name.pm');
+  $p->parse_file('path/to/Module/Name.pm');
   open my $out, '>', 'out.html' or die;
   print $out $html;
 
@@ -1105,7 +1105,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
index 52b8a80..7686cd4 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.15';
+$VERSION = '3.16';
 @ISA = ();  # Yup, we're NOT a subclass of Pod::Simple::HTML!
 
 # TODO: nocontents stylesheets. Strike some of the color variations?
@@ -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'>
index 185b2b6..7d77ebb 100644 (file)
@@ -3,12 +3,12 @@ require 5;
 package Pod::Simple::LinkSection;
   # Based somewhat dimly on Array::Autojoin
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 use strict;
 use Pod::Simple::BlackBox;
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 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
index 2c28602..0d69b7a 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::Methody;
 use strict;
 use Pod::Simple ();
 use vars qw(@ISA $VERSION);
-$VERSION = '3.15';
+$VERSION = '3.16';
 @ISA = ('Pod::Simple');
 
 # Yes, we could use named variables, but I want this to be impose
@@ -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
index 03bff67..622909b 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::Progress;
-$VERSION = '3.15';
+$VERSION = '3.16';
 use strict;
 
 # Objects of this class are used for noting progress of an
index 9c8378e..4033213 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::PullParser;
-$VERSION = '3.15';
+$VERSION = '3.16';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
@@ -453,7 +453,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 +532,7 @@ And elsewhere:
  package SomePodProcessor;
  use strict;
  use base qw(Pod::Simple::PullParser);
+
  sub run {
    my $self = shift;
   Token:
@@ -623,14 +623,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 +648,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 +657,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 +769,7 @@ Pod::Simple is maintained by:
 =back
 
 =cut
+
 JUNK:
 
 sub _old_get_title {  # some witchery in here
@@ -833,7 +834,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" }
   }
   
index 21ae23f..8b12e64 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 sub new {  # Class->new(tagname);
   my $class = shift;
index d346e39..232ef23 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 sub new {  # Class->new(tagname, optional_attrhash);
   my $class = shift;
index ad72a89..a7fcb0f 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 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...
   }
 
index 861a1d2..ad6ebf3 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.15';
+$VERSION = '3.16';
 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...
-    
+
     }
   }
 
index 71ba107..7dbc643 100644 (file)
@@ -8,7 +8,7 @@ package Pod::Simple::RTF;
 
 use strict;
 use vars qw($VERSION @ISA %Escape $WRAP %Tagmap);
-$VERSION = '3.15';
+$VERSION = '3.16';
 use Pod::Simple::PullParser ();
 BEGIN {@ISA = ('Pod::Simple::PullParser')}
 
index bb9371a..b7d209b 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::Search;
 use strict;
 
 use vars qw($VERSION $MAX_VERSION_WITHIN $SLEEPY);
-$VERSION = '3.15';   ## Current version of this package
+$VERSION = '3.16';   ## Current version of this package
 
 BEGIN { *DEBUG = sub () {0} unless defined &DEBUG; }   # set DEBUG level
 use Carp ();
index 92cf7b9..fc8b7a2 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '3.15';
+$VERSION = '3.16';
 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 },
index 426fa89..f536318 100644 (file)
@@ -275,7 +275,7 @@ some link text.)
 For example, this Pod source:
 
   L<hell itself!|crontab(5)>
-  
+
 will produce this event structure:
 
   <L to="crontab(5)" type="man">
@@ -425,7 +425,7 @@ 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">
@@ -509,15 +509,15 @@ The I<indent> attribute is 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:
@@ -559,18 +559,18 @@ The I<indent> attribute is 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
-  
+
 will produce this event structure:
 
   <over-block indent="4" start_line="2">
@@ -615,7 +615,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>.
 
@@ -793,7 +793,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 +806,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.
 
index 6f05f89..55dae9a 100644 (file)
@@ -6,7 +6,7 @@ use Carp ();
 use Pod::Simple::Methody ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION $FREAKYMODE);
-$VERSION = '3.15';
+$VERSION = '3.16';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG
index 5220698..36a4988 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 @ISA = ('Pod::Simple');
 
 sub new {
index 13c7ec7..e6e5a4a 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::TiedOutFH;
 use Symbol ('gensym');
 use Carp ();
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
index 9ee4796..dec3b96 100644 (file)
@@ -2,7 +2,7 @@
 require 5;
 package Pod::Simple::Transcode;
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 BEGIN {
   if(defined &DEBUG) {;} # Okay
index 95b5fc8..6474475 100644 (file)
@@ -5,7 +5,7 @@ require 5;
 package Pod::Simple::TranscodeDumb;
 use strict;
 use vars qw($VERSION %Supported);
-$VERSION = '3.15';
+$VERSION = '3.16';
 # This module basically pretends it knows how to transcode, except
 #  only for null-transcodings!  We use this when Encode isn't
 #  available.
index 8979bd2..5c10f02 100644 (file)
@@ -9,7 +9,7 @@ use strict;
 use Pod::Simple;
 require Encode;
 use vars qw($VERSION );
-$VERSION = '3.15';
+$VERSION = '3.16';
 
 sub is_dumb  {0}
 sub is_smart {1}
index e160b30..ef05ddb 100644 (file)
@@ -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.15';
-use Carp ();
+$VERSION = '3.16';
 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
@@ -168,7 +206,8 @@ __PACKAGE__->_accessorize(
  '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',
@@ -198,7 +237,7 @@ 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'} = '';
@@ -206,6 +245,7 @@ sub new {
   $new->{'output'} = [];
   $new->{'saved'} = [];
   $new->{'ids'} = {};
+  $new->{'in_li'} = [];
 
   $new->{'__region_targets'}  = [];
   $new->{'__literal_targets'} = {};
@@ -214,6 +254,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
@@ -270,7 +318,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,15 +330,15 @@ 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   {
@@ -301,9 +349,9 @@ sub start_item_text   {
     $_[0]{'scratch'} .= '<dt>';
 }
 
-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 +362,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;
 }
 
@@ -500,7 +550,7 @@ sub end_I   { $_[0]{'scratch'} .= '</i>' }
 sub start_L {
   my ($self, $flags) = @_;
     my ($type, $to, $section) = @{$flags}{'type', 'to', 'section'};
-    my $url = encode_entities(
+    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)
@@ -513,8 +563,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) = @_;
@@ -556,7 +606,7 @@ sub resolve_pod_page_link {
     }
 
     return ($self->perldoc_url_prefix || '')
-        . encode_entities($to) . $section
+        . $self->encode_entities($to) . $section
         . ($self->perldoc_url_postfix || '');
 }
 
@@ -585,7 +635,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 || '');
 
 }
@@ -692,7 +742,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
index 0cd1a70..69b992d 100644 (file)
@@ -5,7 +5,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '3.15';
+$VERSION = '3.16';
 BEGIN {
   @ISA = ('Pod::Simple');
   *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG;
index 616168a..e8552e7 100644 (file)
@@ -1,5 +1,5 @@
 
-We have deliberately reduntant =encoding statements here.
+We have deliberately redundant =encoding statements here.
 This should generate no errata.
 
 =encoding koi8-r
diff --git a/cpan/Pod-Simple/t/output.t b/cpan/Pod-Simple/t/output.t
new file mode 100644 (file)
index 0000000..822c239
--- /dev/null
@@ -0,0 +1,36 @@
+#!/usr/bin/perl -w
+
+# t/output.t - Check output_string.
+
+BEGIN {
+    chdir 't' if -d 't';
+}
+
+use strict;
+use lib '../lib';
+use Test::More tests => 36;
+#use Test::More 'no_plan';
+use File::Spec;
+
+for my $format (qw(XHTML HTML Text RTF)) {
+    my $class = "Pod::Simple::$format";
+    use_ok $class or next;
+    ok my $parser = $class->new, "Construct $format parser";
+
+    # Try parse_string_document().
+    my $output = '';
+    ok $parser->output_string(\$output), "Set $format output string";
+    ok $parser->parse_string_document( "=head1 Poit!" ),
+        "Parse to $format via parse_string_document()";
+    like $output, qr{Poit!},
+        "Should have $format output from parse_string_document()";
+
+    # Try parse_file().
+    ok $parser = $class->new, "Construct another $format parser";
+    $output = '';
+    ok $parser->output_string(\$output), "Set $format output string again";
+    ok $parser->parse_file(File::Spec->catfile(qw(testlib1 zikzik.pod))),
+        "Parse to $format via parse_file()";
+    like $output, qr{This is just a test file},
+        "Should have $format output from parse_file";
+}
index 9cb83f3..ef85c5a 100644 (file)
@@ -1,6 +1,6 @@
 #!/usr/bin/perl -w
 
-# t/strip_verbatim_indent.t.t - check verabtim indent stripping feature
+# t/strip_verbatim_indent.t.t - check verbatim indent stripping feature
 
 BEGIN {
     chdir 't' if -d 't';
index 1b43220..d8f2417 100644 (file)
@@ -8,8 +8,8 @@ BEGIN {
 
 use strict;
 use lib '../lib';
-use Test::More tests => 50;
-#use Test::More 'no_plan';
+#use Test::More tests => 56;
+use Test::More 'no_plan';
 
 use_ok('Pod::Simple::XHTML') or exit;
 
@@ -125,6 +125,59 @@ initialize($parser, $results);
 $parser->parse_string_document(<<'EOPOD');
 =over
 
+=item *
+
+P: Gee, Brain, what do you want to do tonight?
+
+=item *
+
+B: The same thing we do every night, Pinky. Try to take over the world!
+
+=over
+
+=item *
+
+Take over world
+
+=item *
+
+Do laundry
+
+=back
+
+=back
+
+EOPOD
+
+is($results, <<'EOHTML', "nested bulleted list");
+<ul>
+
+<li><p>P: Gee, Brain, what do you want to do tonight?</p>
+
+</li>
+<li><p>B: The same thing we do every night, Pinky. Try to take over the world!</p>
+
+<ul>
+
+<li><p>Take over world</p>
+
+</li>
+<li><p>Do laundry</p>
+
+</li>
+</ul>
+
+</li>
+</ul>
+
+EOHTML
+
+
+
+initialize($parser, $results);
+$parser->parse_string_document(<<'EOPOD');
+=over
+
 =item 1
 
 P: Gee, Brain, what do you want to do tonight?
@@ -155,6 +208,58 @@ initialize($parser, $results);
 $parser->parse_string_document(<<'EOPOD');
 =over
 
+=item 1
+
+P: Gee, Brain, what do you want to do tonight?
+
+=item 2
+
+B: The same thing we do every night, Pinky. Try to take over the world!
+
+=over
+
+=item 1
+
+Take over world
+
+=item 2
+
+Do laundry
+
+=back
+
+=back
+
+EOPOD
+
+is($results, <<'EOHTML', "nested numbered list");
+<ol>
+
+<li><p>P: Gee, Brain, what do you want to do tonight?</p>
+
+</li>
+<li><p>B: The same thing we do every night, Pinky. Try to take over the world!</p>
+
+<ol>
+
+<li><p>Take over world</p>
+
+</li>
+<li><p>Do laundry</p>
+
+</li>
+</ol>
+
+</li>
+</ol>
+
+EOHTML
+
+
+initialize($parser, $results);
+$parser->parse_string_document(<<'EOPOD');
+=over
+
 =item Pinky
 
 Gee, Brain, what do you want to do tonight?
@@ -416,7 +521,7 @@ $parser->parse_string_document(<<'EOPOD');
 A plain paragraph with S<non breaking text>.
 EOPOD
 is($results, <<"EOHTML", "Non breaking text in a paragraph");
-<p>A plain paragraph with <nobr>non breaking text</nobr>.</p>
+<p>A plain paragraph with <span style="white-space: nowrap;">non breaking text</span>.</p>
 
 EOHTML
 
@@ -565,6 +670,24 @@ is($results, <<"EOHTML", "Verbatim text with markup and embedded formatting");
   my \$text = &quot;File is: &quot; . &lt;FILE&gt;;</code></pre>
 
 EOHTML
+
+  # Specify characters to encode.
+  initialize($parser, $results);
+  $parser->html_encode_chars('><"&T');
+  $parser->parse_string_document(<<'EOPOD');
+=pod
+
+This is Anna's "Answer" to the <q>Question</q>.
+
+=cut
+
+EOPOD
+my $T = $use_html_entities ? 84 : 'x54';
+is($results, <<"EOHTML", 'HTML Entities should be only for specified characters');
+<p>&#$T;his is Anna's &quot;Answer&quot; to the &lt;q&gt;Question&lt;/q&gt;.</p>
+
+EOHTML
+
 }
 
 
@@ -572,9 +695,17 @@ ok $parser = Pod::Simple::XHTML->new, 'Construct a new parser';
 $results = '';
 $parser->output_string( \$results ); # Send the resulting output to a string
 ok $parser->parse_string_document( "=head1 Poit!" ), 'Parse with headers';
-like $results, qr{<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />},
+like $results, qr{\Q<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />},
     'Should have proper http-equiv meta tag';
 
+ok $parser = Pod::Simple::XHTML->new, 'Construct a new parser again';
+ok $parser->html_charset('UTF-8'), 'Set the html charset to UTF-8';
+$results = '';
+$parser->output_string( \$results ); # Send the resulting output to a string
+ok $parser->parse_string_document( "=head1 Poit!" ), 'Parse with headers';
+like $results, qr{\Q<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />},
+    'Should have http-equiv meta tag with UTF-8';
+
 # Test the link generation methods.
 is $parser->resolve_pod_page_link('Net::Ping', 'INSTALL'),
     "$PERLDOC?Net::Ping#INSTALL",
index a85af80..8019dd3 100644 (file)
@@ -203,6 +203,10 @@ C<parent> has been upgraded from version 0.224 to 0.225
 
 =item *
 
+C<Pod::Simple> has been upgraded from version 3.15 to 3.16
+
+=item *
+
 C<Storable> has been upgraded from version 2.26 to 2.27.
 
 =item *