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.17
authorChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Sun, 10 Jul 2011 09:13:39 +0000 (10:13 +0100)
committerChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Sun, 10 Jul 2011 09:13:39 +0000 (10:13 +0100)
  [DELTA]

  2011-07-09   David E. Wheeler <david@justatheory.org>
  * Release 3.17

  Documented tertiary methods. Patch from Shawn H Corey.

  Added "backlink" option to Pod::Simple::XHTML. Thanks to Marc
  Green/Google Summer of Code for the pull request.

  Typos fixed in Pod::Simple::HTMLBatch. Reported by Shawn H Corey.

  Fixed quoting of value returned by a "strip_verbatim_indent()"
  code reference so that regex meta characters are properly escaped.

  Added "anchor_items" option to Pod::Simple::XHMTL. This allows
  text items (which are output as <dt> elements) to have IDs that
  can be referenced in the "#" part of a URL. Marc Green/Google
  Summer of Code.

  Added "recurse" option to Pod::Simple::Search. It's enabled by
  default; disable it to turn off recursion into subdirectories.
  Marc Green/Google Summer of Code.

  Added documentation to clarify the behavior of the "content_seen"
  method. Thanks to Olaf Alders for the pull request.

39 files changed:
Porting/Maintainers.pl
cpan/Pod-Simple/ChangeLog
cpan/Pod-Simple/README
cpan/Pod-Simple/lib/Pod/Simple.pm
cpan/Pod-Simple/lib/Pod/Simple.pod
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/search05.t
cpan/Pod-Simple/t/search10.t
cpan/Pod-Simple/t/search12.t
cpan/Pod-Simple/t/search20.t
cpan/Pod-Simple/t/strpvbtm.t
cpan/Pod-Simple/t/xhtml10.t
pod/perldelta.pod

index a8228c2..10e6ad9 100755 (executable)
@@ -1560,14 +1560,8 @@ use File::Glob qw(:case);
     'Pod::Simple' =>
        {
        'MAINTAINER'    => 'arandal',
-       'DISTRIBUTION'  => 'DWHEELER/Pod-Simple-3.16.tar.gz',
+       'DISTRIBUTION'  => 'DWHEELER/Pod-Simple-3.17.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
-       # have been in blead a long time. I'm going to assume then that
-       # the blead versions of these two files are authoritative - DAPM
-  # Now been removed from Pod-Simple-3.15 commenting this out - bingos
-       #'EXCLUDED'     => [ qw( lib/perlpod.pod lib/perlpodspec.pod ) ],
        'UPSTREAM'      => 'cpan',
        },
 
index 721513a..d47f926 100644 (file)
@@ -1,6 +1,31 @@
 # ChangeLog for Pod::Simple dist
 #---------------------------------------------------------------------------
 
+2011-07-09   David E. Wheeler <david@justatheory.org>
+       * Release 3.17
+
+       Documented tertiary methods. Patch from Shawn H Corey.
+
+       Added "backlink" option to Pod::Simple::XHTML. Thanks to Marc
+       Green/Google Summer of Code for the pull request.
+
+       Typos fixed in Pod::Simple::HTMLBatch. Reported by Shawn H Corey.
+
+       Fixed quoting of value returned by a "strip_verbatim_indent()"
+       code reference so that regex meta characters are properly escaped.
+
+       Added "anchor_items" option to Pod::Simple::XHMTL. This allows
+       text items (which are output as <dt> elements) to have IDs that
+       can be referenced in the "#" part of a URL. Marc Green/Google
+       Summer of Code.
+
+       Added "recurse" option to Pod::Simple::Search. It's enabled by
+       default; disable it to turn off recursion into subdirectories.
+       Marc Green/Google Summer of Code.
+
+       Added documentation to clarify the behavior of the "content_seen"
+       method. Thanks to Olaf Alders for the pull request.
+
 2011-03-14   David E. Wheeler <david@justatheory.org>
        * Release 3.16
 
@@ -28,7 +53,7 @@
        spelled "=encode"). Thanks to "TTY" for the patch. (RT #24820).
 
 2010-11-11   David E. Wheeler <david@justatheory.org>
-       * Release 3.16
+       * Release 3.17
 
        Removed "perlpod.pod" and "perlpodspec.pod". These now just live
        in the Perl core.
index 7f86422..f213dc2 100644 (file)
@@ -1,4 +1,4 @@
-=head1 Pod::Simple version 3.16
+=head1 Pod::Simple version 3.17
 
 Pod::Simple is a Perl library for parsing text in the Pod ("plain old
 documentation") markup language that is typically used for writing
index 909a2ec..8ba9af8 100644 (file)
@@ -18,7 +18,7 @@ use vars qw(
 );
 
 @ISA = ('Pod::Simple::BlackBox');
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 @Known_formatting_codes = qw(I B C L E F S X Z); 
 %Known_formatting_codes = map(($_=>1), @Known_formatting_codes);
index d3f168d..a8ad211 100644 (file)
@@ -85,9 +85,9 @@ the last call) ends with an C<undef> value.
 
 =item C<< $parser->content_seen >>
 
-This returns true only if there has been any real content seen
-for this document.
-
+This returns true only if there has been any real content seen for this
+document. Returns false in cases where the document contains content,
+but does not make use of any Pod markup.
 
 =item C<< I<SomeClass>->filter( I<$filename> ); >>
 
@@ -211,6 +211,117 @@ that you don't want I<any> lines indented. You can do something like this:
 
 =back
 
+=head1 TERTIARY METHODS
+
+=over
+
+=item C<< $parser->abandon_output_fh() >>X<abandon_output_fh>
+
+Cancel output to the file handle. Any POD read by the C<$parser> is not
+effected.
+
+=item C<< $parser->abandon_output_string() >>X<abandon_output_string>
+
+Cancel output to the output string. Any POD read by the C<$parser> is not
+effected.
+
+=item C<< $parser->accept_code( @codes ) >>X<accept_code>
+
+Alias for L<< accept_codes >>.
+
+=item C<< $parser->accept_codes( @codes ) >>X<accept_codes>
+
+Allows C<$parser> to accept a list of L<perlpod/Formatting Codes>. This can be
+used to implement user-defined codes.
+
+=item C<< $parser->accept_directive_as_data( @directives ) >>X<accept_directive_as_data>
+
+Allows C<$parser> to accept a list of directives for data paragraphs. A
+directive is the label of a L<perlpod/Command Paragraph>. A data paragraph is
+one delimited by C<< =begin/=for/=end >> directives. This can be used to
+implement user-defined directives.
+
+=item C<< $parser->accept_directive_as_processed( @directives ) >>X<accept_directive_as_processed>
+
+Allows C<$parser> to accept a list of directives for processed paragraphs. A
+directive is the label of a L<perlpod/Command Paragraph>. A processed
+paragraph is also known as L<perlpod/Ordinary Paragraph>. This can be used to
+implement user-defined directives.
+
+=item C<< $parser->accept_directive_as_verbatim( @directives ) >>X<accept_directive_as_verbatim>
+
+Allows C<$parser> to accept a list of directives for L<perlpod/Verbatim
+Paragraph>. A directive is the label of a L<perlpod/Command Paragraph>. This
+can be used to implement user-defined directives.
+
+=item C<< $parser->accept_target( @targets ) >>X<accept_target>
+
+Alias for L<< accept_targets >>.
+
+=item C<< $parser->accept_target_as_text( @targets ) >>X<accept_target_as_text>
+
+Alias for L<< accept_targets_as_text >>.
+
+=item C<< $parser->accept_targets( @targets ) >>X<accept_targets>
+
+Accepts targets for C<< =begin/=for/=end >> sections of the POD.
+
+=item C<< $parser->accept_targets_as_text( @targets ) >>X<accept_targets_as_text>
+
+Accepts targets for C<< =begin/=for/=end >> sections that should be parsed as
+POD. For details, see L<< perlpodspec/About Data Paragraphs >>.
+
+=item C<< $parser->any_errata_seen() >>X<any_errata_seen>
+
+Used to check if any errata was seen.
+
+I<Example:>
+
+  die "too many errors\n" if $parser->any_errata_seen();
+
+=item C<< $parser->parse_from_file( $source, $to ) >>X<parse_from_file>
+
+Parses from C<$source> file to C<$to> file. Similar to L<<
+Pod::Parser/parse_from_file >>.
+
+=item C<< $parser->scream( @error_messages ) >>X<scream>
+
+Log an error that can't be ignored.
+
+=item C<< $parser->unaccept_code( @codes ) >>X<unaccept_code>
+
+Alias for L<< unaccept_codes >>.
+
+=item C<< $parser->unaccept_codes( @codes ) >>X<unaccept_codes>
+
+Removes C<< @codes >> as valid codes for the parse.
+
+=item C<< $parser->unaccept_directive( @directives ) >>X<unaccept_directive>
+
+Alias for L<< unaccept_directives >>.
+
+=item C<< $parser->unaccept_directives( @directives ) >>X<unaccept_directives>
+
+Removes C<< @directives >> as valid directives for the parse.
+
+=item C<< $parser->unaccept_target( @targets ) >>X<unaccept_target>
+
+Alias for L<< unaccept_targets >>.
+
+=item C<< $parser->unaccept_targets( @targets ) >>X<unaccept_targets>
+
+Removes C<< @targets >> as valid targets for the parse.
+
+=item C<< $parser->version_report() >>X<version_report>
+
+Returns a string describing the version.
+
+=item C<< $parser->whine( @error_messages ) >>X<whine>
+
+Log an error unless C<< $parser->no_whining( TRUE ); >>.
+
+=back
+
 =head1 CAVEATS
 
 This is just a beta release -- there are a good number of things still
@@ -271,4 +382,14 @@ Pod::Simple is maintained by:
 
 =back
 
+Documentation has been contributed by:
+
+=over
+
+=item * Gabor Szabo C<szabgab@gmail.com>
+
+=item * Shawn H Corey  C<SHCOREY at cpan.org>
+
+=back
+
 =cut
index 4765744..629563b 100644 (file)
@@ -23,7 +23,7 @@ use integer; # vroom!
 use strict;
 use Carp ();
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 #use constant DEBUG => 7;
 BEGIN {
   require Pod::Simple;
@@ -1383,7 +1383,7 @@ sub _ponder_Verbatim {
   for(my $i = 2; $i < @$para; $i++) {
     foreach my $line ($para->[$i]) { # just for aliasing
       # Strip indentation.
-      $line =~ s/^\E$indent// if $indent
+      $line =~ s/^\Q$indent// if $indent
           && !($self->{accept_codes} && $self->{accept_codes}{VerbatimFormatted});
       while( $line =~
         # Sort of adapted from Text::Tabs -- yes, it's hardwired in that
index 6aca389..e5ff0f7 100644 (file)
@@ -9,7 +9,7 @@ use Carp ();
 use Pod::Simple::Methody ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG
index b3de557..1aa2da8 100644 (file)
@@ -3,7 +3,7 @@ require 5;
 package Pod::Simple::Debug;
 use strict;
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 sub import {
   my($value,$variable);
index 5609c71..f2177b2 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsText;
-$VERSION = '3.16';
+$VERSION = '3.17';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
index beef7ca..40b94c0 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::DumpAsXML;
-$VERSION = '3.16';
+$VERSION = '3.17';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
index 9d7d069..54e87b2 100644 (file)
@@ -10,7 +10,7 @@ use vars qw(
   $Doctype_decl  $Content_decl
 );
 @ISA = ('Pod::Simple::PullParser');
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 BEGIN {
   if(defined &DEBUG) { } # no-op
index 7686cd4..cfa2e4b 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.16';
+$VERSION = '3.17';
 @ISA = ();  # Yup, we're NOT a subclass of Pod::Simple::HTML!
 
 # TODO: nocontents stylesheets. Strike some of the color variations?
@@ -1082,7 +1082,7 @@ Example:
   % mkdir out_html
   % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go @INC out_html
       (to convert the pod from Perl's @INC
-       files under the directory ../htmlversion)
+       files under the directory ./out_html)
 
 (Note that the command line there contains a literal atsign-I-N-C.  This
 is handled as a special case by batch_convert, in order to save you having
@@ -1095,7 +1095,7 @@ Example:
   % chmod og-rx ../seekrut
   % perl -MPod::Simple::HTMLBatch -e Pod::Simple::HTMLBatch::go . ../htmlversion
       (to convert the pod under the current dir into HTML
-       files under the directory ../htmlversion)
+       files under the directory ./seekrut)
 
 Example:
 
index 7d77ebb..70dbb07 100644 (file)
@@ -3,12 +3,12 @@ require 5;
 package Pod::Simple::LinkSection;
   # Based somewhat dimly on Array::Autojoin
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 use strict;
 use Pod::Simple::BlackBox;
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 use overload( # So it'll stringify nice
   '""'   => \&Pod::Simple::BlackBox::stringify_lol,
index 0d69b7a..3df5227 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::Methody;
 use strict;
 use Pod::Simple ();
 use vars qw(@ISA $VERSION);
-$VERSION = '3.16';
+$VERSION = '3.17';
 @ISA = ('Pod::Simple');
 
 # Yes, we could use named variables, but I want this to be impose
index 622909b..1d54999 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::Progress;
-$VERSION = '3.16';
+$VERSION = '3.17';
 use strict;
 
 # Objects of this class are used for noting progress of an
index 4033213..cf45e8a 100644 (file)
@@ -1,7 +1,7 @@
 
 require 5;
 package Pod::Simple::PullParser;
-$VERSION = '3.16';
+$VERSION = '3.17';
 use Pod::Simple ();
 BEGIN {@ISA = ('Pod::Simple')}
 
index 8b12e64..1adcf2e 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 sub new {  # Class->new(tagname);
   my $class = shift;
index 232ef23..8906ae7 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 sub new {  # Class->new(tagname, optional_attrhash);
   my $class = shift;
index a7fcb0f..0f6155f 100644 (file)
@@ -5,7 +5,7 @@ use Pod::Simple::PullParserToken ();
 use strict;
 use vars qw(@ISA $VERSION);
 @ISA = ('Pod::Simple::PullParserToken');
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 sub new {  # Class->new(text);
   my $class = shift;
index ad6ebf3..a90538f 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.16';
+$VERSION = '3.17';
 use strict;
 
 sub new {  # Class->new('type', stuff...);  ## Overridden in derived classes anyway
index 7dbc643..7718b9e 100644 (file)
@@ -8,7 +8,7 @@ package Pod::Simple::RTF;
 
 use strict;
 use vars qw($VERSION @ISA %Escape $WRAP %Tagmap);
-$VERSION = '3.16';
+$VERSION = '3.17';
 use Pod::Simple::PullParser ();
 BEGIN {@ISA = ('Pod::Simple::PullParser')}
 
index b7d209b..fca12fe 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::Search;
 use strict;
 
 use vars qw($VERSION $MAX_VERSION_WITHIN $SLEEPY);
-$VERSION = '3.16';   ## Current version of this package
+$VERSION = '3.17';   ## Current version of this package
 
 BEGIN { *DEBUG = sub () {0} unless defined &DEBUG; }   # set DEBUG level
 use Carp ();
@@ -25,7 +25,7 @@ use Cwd qw( cwd );
 #==========================================================================
 __PACKAGE__->_accessorize(  # Make my dumb accessor methods
  'callback', 'progress', 'dir_prefix', 'inc', 'laborious', 'limit_glob',
- 'limit_re', 'shadows', 'verbose', 'name2path', 'path2name', 
+ 'limit_re', 'shadows', 'verbose', 'name2path', 'path2name', 'recurse',
 );
 #==========================================================================
 
@@ -39,6 +39,7 @@ sub new {
 sub init {
   my $self = shift;
   $self->inc(1);
+  $self->recurse(1);
   $self->verbose(DEBUG);
   return $self;
 }
@@ -127,9 +128,11 @@ sub _make_search_callback {
   my $self = $_[0];
 
   # Put the options in variables, for easy access
-  my(  $laborious, $verbose, $shadows, $limit_re, $callback, $progress,$path2name,$name2path) =
+  my( $laborious, $verbose, $shadows, $limit_re, $callback, $progress,
+      $path2name, $name2path, $recurse) =
     map scalar($self->$_()),
-     qw(laborious   verbose   shadows   limit_re   callback   progress  path2name  name2path);
+     qw(laborious verbose shadows limit_re callback progress
+        path2name name2path recurse);
 
   my($file, $shortname, $isdir, $modname_bits);
   return sub {
@@ -137,6 +140,11 @@ sub _make_search_callback {
 
     if($isdir) { # this never gets called on the startdir itself, just subdirs
 
+      unless( $recurse ) {
+        $verbose and print "Not recursing into '$file' as per requested.\n";
+        return 'PRUNE';
+      }
+
       if( $self->{'_dirs_visited'}{$file} ) {
         $verbose and print "Directory '$file' already seen, skipping.\n";
         return 'PRUNE';
index fc8b7a2..8099895 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '3.16';
+$VERSION = '3.17';
 BEGIN {
   @ISA = ('Pod::Simple');
   *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG;
index f536318..793c790 100644 (file)
@@ -290,7 +290,7 @@ specified for this type of L code.
 In the most common case, the simple case of a LE<lt>podpageE<gt> code
 produces this event structure:
 
-  <L content-implicit="yes" to="Net::Ping" type="pod">
+  <L content-implicit="yes" to="podpage" type="pod">
     podpage
   </L>
 
@@ -673,7 +673,7 @@ B<TODO: document how this interacts with =extend, and long element names>
 
 In the unlikely situation that you need to tell the parser that you will
 accept additional directives ("=foo" things), you need to first set the
-parset to treat its content as data (i.e., not really processed at
+parser to treat its content as data (i.e., not really processed at
 all), or as verbatim (mostly just expanding tabs), or as processed text
 (parsing formatting codes like BE<lt>...E<gt>).
 
index 55dae9a..1ed814c 100644 (file)
@@ -6,7 +6,7 @@ use Carp ();
 use Pod::Simple::Methody ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION $FREAKYMODE);
-$VERSION = '3.16';
+$VERSION = '3.17';
 @ISA = ('Pod::Simple::Methody');
 BEGIN { *DEBUG = defined(&Pod::Simple::DEBUG)
           ? \&Pod::Simple::DEBUG
index 36a4988..d78373e 100644 (file)
@@ -6,7 +6,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( @ISA $VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 @ISA = ('Pod::Simple');
 
 sub new {
index e6e5a4a..2c2af0b 100644 (file)
@@ -4,7 +4,7 @@ package Pod::Simple::TiedOutFH;
 use Symbol ('gensym');
 use Carp ();
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 #~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
index dec3b96..266bade 100644 (file)
@@ -2,7 +2,7 @@
 require 5;
 package Pod::Simple::Transcode;
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 BEGIN {
   if(defined &DEBUG) {;} # Okay
index 6474475..4592c32 100644 (file)
@@ -5,7 +5,7 @@ require 5;
 package Pod::Simple::TranscodeDumb;
 use strict;
 use vars qw($VERSION %Supported);
-$VERSION = '3.16';
+$VERSION = '3.17';
 # This module basically pretends it knows how to transcode, except
 #  only for null-transcodings!  We use this when Encode isn't
 #  available.
index 5c10f02..c16cbfe 100644 (file)
@@ -9,7 +9,7 @@ use strict;
 use Pod::Simple;
 require Encode;
 use vars qw($VERSION );
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 sub is_dumb  {0}
 sub is_smart {1}
index ef05ddb..21e3318 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.16';
+$VERSION = '3.17';
 use Pod::Simple::Methody ();
 @ISA = ('Pod::Simple::Methody');
 
@@ -194,6 +194,16 @@ to the empty string.
 Whether to add a table-of-contents at the top of each page (called an
 index for the sake of tradition).
 
+=head2 anchor_items
+
+Whether to anchor every definition C<=item> directive. This needs to be
+enabled if you want to be able to link to specific C<=item> directives, which
+are output as C<< <dt> >> elements. Disabled by default.
+
+=head2 backlink
+
+Whether to turn every =head1 directive into a link pointing to the top 
+of the page (specifically, the opening body tag).
 
 =cut
 
@@ -215,6 +225,8 @@ __PACKAGE__->_accessorize(
  'html_header',
  'html_footer',
  'index',
+ 'anchor_items',
+ 'backlink',
  'batch_mode', # whether we're in batch mode
  'batch_mode_current_level',
     # When in batch mode, how deep the current module is: 1 for "LWP",
@@ -244,7 +256,7 @@ sub new {
   $new->{'to_index'} = [];
   $new->{'output'} = [];
   $new->{'saved'} = [];
-  $new->{'ids'} = {};
+  $new->{'ids'} = { '_podtop_' => 1 }; # used in <body>
   $new->{'in_li'} = [];
 
   $new->{'__region_targets'}  = [];
@@ -273,7 +285,7 @@ want to override this if you are adding a custom element type that does
 more than just display formatted text. Perhaps adding a way to generate
 HTML tables from an extended version of POD.
 
-So, let's say you want add a custom element called 'foo'. In your
+So, let's say you want to add a custom element called 'foo'. In your
 subclass's C<new> method, after calling C<SUPER::new> you'd call:
 
   $new->accept_targets_as_text( 'foo' );
@@ -342,11 +354,7 @@ sub start_item_bullet {
 }
 
 sub start_item_text   {
-    if ($_[0]{'in_dd'}[ $_[0]{'dl_level'} ]) {
-        $_[0]{'scratch'} = "</dd>\n";
-        $_[0]{'in_dd'}[ $_[0]{'dl_level'} ] = 0;
-    }
-    $_[0]{'scratch'} .= '<dt>';
+    # see end_item_text
 }
 
 sub start_over_bullet { $_[0]{'scratch'} = '<ul>'; push @{$_[0]{'in_li'}}, 0; $_[0]->emit }
@@ -402,7 +410,10 @@ sub _end_head {
 
     my $id = $_[0]->idify($_[0]{scratch});
     my $text = $_[0]{scratch};
-    $_[0]{'scratch'} = qq{<h$h id="$id">$text</h$h>};
+    $_[0]{'scratch'} = $_[0]->backlink && ($h - $add == 0) 
+                         # backlinks enabled && =head1
+                         ? qq{<a href="#_podtop_"><h$h id="$id">$text</h$h></a>}
+                         : qq{<h$h id="$id">$text</h$h>};
     $_[0]->emit;
     push @{ $_[0]{'to_index'} }, [$h, $id, $text];
 }
@@ -416,7 +427,21 @@ sub end_item_bullet { $_[0]{'scratch'} .= '</p>'; $_[0]->emit }
 sub end_item_number { $_[0]{'scratch'} .= '</p>'; $_[0]->emit }
 
 sub end_item_text   {
-    $_[0]{'scratch'} .= "</dt>\n<dd>";
+    # idify and anchor =item content if wanted
+    my $dt_id = $_[0]{'anchor_items'} 
+                 ? ' id="'. $_[0]->idify($_[0]{'scratch'}) .'"'
+                 : '';
+
+    # reset scratch
+    my $text = $_[0]{scratch};
+    $_[0]{'scratch'} = '';
+
+    if ($_[0]{'in_dd'}[ $_[0]{'dl_level'} ]) {
+        $_[0]{'scratch'} = "</dd>\n";
+        $_[0]{'in_dd'}[ $_[0]{'dl_level'} ] = 0;
+    }
+
+    $_[0]{'scratch'} .= qq{<dt$dt_id>$text</dt>\n<dd>};
     $_[0]{'in_dd'}[ $_[0]{'dl_level'} ] = 1;
     $_[0]->emit;
 }
@@ -451,7 +476,7 @@ sub start_Document {
     $self->{'scratch'} .= $self->html_header;
     $self->emit unless $self->html_header eq "";
   } else {
-    my ($doctype, $title, $metatags);
+    my ($doctype, $title, $metatags, $bodyid);
     $doctype = $self->html_doctype || '';
     $title = $self->force_title || $self->title || $self->default_title || '';
     $metatags = $self->html_header_tags || '';
@@ -463,6 +488,7 @@ sub start_Document {
       $metatags .= "\n<script type='text/javascript' src='" .
                     $self->html_javascript . "'></script>";
     }
+    $bodyid = $self->backlink ? ' id="_podtop_"' : '';
     $self->{'scratch'} .= <<"HTML";
 $doctype
 <html>
@@ -470,7 +496,7 @@ $doctype
 <title>$title</title>
 $metatags
 </head>
-<body>
+<body$bodyid>
 HTML
     $self->emit;
   }
index 69b992d..00d71b6 100644 (file)
@@ -5,7 +5,7 @@ use strict;
 use Carp ();
 use Pod::Simple ();
 use vars qw( $ATTR_PAD @ISA $VERSION $SORT_ATTRS);
-$VERSION = '3.16';
+$VERSION = '3.17';
 BEGIN {
   @ISA = ('Pod::Simple');
   *DEBUG = \&Pod::Simple::DEBUG unless defined &DEBUG;
index a55ca72..7250320 100644 (file)
@@ -8,7 +8,7 @@ BEGIN {
 use strict;
 use Pod::Simple::Search;
 use Test;
-BEGIN { plan tests => 15 }
+BEGIN { plan tests => 16 }
 
 print "# Some basic sanity tests...\n";
 
@@ -22,6 +22,7 @@ ok defined $x->can('inc');
 ok defined $x->can('laborious');
 ok defined $x->can('limit_glob');
 ok defined $x->can('limit_re');
+ok defined $x->can('recurse');
 ok defined $x->can('shadows');
 ok defined $x->can('verbose');
 ok defined $x->can('survey');
index c69334b..21f8a2d 100644 (file)
@@ -13,7 +13,7 @@ use strict;
 
 use Pod::Simple::Search;
 use Test;
-BEGIN { plan tests => 7 }
+BEGIN { plan tests => 11 }
 
 print "# ", __FILE__,
  ": Testing the surveying of a single specified docroot...\n";
@@ -21,7 +21,7 @@ print "# ", __FILE__,
 my $x = Pod::Simple::Search->new;
 die "Couldn't make an object!?" unless ok defined $x;
 
-print "# Testing the surveying of the current directory...\n";
+print "# Testing the surveying of a single docroot...\n";
 
 $x->inc(0);
 
@@ -80,6 +80,32 @@ ok( ($name2where->{'squaa'} || 'huh???'), '/squaa\.pm$/');
 
 ok grep( m/squaa\.pm/, keys %$where2name ), 1;
 
+###### Now with recurse(0)
+
+print "# Testing the surveying of a single docroot without recursing...\n";
+
+$x->recurse(0);
+($name2where, $where2name) = $x->survey($here);
+
+$p = pretty( $where2name, $name2where )."\n";
+$p =~ s/, +/,\n/g;
+$p =~ s/^/#  /mg;
+print $p;
+
+{
+my $names = join "|", sort values %$where2name;
+ok $names, "Blorm|squaa|zikzik";
+}
+
+{
+my $names = join "|", sort keys %$name2where;
+ok $names, "Blorm|squaa|zikzik";
+}
+
+ok( ($name2where->{'squaa'} || 'huh???'), '/squaa\.pm$/');
+
+ok grep( m/squaa\.pm/, keys %$where2name ), 1;
+
 ok 1;
 
 __END__
index 4f620c0..4f8231b 100644 (file)
@@ -8,7 +8,7 @@ BEGIN {
 use strict;
 use Pod::Simple::Search;
 use Test;
-BEGIN { plan tests => 7 }
+BEGIN { plan tests => 11 }
 
 print "# ", __FILE__,
  ": Testing the surveying of the current directory...\n";
@@ -73,7 +73,34 @@ ok( ($name2where->{'squaa'} || 'huh???'), '/squaa\.pm$/');
 
 ok grep( m/squaa\.pm/, keys %$where2name ), 1;
 
+###### Now with recurse(0)
+
+print "# Testing the surveying of a current directory without recursing...\n";
+
+$x->recurse(0);
+($name2where, $where2name) = $x->survey($cwd);
+
+$p = pretty( $where2name, $name2where )."\n";
+$p =~ s/, +/,\n/g;
+$p =~ s/^/#  /mg;
+print $p;
+
+{
+my $names = join "|", sort values %$where2name;
+ok $names, "";
+}
+
+{
+my $names = join "|", sort keys %$name2where;
+ok $names, "";
+}
+
+ok( ($name2where->{'squaa'} || 'huh???'), 'huh???');
+
+ok grep( m/squaa\.pm/, keys %$where2name ), 0;
+
 ok 1;
 
 __END__
 
+
index 3022b36..ea161cc 100644 (file)
@@ -8,7 +8,7 @@ BEGIN {
 use strict;
 use Pod::Simple::Search;
 use Test;
-BEGIN { plan tests => 7 }
+BEGIN { plan tests => 11 }
 
 print "# ", __FILE__,
  ": Testing the scanning of several (well, two) docroots...\n";
@@ -85,6 +85,37 @@ ok( ($name2where->{'squaa'} || 'huh???'), '/squaa\.pm$/');
 
 ok grep( m/squaa\.pm/, keys %$where2name ), 1;
 
+###### Now with recurse(0)
+
+$x->recurse(0);
+
+print "# OK, starting run without recurse...\n# [[\n";
+($name2where, $where2name) = $x->survey($here1, $here2);
+print "# ]]\n#OK, run without recurse done.\n";
+
+$p = pretty( $where2name, $name2where )."\n";
+$p =~ s/, +/,\n/g;
+$p =~ s/^/#  /mg;
+print $p;
+
+{
+my $names = join "|", sort values %$where2name;
+skip $^O eq 'VMS' ? '-- case may or may not be preserved' : 0, 
+     $names, 
+     "Blorm|Suzzle|squaa|zikzik";
+}
+
+{
+my $names = join "|", sort keys %$name2where;
+skip $^O eq 'VMS' ? '-- case may or may not be preserved' : 0, 
+     $names, 
+     "Blorm|Suzzle|squaa|zikzik";
+}
+
+ok( ($name2where->{'squaa'} || 'huh???'), '/squaa\.pm$/');
+
+ok grep( m/squaa\.pm/, keys %$where2name ), 1;
+
 ok 1;
 
 __END__
index ef85c5a..8650fb8 100644 (file)
@@ -8,7 +8,7 @@ BEGIN {
 
 use strict;
 use lib '../lib';
-use Test::More tests => 79;
+use Test::More tests => 87;
 #use Test::More 'no_plan';
 
 use_ok('Pod::Simple::XHTML') or exit;
@@ -85,6 +85,13 @@ for my $spec (
         "<pre><code>foo bar\nbaz blez</code></pre>\n\n",
         'militant code ref'
     ],
+    [
+        "\n=pod\n\n foo (bar\n   baz blez\n",
+        sub { (my $i = $_[0]->[0]) =~ s/S.*//; $i },
+        qq{<Document><Verbatim\nxml:space="preserve">\n   baz blez</Verbatim></Document>},
+        "<pre><code>\n   baz blez</code></pre>\n\n",
+        'code ref and paren'
+    ],
 ) {
     my ($pod, $indent, $xml, $xhtml, $desc) = @$spec;
     # Test XML output.
index c3ec202..6f54dd4 100644 (file)
@@ -8,7 +8,7 @@ BEGIN {
 
 use strict;
 use lib '../lib';
-use Test::More tests => 44;
+use Test::More tests => 56;
 #use Test::More 'no_plan';
 
 use_ok('Pod::Simple::XHTML') or exit;
@@ -397,6 +397,262 @@ is $results, <<'EOF', 'And it should work!';
 
 EOF
 
+initialize($parser, $results);
+$parser->html_header($header);
+$parser->html_footer($footer);
+$parser->backlink(1);
+ok $parser->parse_string_document( '=head1 Foo' ), 'Parse a header';
+is $results, <<'EOF', 'Should have the index and a backlink';
+
+<html>
+<head>
+<title></title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+</head>
+<body id="_podtop_">
+
+
+<ul id="index">
+  <li><a href="#Foo">Foo</a></li>
+</ul>
+
+<a href="#_podtop_"><h1 id="Foo">Foo</h1></a>
+
+</body>
+</html>
+
+EOF
+
+initialize($parser, $results);
+$parser->html_header($header);
+$parser->html_footer($footer);
+$parser->backlink(1);
+ok $parser->parse_string_document( "=head1 Foo \n\n=head2 Bar \n\n=head1 Baz" ), 'Parse headers';
+is $results, <<'EOF', 'Should have the index and backlinks';
+
+<html>
+<head>
+<title></title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+</head>
+<body id="_podtop_">
+
+
+<ul id="index">
+  <li><a href="#Foo">Foo</a>
+    <ul>
+      <li><a href="#Bar">Bar</a></li>
+    </ul>
+  </li>
+  <li><a href="#Baz">Baz</a></li>
+</ul>
+
+<a href="#_podtop_"><h1 id="Foo">Foo</h1></a>
+
+<h2 id="Bar">Bar</h2>
+
+<a href="#_podtop_"><h1 id="Baz">Baz</h1></a>
+
+</body>
+</html>
+
+EOF
+
+initialize($parser, $results);
+$parser->html_header($header);
+$parser->html_footer($footer);
+$parser->index(0);
+$parser->backlink(1);
+ok $parser->parse_string_document( "=head1 Foo \n\n=head1 Bar" ), 'Parse headers';
+is $results, <<'EOF', 'Should have backlinks but no index';
+
+<html>
+<head>
+<title></title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+</head>
+<body id="_podtop_">
+
+
+<a href="#_podtop_"><h1 id="Foo">Foo</h1></a>
+
+<a href="#_podtop_"><h1 id="Bar">Bar</h1></a>
+
+</body>
+</html>
+
+EOF
+
+initialize($parser, $results);
+$parser->html_header($header);
+$parser->html_footer($footer);
+$parser->backlink(1);
+$parser->html_h_level(2);
+ok $parser->parse_string_document( "=head1 Foo \n\n=head1 Bar" ), 'Parse headers';
+is $results, <<'EOF', 'Should have index and backlinks around h2 elements';
+
+<html>
+<head>
+<title></title>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
+</head>
+<body id="_podtop_">
+
+
+<ul id="index">
+  <li>
+    <ul>
+      <li><a href="#Foo">Foo</a></li>
+      <li><a href="#Bar">Bar</a></li>
+    </ul>
+  </li>
+</ul>
+
+<a href="#_podtop_"><h2 id="Foo">Foo</h2></a>
+
+<a href="#_podtop_"><h2 id="Bar">Bar</h2></a>
+
+</body>
+</html>
+
+EOF
+
+initialize($parser, $results);
+$parser->anchor_items(1);
+ok $parser->parse_string_document( <<'EOPOD' ), 'Parse POD';
+=head1 Foo
+
+=over
+
+=item test
+
+=item Test 2
+
+body of item
+
+=back
+
+=over
+
+=item *
+
+not anchored
+
+=back
+
+=over
+
+=item 1
+
+still not anchored
+
+=back
+EOPOD
+
+is $results, <<'EOF', 'Anchor =item directives';
+<ul id="index">
+  <li><a href="#Foo">Foo</a></li>
+</ul>
+
+<h1 id="Foo">Foo</h1>
+
+<dl>
+
+<dt id="test">test</dt>
+<dd>
+
+</dd>
+<dt id="Test-2">Test 2</dt>
+<dd>
+
+<p>body of item</p>
+
+</dd>
+</dl>
+
+<ul>
+
+<li><p>not anchored</p>
+
+</li>
+</ul>
+
+<ol>
+
+<li><p>still not anchored</p>
+
+</li>
+</ol>
+
+EOF
+
+initialize($parser, $results);
+$parser->anchor_items(0);
+ok $parser->parse_string_document( <<'EOPOD' ), 'Parse POD';
+=head1 Foo
+
+=over
+
+=item test
+
+=item Test 2
+
+body of item
+
+=back
+
+=over
+
+=item *
+
+not anchored
+
+=back
+
+=over
+
+=item 1
+
+still not anchored
+
+=back
+EOPOD
+is $results, <<'EOF', 'Do not anchor =item directives';
+<ul id="index">
+  <li><a href="#Foo">Foo</a></li>
+</ul>
+
+<h1 id="Foo">Foo</h1>
+
+<dl>
+
+<dt>test</dt>
+<dd>
+
+</dd>
+<dt>Test 2</dt>
+<dd>
+
+<p>body of item</p>
+
+</dd>
+</dl>
+
+<ul>
+
+<li><p>not anchored</p>
+
+</li>
+</ul>
+
+<ol>
+
+<li><p>still not anchored</p>
+
+</li>
+</ol>
+
+EOF
 sub initialize {
        $_[0] = Pod::Simple::XHTML->new;
         $_[0]->html_header('');
index 157f115..f4fc9c7 100644 (file)
@@ -227,6 +227,10 @@ performance under ithreads.
 
 =item *
 
+L<Pod::Simple> has been upgraded from version 3.16 to version 3.17
+
+=item *
+
 L<Unicode::Collate> has been upgraded from version 0.76 to version 0.77
 
 Applied [perl #93470] silencing compiler warnings with -Wwrite-strings