Upgrade podlators from 2.5.1 to 2.5.2
authorSteve Hay <steve.m.hay@googlemail.com>
Mon, 23 Sep 2013 08:10:11 +0000 (09:10 +0100)
committerSteve Hay <steve.m.hay@googlemail.com>
Mon, 23 Sep 2013 08:10:11 +0000 (09:10 +0100)
This incorporates CPAN RT #87440.

MANIFEST
Porting/Maintainers.pl
cpan/podlators/VERSION
cpan/podlators/lib/Pod/Man.pm
cpan/podlators/lib/Pod/Text.pm
cpan/podlators/lib/Pod/Text/Termcap.pm
cpan/podlators/t/man-empty.t [new file with mode: 0644]
cpan/podlators/t/text-empty.t [new file with mode: 0644]
pod/perldelta.pod
t/porting/customized.dat

index d061153..e5489a4 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -1850,6 +1850,7 @@ cpan/podlators/t/basic.txt                        podlators test
 cpan/podlators/t/color.t                       podlators test
 cpan/podlators/t/devise-date.t                 podlators test
 cpan/podlators/t/filehandle.t                  podlators test
+cpan/podlators/t/man-empty.t                   podlators test
 cpan/podlators/t/man-heading.t                 podlators test
 cpan/podlators/t/man-options.t                 podlators test
 cpan/podlators/t/man-perlio.t                          podlators test
@@ -1861,6 +1862,7 @@ cpan/podlators/t/pod-parser.t                     podlators test
 cpan/podlators/t/pod-spelling.t                        podlators test
 cpan/podlators/t/pod.t                         podlators test
 cpan/podlators/t/termcap.t                     podlators test
+cpan/podlators/t/text-empty.t                  podlators test
 cpan/podlators/t/text-encoding.t               podlators test
 cpan/podlators/t/text-options.t                        podlators test
 cpan/podlators/t/text-perlio.t                 podlators test
index 93646bb..0d3b4e2 100755 (executable)
@@ -1513,7 +1513,7 @@ use File::Glob qw(:case);
 
     'podlators' => {
         'MAINTAINER'   => 'rra',
-        'DISTRIBUTION' => 'RRA/podlators-2.5.1.tar.gz',
+        'DISTRIBUTION' => 'RRA/podlators-2.5.2.tar.gz',
         'FILES'        => q[cpan/podlators pod/perlpodstyle.pod],
 
         # The perl distribution has pod2man.PL and pod2text.PL,  which are
@@ -1524,10 +1524,6 @@ use File::Glob qw(:case);
             qw( scripts/pod2man.PL
                 scripts/pod2text.PL
                 ),
-
-            # Waiting to be merged upstream: see CPAN RT#87440
-            qw( pod/perlpodstyle.pod
-                ),
         ],
         'MAP' => {
             ''                 => 'cpan/podlators/',
index 69771f2..492e415 100644 (file)
@@ -1 +1 @@
-$VERSION = '2.5.1';
+$VERSION = '2.5.2';
index 5e5f4dc..39ff7f5 100644 (file)
@@ -36,7 +36,7 @@ use Pod::Simple ();
 
 @ISA = qw(Pod::Simple);
 
-$VERSION = '2.27';
+$VERSION = '2.28';
 
 # Set the debugging level.  If someone has inserted a debug function into this
 # class already, use that.  Otherwise, use any Pod::Simple debug function
@@ -56,6 +56,27 @@ BEGIN { *ASCII = \&Pod::Simple::ASCII }
 # Pretty-print a data structure.  Only used for debugging.
 BEGIN { *pretty = \&Pod::Simple::pretty }
 
+# Formatting instructions for various types of blocks.  cleanup makes hyphens
+# hard, adds spaces between consecutive underscores, and escapes backslashes.
+# convert translates characters into escapes.  guesswork means to apply the
+# transformations done by the guesswork sub.  literal says to protect literal
+# quotes from being turned into UTF-8 quotes.  By default, all transformations
+# are on except literal, but some elements override.
+#
+# DEFAULT specifies the default settings.  All other elements should list only
+# those settings that they are overriding.  Data indicates =for roff blocks,
+# which should be passed along completely verbatim.
+#
+# Formatting inherits negatively, in the sense that if the parent has turned
+# off guesswork, all child elements should leave it off.
+my %FORMATTING = (
+    DEFAULT  => { cleanup => 1, convert => 1, guesswork => 1, literal => 0 },
+    Data     => { cleanup => 0, convert => 0, guesswork => 0, literal => 0 },
+    Verbatim => {                             guesswork => 0, literal => 1 },
+    C        => {                             guesswork => 0, literal => 1 },
+    X        => { cleanup => 0,               guesswork => 0               },
+);
+
 ##############################################################################
 # Object initialization
 ##############################################################################
@@ -73,8 +94,8 @@ sub new {
     $self->nbsp_for_S (1);
 
     # Tell Pod::Simple to keep whitespace whenever possible.
-    if ($self->can ('preserve_whitespace')) {
-        $self->preserve_whitespace (1);
+    if (my $preserve_whitespace = $self->can ('preserve_whitespace')) {
+        $self->$preserve_whitespace (1);
     } else {
         $self->fullstop_space_harden (1);
     }
@@ -257,8 +278,7 @@ sub _handle_text {
 # Given an element name, get the corresponding method name.
 sub method_for_element {
     my ($self, $element) = @_;
-    $element =~ tr/-/_/;
-    $element =~ tr/A-Z/a-z/;
+    $element =~ tr/A-Z-/a-z_/;
     $element =~ tr/_a-z0-9//cd;
     return $element;
 }
@@ -284,13 +304,14 @@ sub _handle_element_start {
         # and also depends on our parent tags.  Thankfully, inside tags that
         # turn off guesswork and reformatting, nothing else can turn it back
         # on, so this can be strictly inherited.
-        my $formatting = $$self{PENDING}[-1][1];
-        $formatting = $self->formatting ($formatting, $element);
+        my $formatting = {
+            %{ $$self{PENDING}[-1][1] || $FORMATTING{DEFAULT} },
+            %{ $FORMATTING{$element} || {} },
+        };
         push (@{ $$self{PENDING} }, [ $attrs, $formatting, '' ]);
         DEBUG > 4 and print "Pending: [", pretty ($$self{PENDING}), "]\n";
-    } elsif ($self->can ("start_$method")) {
-        my $method = 'start_' . $method;
-        $self->$method ($attrs, '');
+    } elsif (my $start_method = $self->can ("start_$method")) {
+        $self->$start_method ($attrs, '');
     } else {
         DEBUG > 2 and print "No $method start method, skipping\n";
     }
@@ -306,13 +327,12 @@ sub _handle_element_end {
 
     # If we have a command handler, pull off the pending text and pass it to
     # the handler along with the saved attribute hash.
-    if ($self->can ("cmd_$method")) {
+    if (my $cmd_method = $self->can ("cmd_$method")) {
         DEBUG > 2 and print "</$element> stops saving a tag\n";
         my $tag = pop @{ $$self{PENDING} };
         DEBUG > 4 and print "Popped: [", pretty ($tag), "]\n";
         DEBUG > 4 and print "Pending: [", pretty ($$self{PENDING}), "]\n";
-        my $method = 'cmd_' . $method;
-        my $text = $self->$method ($$tag[0], $$tag[2]);
+        my $text = $self->$cmd_method ($$tag[0], $$tag[2]);
         if (defined $text) {
             if (@{ $$self{PENDING} } > 1) {
                 $$self{PENDING}[-1][2] .= $text;
@@ -320,9 +340,8 @@ sub _handle_element_end {
                 $self->output ($text);
             }
         }
-    } elsif ($self->can ("end_$method")) {
-        my $method = 'end_' . $method;
-        $self->$method ();
+    } elsif (my $end_method = $self->can ("end_$method")) {
+        $self->$end_method ();
     } else {
         DEBUG > 2 and print "No $method end method, skipping\n";
     }
@@ -332,34 +351,6 @@ sub _handle_element_end {
 # General formatting
 ##############################################################################
 
-# Return formatting instructions for a new block.  Takes the current
-# formatting and the new element.  Formatting inherits negatively, in the
-# sense that if the parent has turned off guesswork, all child elements should
-# leave it off.  We therefore return a copy of the same formatting
-# instructions but possibly with more things turned off depending on the
-# element.
-sub formatting {
-    my ($self, $current, $element) = @_;
-    my %options;
-    if ($current) {
-        %options = %$current;
-    } else {
-        %options = (guesswork => 1, cleanup => 1, convert => 1);
-    }
-    if ($element eq 'Data') {
-        $options{guesswork} = 0;
-        $options{cleanup} = 0;
-        $options{convert} = 0;
-    } elsif ($element eq 'X') {
-        $options{guesswork} = 0;
-        $options{cleanup} = 0;
-    } elsif ($element eq 'Verbatim' || $element eq 'C') {
-        $options{guesswork} = 0;
-        $options{literal} = 1;
-    }
-    return \%options;
-}
-
 # Format a text block.  Takes a hash of formatting options and the text to
 # format.  Currently, the only formatting options are guesswork, cleanup, and
 # convert, all of which are boolean.
@@ -456,7 +447,7 @@ sub guesswork {
     local $_ = shift;
     DEBUG > 5 and print "   Guesswork called on [$_]\n";
 
-    # By the time we reach this point, all hypens will be escaped by adding a
+    # By the time we reach this point, all hyphens will be escaped by adding a
     # backslash.  We want to undo that escaping if they're part of regular
     # words and there's only a single dash, since that's a real hyphen that
     # *roff gets to consider a possible break point.  Make sure that a dash
@@ -512,7 +503,7 @@ sub guesswork {
     # strings inserted around things that we've made small-caps if later
     # transforms should work on those strings.
 
-    # Italize functions in the form func(), including functions that are in
+    # Italicize functions in the form func(), including functions that are in
     # all capitals, but don't italize if there's anything between the parens.
     # The function must start with an alphabetic character or underscore and
     # then consist of word characters or colons.
@@ -767,7 +758,6 @@ sub start_document {
     if ($$attrs{contentless} && !$$self{ALWAYS_EMIT_SOMETHING}) {
         DEBUG and print "Document is contentless\n";
         $$self{CONTENTLESS} = 1;
-        return;
     } else {
         delete $$self{CONTENTLESS};
     }
@@ -788,17 +778,20 @@ sub start_document {
         }
     }
 
-    # Determine information for the preamble and then output it.
-    my ($name, $section);
-    if (defined $$self{name}) {
-        $name = $$self{name};
-        $section = $$self{section} || 1;
-    } else {
-        ($name, $section) = $self->devise_title;
+    # Determine information for the preamble and then output it unless the
+    # document was content-free.
+    if (!$$self{CONTENTLESS}) {
+        my ($name, $section);
+        if (defined $$self{name}) {
+            $name = $$self{name};
+            $section = $$self{section} || 1;
+        } else {
+            ($name, $section) = $self->devise_title;
+        }
+        my $date = $$self{date} || $self->devise_date;
+        $self->preamble ($name, $section, $date)
+            unless $self->bare_output or DEBUG > 9;
     }
-    my $date = $$self{date} || $self->devise_date;
-    $self->preamble ($name, $section, $date)
-        unless $self->bare_output or DEBUG > 9;
 
     # Initialize a few per-document variables.
     $$self{INDENT}    = 0;      # Current indentation level.
@@ -988,9 +981,12 @@ sub cmd_para {
         if defined ($line) && DEBUG && !$$self{IN_NAME};
 
     # Force exactly one newline at the end and strip unwanted trailing
-    # whitespace at the end, but leave "\ " backslashed space from an S< >
-    # at the end of a line.
-    $text =~ s/((?:\\ )*)\s*$/$1\n/;
+    # whitespace at the end, but leave "\ " backslashed space from an S< > at
+    # the end of a line.  Reverse the text first, to avoid having to scan the
+    # entire paragraph.
+    $text = reverse $text;
+    $text =~ s/\A\s*?(?= \\|\S|\z)/\n/;
+    $text = reverse $text;
 
     # Output the paragraph.
     $self->output ($self->protect ($self->textmapfonts ($text)));
@@ -1009,8 +1005,11 @@ sub cmd_verbatim {
     return unless $text =~ /\S/;
 
     # Force exactly one newline at the end and strip unwanted trailing
-    # whitespace at the end.
-    $text =~ s/\s*$/\n/;
+    # whitespace at the end.  Reverse the text first, to avoid having to scan
+    # the entire paragraph.
+    $text = reverse $text;
+    $text =~ s/\A\s*/\n/;
+    $text = reverse $text;
 
     # Get a count of the number of lines before the first blank line, which
     # we'll pass to .Vb as its parameter.  This tells *roff to keep that many
@@ -1354,6 +1353,26 @@ sub parse_file {
     return $self->SUPER::parse_file ($in);
 }
 
+# Do the same for parse_lines, just to be polite.  Pod::Simple's man page
+# implies that the caller is responsible for setting this, but I don't see any
+# reason not to set a default.
+sub parse_lines {
+    my ($self, @lines) = @_;
+    unless (defined $$self{output_fh}) {
+        $self->output_fh (\*STDOUT);
+    }
+    return $self->SUPER::parse_lines (@lines);
+}
+
+# Likewise for parse_string_document.
+sub parse_string_document {
+    my ($self, $doc) = @_;
+    unless (defined $$self{output_fh}) {
+        $self->output_fh (\*STDOUT);
+    }
+    return $self->SUPER::parse_string_document ($doc);
+}
+
 ##############################################################################
 # Translation tables
 ##############################################################################
@@ -1547,7 +1566,7 @@ __END__
 =for stopwords
 en em ALLCAPS teeny fixedbold fixeditalic fixedbolditalic stderr utf8
 UTF-8 Allbery Sean Burke Ossanna Solaris formatters troff uppercased
-Christiansen nourls
+Christiansen nourls parsers
 
 =head1 NAME
 
@@ -1746,16 +1765,22 @@ L<perlpod(1)> for more information on the C<=encoding> command.
 
 The standard Pod::Simple method parse_file() takes one argument naming the
 POD file to read from.  By default, the output is sent to C<STDOUT>, but
-this can be changed with the output_fd() method.
+this can be changed with the output_fh() method.
 
 The standard Pod::Simple method parse_from_file() takes up to two
 arguments, the first being the input file to read POD from and the second
 being the file to write the formatted output to.
 
 You can also call parse_lines() to parse an array of lines or
-parse_string_document() to parse a document already in memory.  To put the
-output into a string instead of a file handle, call the output_string()
-method.  See L<Pod::Simple> for the specific details.
+parse_string_document() to parse a document already in memory.  As with
+parse_file(), parse_lines() and parse_string_document() default to sending
+their output to C<STDOUT> unless changed with the output_fh() method.
+
+To put the output from any parse method into a string instead of a file
+handle, call the output_string() method instead of output_fh().
+
+See L<Pod::Simple> for more specific details on the methods available to
+all derived parsers.
 
 =head1 DIAGNOSTICS
 
index f57256f..ed95591 100644 (file)
@@ -38,7 +38,7 @@ use Pod::Simple ();
 # We have to export pod2text for backward compatibility.
 @EXPORT = qw(pod2text);
 
-$VERSION = '3.17';
+$VERSION = '3.18';
 
 ##############################################################################
 # Initialization
@@ -301,7 +301,6 @@ sub start_document {
     my ($self, $attrs) = @_;
     if ($$attrs{contentless} && !$$self{ALWAYS_EMIT_SOMETHING}) {
         $$self{CONTENTLESS} = 1;
-        return;
     } else {
         delete $$self{CONTENTLESS};
     }
@@ -727,6 +726,26 @@ sub parse_file {
     return $self->SUPER::parse_file ($in);
 }
 
+# Do the same for parse_lines, just to be polite.  Pod::Simple's man page
+# implies that the caller is responsible for setting this, but I don't see any
+# reason not to set a default.
+sub parse_lines {
+    my ($self, @lines) = @_;
+    unless (defined $$self{output_fh}) {
+        $self->output_fh (\*STDOUT);
+    }
+    return $self->SUPER::parse_lines (@lines);
+}
+
+# Likewise for parse_string_document.
+sub parse_string_document {
+    my ($self, $doc) = @_;
+    unless (defined $$self{output_fh}) {
+        $self->output_fh (\*STDOUT);
+    }
+    return $self->SUPER::parse_string_document ($doc);
+}
+
 ##############################################################################
 # Module return value and documentation
 ##############################################################################
@@ -736,6 +755,7 @@ __END__
 
 =for stopwords
 alt stderr Allbery Sean Burke's Christiansen UTF-8 pre-Unicode utf8 nourls
+parsers
 
 =head1 NAME
 
@@ -871,10 +891,24 @@ The column at which to wrap text on the right-hand side.  Defaults to 76.
 
 =back
 
-The standard Pod::Simple method parse_file() takes one argument, the file or
-file handle to read from, and writes output to standard output unless that
-has been changed with the output_fh() method.  See L<Pod::Simple> for the
-specific details and for other alternative interfaces.
+The standard Pod::Simple method parse_file() takes one argument naming the
+POD file to read from.  By default, the output is sent to C<STDOUT>, but
+this can be changed with the output_fh() method.
+
+The standard Pod::Simple method parse_from_file() takes up to two
+arguments, the first being the input file to read POD from and the second
+being the file to write the formatted output to.
+
+You can also call parse_lines() to parse an array of lines or
+parse_string_document() to parse a document already in memory.  As with
+parse_file(), parse_lines() and parse_string_document() default to sending
+their output to C<STDOUT> unless changed with the output_fh() method.
+
+To put the output from any parse method into a string instead of a file
+handle, call the output_string() method instead of output_fh().
+
+See L<Pod::Simple> for more specific details on the methods available to
+all derived parsers.
 
 =head1 DIAGNOSTICS
 
index 8638060..18ba7b2 100644 (file)
@@ -27,7 +27,7 @@ use vars qw(@ISA $VERSION);
 
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.07';
+$VERSION = '2.08';
 
 ##############################################################################
 # Overrides
@@ -104,7 +104,7 @@ sub strip_format {
     return $text;
 }
 
-# Override the wrapping code to igore the special sequences.
+# Override the wrapping code to ignore the special sequences.
 sub wrap {
     my $self = shift;
     local $_ = shift;
@@ -113,7 +113,7 @@ sub wrap {
     my $width = $$self{opt_width} - $$self{MARGIN};
 
     # $codes matches a single special sequence.  $char matches any number of
-    # special sequences preceeding a single character other than a newline.
+    # special sequences preceding a single character other than a newline.
     # We have to do $shortchar and $longchar in variables because the
     # construct ${char}{0,$width} didn't do the right thing until Perl 5.8.x.
     my $codes = "(?:\Q$$self{BOLD}\E|\Q$$self{UNDL}\E|\Q$$self{NORM}\E)";
diff --git a/cpan/podlators/t/man-empty.t b/cpan/podlators/t/man-empty.t
new file mode 100644 (file)
index 0000000..8ba97df
--- /dev/null
@@ -0,0 +1,42 @@
+#!/usr/bin/perl -w
+#
+# man-empty.t -- Test Pod::Man with a document that produces only errors.
+#
+# Copyright 2013 Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+BEGIN {
+    chdir 't' if -d 't';
+    if ($ENV{PERL_CORE}) {
+        @INC = '../lib';
+    }
+    unshift (@INC, '../blib/lib');
+    $| = 1;
+}
+
+use strict;
+
+use Test::More tests => 8;
+BEGIN { use_ok ('Pod::Man') }
+
+# Set up Pod::Man to output to a string.
+my $parser = Pod::Man->new;
+isa_ok ($parser, 'Pod::Man');
+my $output;
+$parser->output_string (\$output);
+
+# Try a POD document where the only command is invalid.
+ok (eval { $parser->parse_string_document("=\xa0") },
+    'Parsed invalid document');
+is ($@, '', '...with no errors');
+like ($output, qr{\.SH \"POD ERRORS\"},
+      '...and output contains a POD ERRORS section');
+
+# Try with a document containing only =cut.
+ok (eval { $parser->parse_string_document("=cut") },
+    'Parsed invalid document');
+is ($@, '', '...with no errors');
+like ($output, qr{\.SH \"POD ERRORS\"},
+      '...and output contains a POD ERRORS section');
diff --git a/cpan/podlators/t/text-empty.t b/cpan/podlators/t/text-empty.t
new file mode 100644 (file)
index 0000000..0a4c66a
--- /dev/null
@@ -0,0 +1,42 @@
+#!/usr/bin/perl -w
+#
+# text-empty.t -- Test Pod::Text with a document that produces only errors.
+#
+# Copyright 2013 Russ Allbery <rra@stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+BEGIN {
+    chdir 't' if -d 't';
+    if ($ENV{PERL_CORE}) {
+        @INC = '../lib';
+    }
+    unshift (@INC, '../blib/lib');
+    $| = 1;
+}
+
+use strict;
+
+use Test::More tests => 8;
+BEGIN { use_ok ('Pod::Text') }
+
+# Set up Pod::Text to output to a string.
+my $parser = Pod::Text->new;
+isa_ok ($parser, 'Pod::Text');
+my $output;
+$parser->output_string (\$output);
+
+# Try a POD document where the only command is invalid.  Be sure that we don't
+# get any warnings as well as any errors.
+local $SIG{__WARN__} = sub { die $_[0] };
+ok (eval { $parser->parse_string_document("=\xa0") },
+    'Parsed invalid document');
+is ($@, '', '...with no errors');
+like ($output, qr{POD ERRORS}, '...and output contains a POD ERRORS section');
+
+# Try with a document containing only =cut.
+ok (eval { $parser->parse_string_document("=cut") },
+    'Parsed invalid document');
+is ($@, '', '...with no errors');
+like ($output, qr{POD ERRORS}, '...and output contains a POD ERRORS section');
index f1d88a9..0d85410 100644 (file)
@@ -130,6 +130,13 @@ L<Module::CoreList> has been upgraded from version 2.99 to 3.00.
 
 The list of Perl versions covered has been updated.
 
+=item *
+
+The podlators modules have been upgraded from version 2.5.1 to 2.5.2.
+
+Numerous updates and bug fixes are incorporated.  See the F<Changes> file in
+the CPAN distribution for full details.
+
 =back
 
 =head2 Removed Modules and Pragmata
index 59f4660..af9163b 100644 (file)
@@ -24,7 +24,6 @@ autodie cpan/autodie/t/utf8_open.t 5295851351c49f939008c5aca6a798742b1e503d
 libnet cpan/libnet/Makefile.PL 6b10ac98e672bfebb8f49b9720a93442645208b3
 podlators cpan/podlators/scripts/pod2man.PL f81acf53f3ff46cdcc5ebdd661c5d13eb35d20d6
 podlators cpan/podlators/scripts/pod2text.PL b4693fcfe4a0a1b38a215cfb8985a65d5d025d69
-podlators pod/perlpodstyle.pod dcf4b8f67d963e215f0e2e1cd214246705163a79
 version cpan/version/lib/version.pm e9d5df9a053ac6882c6e73f7e29db74e01b15841
 version cpan/version/t/07locale.t c7e86c2706622d5055b617a4b0119ea874be8a7b
 version cpan/version/t/08_corelist.t bd1c900f8be98e87dbf88896b8337f0694e4b4d3