Update podlators to CPAN version 2.5.0
authorChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Fri, 4 Jan 2013 14:33:58 +0000 (14:33 +0000)
committerChris 'BinGOs' Williams <chris@bingosnet.co.uk>
Fri, 4 Jan 2013 14:33:58 +0000 (14:33 +0000)
  [DELTA]

2013-01-02  Russ Allbery  <rra@stanford.edu>

  * VERSION: podlators 2.5.0 released.

  * lib/Pod/Man.pm (guesswork): Extend a small-caps section through
  the punctuation that commonly appears in license disclaimers so
  that small caps isn't turned on and off at the boundaries of every
  word, producing unreadable *roff.
  * t/man.t: Test the updated small-caps behavior.

  * lib/Pod/Man.pm (new): Support a new errors option with values
  die, stderr, pod, and none.  Convert the stderr option to the
  errors option with value stderr.  (#39007)
  (end_document): Die if errors was set to die and there were POD
  syntax errors.
  * lib/Pod/Text.pm (new): Likewise.
  (end_document): Likewise.
  * scripts/pod2man: Support a new --errors option that sets the
  underlying errors formatter option and default to dying on POD
  syntax errors.
  * scripts/pod2text: Likewise.
  * t/man-options.t: Add support for catching exceptions during
  formatting.  Test valid and invalid errors settings.
  * t/text-options.t: Likewise.

  * lib/Pod/Man.pm (cmd_l): Add nourls option to suppress the URL
  from L<> formatting codes that contain anchor text.  (#62210)
  * lib/Pod/Text.pm (cmd_l): Likewise.
  * scripts/pod2man: New --nourls option to set the corresponding
  option in Pod::Man.
  * scripts/pod2text: Likewise for Pod::Text.
  * t/man-options.t: Test new nourls option.
  * t/text-options.t: Likewise.

  * lib/Pod/Man.pm (outindex): Also collapse consecutive whitespace
  in index term text.
  * t/man.t: Test for handling of index terms containing whitespace.

2013-01-02  Kevin Ryde  <user42@zip.com.au>

  * lib/Pod/Man.pm (outindex): Remove newlines from index term text
  since *roff quotes don't span lines.  (#82332)

2012-06-01  Russ Allbery  <rra@stanford.edu>

  * VERSION: podlators 2.4.2 released.

  * t/text-encoding.t: Remove the test of a POD document without an
  encoding.  We previously tested that this interpreted the document
  as ISO 8859-1, but Pod::Simple behavior has changed so that the
  test started failing, plus Pod::Simple now warns about a missing
  =encoding.  (#77553)

cpan/podlators/VERSION
cpan/podlators/lib/Pod/Man.pm
cpan/podlators/lib/Pod/Text.pm
cpan/podlators/lib/Pod/Text/Color.pm
cpan/podlators/lib/Pod/Text/Overstrike.pm
cpan/podlators/lib/Pod/Text/Termcap.pm
cpan/podlators/scripts/pod2man.PL
cpan/podlators/scripts/pod2text.PL
cpan/podlators/t/man-options.t
cpan/podlators/t/man.t
cpan/podlators/t/text-options.t

index 1bc3ad4..5d406fb 100644 (file)
@@ -1 +1 @@
-$VERSION = '2.4.2';
+$VERSION = '2.5.0';
index 3859371..5e5f4dc 100644 (file)
@@ -1,12 +1,5 @@
 # Pod::Man -- Convert POD data to formatted *roff input.
 #
-# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-#     2010, 2012 Russ Allbery <rra@stanford.edu>
-# Substantial contributions by Sean Burke <sburke@cpan.org>
-#
-# This program is free software; you may redistribute it and/or modify it
-# under the same terms as Perl itself.
-#
 # This module translates POD documentation into *roff markup using the man
 # macro set, and is intended for converting POD documents written as Unix
 # manual pages to manual pages that can be read by the man(1) command.  It is
 # maintained outside of the Perl core as part of the podlators.  Please send
 # me any patches at the address above in addition to sending them to the
 # standard Perl mailing lists.
+#
+# Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
+#     2010, 2012, 2013 Russ Allbery <rra@stanford.edu>
+# Substantial contributions by Sean Burke <sburke@cpan.org>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
 
 ##############################################################################
 # Modules and declarations
@@ -36,7 +36,7 @@ use Pod::Simple ();
 
 @ISA = qw(Pod::Simple);
 
-$VERSION = '2.26';
+$VERSION = '2.27';
 
 # Set the debugging level.  If someone has inserted a debug function into this
 # class already, use that.  Otherwise, use any Pod::Simple debug function
@@ -93,11 +93,30 @@ sub new {
     %$self = (%$self, @_);
 
     # Send errors to stderr if requested.
-    if ($$self{stderr}) {
+    if ($$self{stderr} and not $$self{errors}) {
+        $$self{errors} = 'stderr';
+    }
+    delete $$self{stderr};
+
+    # Validate the errors parameter and act on it.
+    if (not defined $$self{errors}) {
+        $$self{errors} = 'pod';
+    }
+    if ($$self{errors} eq 'stderr' || $$self{errors} eq 'die') {
         $self->no_errata_section (1);
         $self->complain_stderr (1);
-        delete $$self{stderr};
+        if ($$self{errors} eq 'die') {
+            $$self{complain_die} = 1;
+        }
+    } elsif ($$self{errors} eq 'pod') {
+        $self->no_errata_section (0);
+        $self->complain_stderr (0);
+    } elsif ($$self{errors} eq 'none') {
+        $self->no_whining (1);
+    } else {
+        croak (qq(Invalid errors setting: "$$self{errors}"));
     }
+    delete $$self{errors};
 
     # Initialize various other internal constants based on our arguments.
     $self->init_fonts;
@@ -474,11 +493,16 @@ sub guesswork {
     # line or following regular punctuation (like quotes) or whitespace (1),
     # and followed by either similar punctuation, an em-dash, or the end of
     # the line (3).
+    #
+    # Allow the text we're changing to small caps to include double quotes,
+    # commas, newlines, and periods as long as it doesn't otherwise interrupt
+    # the string of small caps and still fits the criteria.  This lets us turn
+    # entire warranty disclaimers in man page output into small caps.
     if ($$self{MAGIC_SMALLCAPS}) {
         s{
-            ( ^ | [\s\(\"\'\`\[\{<>] | \\\  )                   # (1)
-            ( [A-Z] [A-Z] (?: [/A-Z+:\d_\$&] | \\- )* )         # (2)
-            (?= [\s>\}\]\(\)\'\".?!,;] | \\*\(-- | \\\  | $ )   # (3)
+            ( ^ | [\s\(\"\'\`\[\{<>] | \\[ ]  )                     # (1)
+            ( [A-Z] [A-Z] (?: [/A-Z+:\d_\$&] | \\- | [.,\"\s] )* )  # (2)
+            (?= [\s>\}\]\(\)\'\".?!,;] | \\*\(-- | \\[ ] | $ )      # (3)
         } {
             $1 . '\s-1' . $2 . '\s0'
         }egx;
@@ -715,6 +739,7 @@ sub outindex {
     # Print out the .IX commands.
     for (@output) {
         my ($type, $entry) = @$_;
+        $entry =~ s/\s+/ /g;
         $entry =~ s/\"/\"\"/g;
         $entry =~ s/\\/\\\\/g;
         $self->output (".IX $type " . '"' . $entry . '"' . "\n");
@@ -787,10 +812,14 @@ sub start_document {
     $$self{PENDING}   = [[]];   # Pending output.
 }
 
-# Handle the end of the document.  This does nothing but print out a final
-# comment at the end of the document under debugging.
+# Handle the end of the document.  This handles dying on POD errors, since
+# Pod::Parser currently doesn't.  Otherwise, does nothing but print out a
+# final comment at the end of the document under debugging.
 sub end_document {
     my ($self) = @_;
+    if ($$self{complain_die} && $self->errors_seen) {
+        croak ("POD document had syntax errors");
+    }
     return if $self->bare_output;
     return if ($$self{CONTENTLESS} && !$$self{ALWAYS_EMIT_SOMETHING});
     $self->output (q(.\" [End document]) . "\n") if DEBUG;
@@ -1109,8 +1138,9 @@ sub cmd_x {
 }
 
 # Links reduce to the text that we're given, wrapped in angle brackets if it's
-# a URL.  We need to format the "to" value of the link before comparing it to
-# the text since we may escape hyphens.
+# a URL, followed by the URL.  We take an option to suppress the URL if anchor
+# text is given.  We need to format the "to" value of the link before
+# comparing it to the text since we may escape hyphens.
 sub cmd_l {
     my ($self, $attrs, $text) = @_;
     if ($$attrs{type} eq 'url') {
@@ -1121,6 +1151,8 @@ sub cmd_l {
         }
         if (not defined ($to) or $to eq $text) {
             return "<$text>";
+        } elsif ($$self{nourls}) {
+            return $text;
         } else {
             return "$text <$$attrs{to}>";
         }
@@ -1512,14 +1544,14 @@ sub preamble_template {
 1;
 __END__
 
-=head1 NAME
-
-Pod::Man - Convert POD data to formatted *roff input
-
 =for stopwords
 en em ALLCAPS teeny fixedbold fixeditalic fixedbolditalic stderr utf8
 UTF-8 Allbery Sean Burke Ossanna Solaris formatters troff uppercased
-Christiansen
+Christiansen nourls
+
+=head1 NAME
+
+Pod::Man - Convert POD data to formatted *roff input
 
 =head1 SYNOPSIS
 
@@ -1581,6 +1613,16 @@ argument.
 Sets the centered page header to use instead of "User Contributed Perl
 Documentation".
 
+=item errors
+
+How to report errors.  C<die> says to throw an exception on any POD
+formatting error.  C<stderr> says to report errors on standard error, but
+not to throw an exception.  C<pod> says to include a POD ERRORS section
+in the resulting documentation summarizing the errors.  C<none> ignores
+POD errors entirely, as much as possible.
+
+The default is C<output>.
+
 =item date
 
 Sets the left-hand footer.  By default, the modification date of the input
@@ -1621,6 +1663,22 @@ module path.  If it is, a path like C<.../lib/Pod/Man.pm> is converted into
 a name like C<Pod::Man>.  This option, if given, overrides any automatic
 determination of the name.
 
+=item nourls
+
+Normally, LZ<><> formatting codes with a URL but anchor text are formatted
+to show both the anchor text and the URL.  In other words:
+
+    L<foo|http://example.com/>
+
+is formatted as:
+
+    foo <http://example.com/>
+
+This option, if set to a true value, suppresses the URL when anchor text
+is given, so this example would be formatted as just C<foo>.  This can
+produce less cluttered output in cases where the URLs are not particularly
+important.
+
 =item quotes
 
 Sets the quote marks used to surround CE<lt>> text.  If the value is a
@@ -1658,7 +1716,9 @@ case section 3 will be selected.
 =item stderr
 
 Send error messages about invalid POD to standard error instead of
-appending a POD ERRORS section to the generated *roff output.
+appending a POD ERRORS section to the generated *roff output.  This is
+equivalent to setting C<errors> to C<stderr> if C<errors> is not already
+set.  It is supported for backward compatibility.
 
 =item utf8
 
@@ -1705,13 +1765,23 @@ method.  See L<Pod::Simple> for the specific details.
 
 (F) You specified a *roff font (using C<fixed>, C<fixedbold>, etc.) that
 wasn't either one or two characters.  Pod::Man doesn't support *roff fonts
-longer than two characters, although some *roff extensions do (the canonical
-versions of B<nroff> and B<troff> don't either).
+longer than two characters, although some *roff extensions do (the
+canonical versions of B<nroff> and B<troff> don't either).
+
+=item Invalid errors setting "%s"
+
+(F) The C<errors> parameter to the constructor was set to an unknown value.
 
 =item Invalid quote specification "%s"
 
-(F) The quote specification given (the quotes option to the constructor) was
-invalid.  A quote specification must be one, two, or four characters long.
+(F) The quote specification given (the C<quotes> option to the
+constructor) was invalid.  A quote specification must be one, two, or four
+characters long.
+
+=item POD document had syntax errors
+
+(F) The POD document being formatted had syntax errors and the C<errors>
+option was set to C<die>.
 
 =back
 
@@ -1774,7 +1844,7 @@ mine).
 =head1 COPYRIGHT AND LICENSE
 
 Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
-2009, 2010, 2012 Russ Allbery <rra@stanford.edu>.
+2009, 2010, 2012, 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.
index 1a4fc12..f57256f 100644 (file)
@@ -1,11 +1,5 @@
 # Pod::Text -- Convert POD data to formatted ASCII text.
 #
-# Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012
-#     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.
-#
 # This module converts POD to formatted text.  It replaces the old Pod::Text
 # module that came with versions of Perl prior to 5.6.0 and attempts to match
 # its output except for some specific circumstances where other decisions
 # maintained outside of the Perl core as part of the podlators.  Please send
 # me any patches at the address above in addition to sending them to the
 # standard Perl mailing lists.
+#
+# Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012, 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.
 
 ##############################################################################
 # Modules and declarations
@@ -38,7 +38,7 @@ use Pod::Simple ();
 # We have to export pod2text for backward compatibility.
 @EXPORT = qw(pod2text);
 
-$VERSION = '3.16';
+$VERSION = '3.17';
 
 ##############################################################################
 # Initialization
@@ -87,11 +87,30 @@ sub new {
     %$self = (%$self, @opts);
 
     # Send errors to stderr if requested.
-    if ($$self{opt_stderr}) {
+    if ($$self{opt_stderr} and not $$self{opt_errors}) {
+        $$self{opt_errors} = 'stderr';
+    }
+    delete $$self{opt_stderr};
+
+    # Validate the errors parameter and act on it.
+    if (not defined $$self{opt_errors}) {
+        $$self{opt_errors} = 'pod';
+    }
+    if ($$self{opt_errors} eq 'stderr' || $$self{opt_errors} eq 'die') {
         $self->no_errata_section (1);
         $self->complain_stderr (1);
-        delete $$self{opt_stderr};
+        if ($$self{opt_errors} eq 'die') {
+            $$self{complain_die} = 1;
+        }
+    } elsif ($$self{opt_errors} eq 'pod') {
+        $self->no_errata_section (0);
+        $self->complain_stderr (0);
+    } elsif ($$self{opt_errors} eq 'none') {
+        $self->no_whining (1);
+    } else {
+        croak (qq(Invalid errors setting: "$$self{errors}"));
     }
+    delete $$self{errors};
 
     # Initialize various things from our parameters.
     $$self{opt_alt}      = 0  unless defined $$self{opt_alt};
@@ -315,6 +334,15 @@ sub start_document {
     return '';
 }
 
+# Handle the end of the document.  The only thing we do is handle dying on POD
+# errors, since Pod::Parser currently doesn't.
+sub end_document {
+    my ($self) = @_;
+    if ($$self{complain_die} && $self->errors_seen) {
+        croak ("POD document had syntax errors");
+    }
+}
+
 ##############################################################################
 # Text blocks
 ##############################################################################
@@ -590,6 +618,8 @@ sub cmd_l {
     if ($$attrs{type} eq 'url') {
         if (not defined($$attrs{to}) or $$attrs{to} eq $text) {
             return "<$text>";
+        } elsif ($$self{opt_nourls}) {
+            return $text;
         } else {
             return "$text <$$attrs{to}>";
         }
@@ -704,13 +734,13 @@ sub parse_file {
 1;
 __END__
 
+=for stopwords
+alt stderr Allbery Sean Burke's Christiansen UTF-8 pre-Unicode utf8 nourls
+
 =head1 NAME
 
 Pod::Text - Convert POD data to formatted ASCII text
 
-=for stopwords
-alt stderr Allbery Sean Burke's Christiansen UTF-8 pre-Unicode utf8
-
 =head1 SYNOPSIS
 
     use Pod::Text;
@@ -750,6 +780,16 @@ If set to a true value, the non-POD parts of the input file will be included
 in the output.  Useful for viewing code documented with POD blocks with the
 POD rendered and the code left intact.
 
+=item errors
+
+How to report errors.  C<die> says to throw an exception on any POD
+formatting error.  C<stderr> says to report errors on standard error, but
+not to throw an exception.  C<pod> says to include a POD ERRORS section
+in the resulting documentation summarizing the errors.  C<none> ignores
+POD errors entirely, as much as possible.
+
+The default is C<output>.
+
 =item indent
 
 The number of spaces to indent regular text, and the default indentation for
@@ -771,6 +811,22 @@ for all text, including headings, not the amount by which regular text is
 indented; for the latter, see the I<indent> option.  To set the right
 margin, see the I<width> option.
 
+=item nourls
+
+Normally, LZ<><> formatting codes with a URL but anchor text are formatted
+to show both the anchor text and the URL.  In other words:
+
+    L<foo|http://example.com/>
+
+is formatted as:
+
+    foo <http://example.com/>
+
+This option, if set to a true value, suppresses the URL when anchor text
+is given, so this example would be formatted as just C<foo>.  This can
+produce less cluttered output in cases where the URLs are not particularly
+important.
+
 =item quotes
 
 Sets the quote marks used to surround CE<lt>> text.  If the value is a
@@ -792,7 +848,9 @@ single space.  Defaults to true.
 =item stderr
 
 Send error messages about invalid POD to standard error instead of
-appending a POD ERRORS section to the generated output.
+appending a POD ERRORS section to the generated output.  This is
+equivalent to setting C<errors> to C<stderr> if C<errors> is not already
+set.  It is supported for backward compatibility.
 
 =item utf8
 
@@ -834,10 +892,20 @@ messages indicate a bug in Pod::Text; you should never see them.
 (F) Pod::Text was invoked via the compatibility mode pod2text() interface
 and the input file it was given could not be opened.
 
+=item Invalid errors setting "%s"
+
+(F) The C<errors> parameter to the constructor was set to an unknown value.
+
 =item Invalid quote specification "%s"
 
-(F) The quote specification given (the quotes option to the constructor) was
-invalid.  A quote specification must be one, two, or four characters long.
+(F) The quote specification given (the C<quotes> option to the
+constructor) was invalid.  A quote specification must be one, two, or four
+characters long.
+
+=item POD document had syntax errors
+
+(F) The POD document being formatted had syntax errors and the C<errors>
+option was set to C<die>.
 
 =back
 
@@ -895,7 +963,7 @@ how to use Pod::Simple.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012 Russ
+Copyright 1999, 2000, 2001, 2002, 2004, 2006, 2008, 2009, 2012, 2013 Russ
 Allbery <rra@stanford.edu>.
 
 This program is free software; you may redistribute it and/or modify it
index 2e88641..a114ed9 100644 (file)
@@ -1,13 +1,13 @@
 # Pod::Text::Color -- Convert POD data to formatted color ASCII text
 #
+# This is just a basic proof of concept.  It should later be modified to make
+# better use of color, take options changing what colors are used for what
+# text, and the like.
+#
 # Copyright 1999, 2001, 2004, 2006, 2008, 2009 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.
-#
-# This is just a basic proof of concept.  It should later be modified to make
-# better use of color, take options changing what colors are used for what
-# text, and the like.
 
 ##############################################################################
 # Modules and declarations
@@ -25,7 +25,7 @@ use vars qw(@ISA $VERSION);
 
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.06';
+$VERSION = '2.07';
 
 ##############################################################################
 # Overrides
index 7578f0f..f5dce02 100644 (file)
@@ -1,13 +1,5 @@
 # Pod::Text::Overstrike -- Convert POD data to formatted overstrike text
 #
-# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
-#   (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
-# Copyright 2000 Joe Smith <Joe.Smith@inwap.com>.
-# Copyright 2001, 2004, 2008 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.
-#
 # This was written because the output from:
 #
 #     pod2text Text.pm > plain.txt; less plain.txt
 #
 # and because both Pod::Text::Color and Pod::Text::Termcap are not device
 # independent.
+#
+# Created by Joe Smith <Joe.Smith@inwap.com> 30-Nov-2000
+#   (based on Pod::Text::Color by Russ Allbery <rra@stanford.edu>)
+# Copyright 2000 Joe Smith <Joe.Smith@inwap.com>.
+# Copyright 2001, 2004, 2008 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.
 
 ##############################################################################
 # Modules and declarations
@@ -34,7 +34,7 @@ use vars qw(@ISA $VERSION);
 
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.04';
+$VERSION = '2.05';
 
 ##############################################################################
 # Overrides
index e4885c9..8638060 100644 (file)
@@ -1,14 +1,14 @@
 # Pod::Text::Termcap -- Convert POD data to ASCII text with format escapes.
 #
+# This is a simple subclass of Pod::Text that overrides a few key methods to
+# output the right termcap escape sequences for formatted text on the current
+# terminal type.
+#
 # Copyright 1999, 2001, 2002, 2004, 2006, 2008, 2009
 #     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.
-#
-# This is a simple subclass of Pod::Text that overrides a few key methods to
-# output the right termcap escape sequences for formatted text on the current
-# terminal type.
 
 ##############################################################################
 # Modules and declarations
@@ -27,7 +27,7 @@ use vars qw(@ISA $VERSION);
 
 @ISA = qw(Pod::Text);
 
-$VERSION = '2.06';
+$VERSION = '2.07';
 
 ##############################################################################
 # Overrides
index 4636601..6af3474 100644 (file)
@@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!';
 
 # pod2man -- Convert POD data to formatted *roff input.
 #
-# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013
 #     Russ Allbery <rra@stanford.edu>
 #
 # This program is free software; you may redistribute it and/or modify it
@@ -62,12 +62,12 @@ my $stdin;
 # Parse our options, trying to retain backward compatibility with pod2man but
 # allowing short forms as well.  --lax is currently ignored.
 my %options;
-$options{errors} = 'pod';
 Getopt::Long::config ('bundling_override');
-GetOptions (\%options, 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s',
-            'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 'lax|l',
-            'name|n=s', 'official|o', 'quotes|q=s', 'release|r:s',
-            'section|s=s', 'stderr', 'verbose|v', 'utf8|u') or exit 1;
+GetOptions (\%options, 'center|c=s', 'date|d=s', 'errors=s', 'fixed=s',
+            'fixedbold=s', 'fixeditalic=s', 'fixedbolditalic=s', 'help|h',
+            'lax|l', 'name|n=s', 'nourls', 'official|o', 'quotes|q=s',
+            'release|r:s', 'section|s=s', 'stderr', 'verbose|v', 'utf8|u')
+    or exit 1;
 pod2usage (0) if $options{help};
 
 # Official sets --center, but don't override things explicitly set.
@@ -83,6 +83,11 @@ delete $options{verbose};
 # compatibility.
 delete $options{lax};
 
+# If neither stderr nor errors is set, default to errors = die.
+if (!defined $options{stderr} && !defined $options{errors}) {
+    $options{errors} = 'die';
+}
+
 # Initialize and run the formatter, pulling a pair of input and output off at
 # a time.  For each file, we check whether the document was completely empty
 # and, if so, will remove the created file and exit with a non-zero exit
@@ -106,20 +111,20 @@ exit $status;
 
 __END__
 
+=for stopwords
+en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
+URL troff troff-specific formatters uppercased Christiansen --nourls
+
 =head1 NAME
 
 pod2man - Convert POD data to formatted *roff input
 
-=for stopwords
-en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
-URL troff troff-specific formatters uppercased Christiansen
-
 =head1 SYNOPSIS
 
-pod2man [B<--center>=I<string>] [B<--date>=I<string>]
+pod2man [B<--center>=I<string>] [B<--date>=I<string>] [B<--errors>=I<style>]
     [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
-    [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
-    [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
+    [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--nourls>]
+    [B<--official>] [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
     [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
     [I<input> [I<output>] ...]
 
@@ -173,6 +178,16 @@ Set the left-hand footer string to this value.  By default, the modification
 date of the input file will be used, or the current date if input comes from
 C<STDIN>.
 
+=item B<-errors>=I<style>
+
+Set the error handling style.  C<die> says to throw an exception on any
+POD formatting error.  C<stderr> says to report errors on standard error,
+but not to throw an exception.  C<pod> says to include a POD ERRORS
+section in the resulting documentation summarizing the errors.  C<none>
+ignores POD errors entirely, as much as possible.
+
+The default is C<die>.
+
 =item B<--fixed>=I<font>
 
 The fixed-width font to use for verbatim text and code.  Defaults to
@@ -220,6 +235,21 @@ Note that this option is probably not useful when converting multiple POD
 files at once.  The convention for Unix man pages for commands is for the
 man page title to be in all-uppercase even if the command isn't.
 
+=item B<--nourls>
+
+Normally, LZ<><> formatting codes with a URL but anchor text are formatted
+to show both the anchor text and the URL.  In other words:
+
+    L<foo|http://example.com/>
+
+is formatted as:
+
+    foo <http://example.com/>
+
+This flag, if given, suppresses the URL when anchor text is given, so this
+example would be formatted as just C<foo>.  This can produce less
+cluttered output in cases where the URLs are not particularly important.
+
 =item B<-o>, B<--official>
 
 Set the default header to indicate that this page is part of the standard
@@ -262,10 +292,10 @@ which case section 3 will be selected.
 
 =item B<--stderr>
 
-By default, B<pod2man> puts any errors detected in the POD input in a POD
-ERRORS section in the output manual page.  If B<--stderr> is given, errors
-are sent to standard error instead and the POD ERRORS section is
-suppressed.
+By default, B<pod2man> dies if any errors are detected in the POD input.
+If B<--stderr> is given and no B<--errors> flag is present, errors are
+sent to standard error, but B<pod2man> does not abort.  This is equivalent
+to C<--errors=stderr> and is supported for backward compatibility.
 
 =item B<-u>, B<--utf8>
 
@@ -298,16 +328,17 @@ Print out the name of each output file as it is being generated.
 =head1 EXIT STATUS
 
 As long as all documents processed result in some output, even if that
-output includes errata (a C<POD ERRORS> section), B<pod2man> will exit
-with status 0.  If any of the documents being processed do not result
-in an output document, B<pod2man> will exit with status 1.
+output includes errata (a C<POD ERRORS> section generated with
+C<--errors=pod>), B<pod2man> will exit with status 0.  If any of the
+documents being processed do not result in an output document, B<pod2man>
+will exit with status 1.  If there are syntax errors in a POD document
+being processed and the error handling style is set to the default of
+C<die>, B<pod2man> will abort immediately with exit status 255.
 
 =head1 DIAGNOSTICS
 
 If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
-information about what those errors might mean.  Most POD formatting
-errors will be reported in a C<POD ERRORS> section of the generated
-document.
+information about what those errors might mean.
 
 =head1 EXAMPLES
 
@@ -352,8 +383,8 @@ B<pod2man> by Larry Wall and Tom Christiansen.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012 Russ Allbery
-<rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 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.
index 2ec28d4..f1acdbe 100644 (file)
@@ -37,7 +37,7 @@ print OUT <<'!NO!SUBS!';
 
 # pod2text -- Convert POD data to formatted ASCII text.
 #
-# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 2013
 #     Russ Allbery <rra@stanford.edu>
 #
 # This program is free software; you may redistribute it and/or modify it
@@ -78,10 +78,10 @@ my $stdin;
 my %options;
 $options{sentence} = 0;
 Getopt::Long::config ('bundling');
-GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i',
-            'loose|l', 'margin|left-margin|m=i', 'overstrike|o',
-            'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t', 'utf8|u',
-            'width|w=i')
+GetOptions (\%options, 'alt|a', 'code', 'color|c', 'errors=s', 'help|h',
+            'indent|i=i', 'loose|l', 'margin|left-margin|m=i', 'nourls',
+            'overstrike|o', 'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t',
+            'utf8|u', 'width|w=i')
     or exit 1;
 pod2usage (1) if $options{help};
 
@@ -101,6 +101,11 @@ if ($options{color}) {
 }
 delete @options{'color', 'termcap', 'overstrike'};
 
+# If neither stderr nor errors is set, default to errors = die.
+if (!defined $options{stderr} && !defined $options{errors}) {
+    $options{errors} = 'die';
+}
+
 # Initialize and run the formatter.
 my $parser = $formatter->new (%options);
 my $status = 0;
@@ -119,18 +124,19 @@ exit $status;
 
 __END__
 
+=for stopwords
+-aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8
+UTF-8 subclasses --nourls
+
 =head1 NAME
 
 pod2text - Convert POD data to formatted ASCII text
 
-=for stopwords
--aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8
-UTF-8 subclasses
-
 =head1 SYNOPSIS
 
-pod2text [B<-aclostu>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
-    [B<--stderr>] S<[B<-w> I<width>]> [I<input> [I<output> ...]]
+pod2text [B<-aclostu>] [B<--code>] [B<--errors>=I<style>] [B<-i> I<indent>]
+    S<[B<-q> I<quotes>]> [B<--nourls>] [B<--stderr>] S<[B<-w> I<width>]>
+    [I<input> [I<output> ...]]
 
 pod2text B<-h>
 
@@ -173,6 +179,16 @@ requires that Term::ANSIColor be installed on your system.
 Set the number of spaces to indent regular text, and the default indentation
 for C<=over> blocks.  Defaults to 4 spaces if this option isn't given.
 
+=item B<-errors>=I<style>
+
+Set the error handling style.  C<die> says to throw an exception on any
+POD formatting error.  C<stderr> says to report errors on standard error,
+but not to throw an exception.  C<pod> says to include a POD ERRORS
+section in the resulting documentation summarizing the errors.  C<none>
+ignores POD errors entirely, as much as possible.
+
+The default is C<die>.
+
 =item B<-h>, B<--help>
 
 Print out usage information and exit.
@@ -190,6 +206,21 @@ The width of the left margin in spaces.  Defaults to 0.  This is the margin
 for all text, including headings, not the amount by which regular text is
 indented; for the latter, see B<-i> option.
 
+=item B<--nourls>
+
+Normally, LZ<><> formatting codes with a URL but anchor text are formatted
+to show both the anchor text and the URL.  In other words:
+
+    L<foo|http://example.com/>
+
+is formatted as:
+
+    foo <http://example.com/>
+
+This flag, if given, suppresses the URL when anchor text is given, so this
+example would be formatted as just C<foo>.  This can produce less
+cluttered output in cases where the URLs are not particularly important.
+
 =item B<-o>, B<--overstrike>
 
 Format the output with overstrike printing.  Bold text is rendered as
@@ -217,10 +248,11 @@ is compressed into a single space.
 
 =item B<--stderr>
 
-By default, B<pod2text> puts any errors detected in the POD input in a POD
-ERRORS section in the output manual page.  If B<--stderr> is given, errors
-are sent to standard error instead and the POD ERRORS section is
-suppressed.
+By default, B<pod2text> dies if any errors are detected in the POD input.
+If B<--stderr> is given and no B<--errors> flag is present, errors are
+sent to standard error, but B<pod2text> does not abort.  This is
+equivalent to C<--errors=stderr> and is supported for backward
+compatibility.
 
 =item B<-t>, B<--termcap>
 
@@ -255,9 +287,12 @@ your terminal device.
 =head1 EXIT STATUS
 
 As long as all documents processed result in some output, even if that
-output includes errata (a C<POD ERRORS> section), B<pod2text> will exit
-with status 0.  If any of the documents being processed do not result
-in an output document, B<pod2text> will exit with status 1.
+output includes errata (a C<POD ERRORS> section generated with
+C<--errors=pod>), B<pod2text> will exit with status 0.  If any of the
+documents being processed do not result in an output document, B<pod2text>
+will exit with status 1.  If there are syntax errors in a POD document
+being processed and the error handling style is set to the default of
+C<die>, B<pod2text> will abort immediately with exit status 255.
 
 =head1 DIAGNOSTICS
 
@@ -281,9 +316,6 @@ loaded.
 In addition, other L<Getopt::Long> error messages may result from invalid
 command-line options.
 
-Most POD formatting errors will be reported in a C<POD ERRORS> section of
-the generated document.
-
 =head1 ENVIRONMENT
 
 =over 4
@@ -317,8 +349,8 @@ Russ Allbery <rra@stanford.edu>.
 
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012 Russ Allbery
-<rra@stanford.edu>.
+Copyright 1999, 2000, 2001, 2004, 2006, 2008, 2010, 2012, 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.
index 6b4def7..d35b88e 100644 (file)
@@ -1,8 +1,9 @@
 #!/usr/bin/perl -w
 #
-# man-options.t -- Additional tests for Pod::Man options.
+# Additional tests for Pod::Man options.
 #
-# Copyright 2002, 2004, 2006, 2008, 2009, 2012 Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 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.
@@ -18,7 +19,7 @@ BEGIN {
 
 use strict;
 
-use Test::More tests => 10;
+use Test::More tests => 25;
 BEGIN { use_ok ('Pod::Man') }
 
 # Redirect stderr to a file.
@@ -53,7 +54,8 @@ while (<DATA>) {
     isa_ok ($parser, 'Pod::Man', 'Parser object');
     open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
     stderr_save;
-    $parser->parse_from_file ("tmp$$.pod", \*OUT);
+    eval { $parser->parse_from_file ("tmp$$.pod", \*OUT) };
+    my $exception = $@;
     stderr_restore;
     close OUT;
     my $accents = 0;
@@ -83,6 +85,10 @@ while (<DATA>) {
     close ERR;
     $errors =~ s/\Qtmp$$.pod/tmp.pod/g;
     1 while unlink ("out$$.err");
+    if ($exception) {
+        $exception =~ s/ at .*//;
+        $errors .= "EXCEPTION: $exception";
+    }
     $expected = '';
     while (<DATA>) {
         last if $_ eq "###\n";
@@ -158,3 +164,101 @@ Bar.
 ###
 tmp.pod around line 7: You forgot a '=back' before '=head1'
 ###
+
+###
+nourls 1
+###
+=head1 URL suppression
+
+L<anchor|http://www.example.com/>
+###
+.SH "URL suppression"
+.IX Header "URL suppression"
+anchor
+###
+###
+
+###
+errors stderr
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+tmp.pod around line 7: You forgot a '=back' before '=head1'
+###
+
+###
+errors die
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+tmp.pod around line 7: You forgot a '=back' before '=head1'
+EXCEPTION: POD document had syntax errors
+###
+
+###
+errors pod
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+.SH "POD ERRORS"
+.IX Header "POD ERRORS"
+Hey! \fBThe above document had some coding errors, which are explained below:\fR
+.IP "Around line 7:" 4
+.IX Item "Around line 7:"
+You forgot a '=back' before '=head1'
+###
+###
+
+###
+errors none
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+.IP "Foo" 4
+.IX Item "Foo"
+Bar.
+.SH "NEXT"
+.IX Header "NEXT"
+###
+###
index 3a07e80..f8a391e 100644 (file)
@@ -1,8 +1,8 @@
 #!/usr/bin/perl -w
 #
-# man.t -- Additional specialized tests for Pod::Man.
+# Additional specialized tests for Pod::Man.
 #
-# Copyright 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2012
+# Copyright 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2012, 2013
 #     Russ Allbery <rra@stanford.edu>
 #
 # This program is free software; you may redistribute it and/or modify it
@@ -19,7 +19,7 @@ BEGIN {
 
 use strict;
 
-use Test::More tests => 33;
+use Test::More tests => 35;
 BEGIN { use_ok ('Pod::Man') }
 
 # Test whether we can use binmode to set encoding.
@@ -499,7 +499,7 @@ This is a L<link|http://www.example.com/> to a URL.
 ###
 .SH "LINK TO URL"
 .IX Header "LINK TO URL"
-This is a link <http://www.example.com/> to a \s-1URL\s0.
+This is a link <http://www.example.com/> to a \s-1URL.\s0
 ###
 
 ###
@@ -550,3 +550,37 @@ L<[perl #12345]|https://rt.cpan.org/12345>
 .IX Header "RT LINK"
 [perl #12345] <https://rt.cpan.org/12345>
 ###
+
+###
+=head1 Multiline XZ<><>
+
+Something something X<this   is
+one index term>
+###
+.SH "Multiline X<>"
+.IX Header "Multiline X<>"
+Something something
+.IX Xref "this is one index term"
+###
+
+###
+=head1 Uppercase License
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+###
+.SH "Uppercase License"
+.IX Header "Uppercase License"
+\&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\s0
+###
index e49b746..06bf081 100644 (file)
@@ -1,8 +1,9 @@
 #!/usr/bin/perl -w
 #
-# text-options.t -- Additional tests for Pod::Text options.
+# Additional tests for Pod::Text options.
 #
-# Copyright 2002, 2004, 2006, 2008, 2009, 2012 Russ Allbery <rra@stanford.edu>
+# Copyright 2002, 2004, 2006, 2008, 2009, 2012, 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.
@@ -18,7 +19,7 @@ BEGIN {
 
 use strict;
 
-use Test::More tests => 19;
+use Test::More tests => 34;
 BEGIN { use_ok ('Pod::Text') }
 
 # Redirect stderr to a file.
@@ -53,7 +54,8 @@ while (<DATA>) {
     isa_ok ($parser, 'Pod::Text', 'Parser object');
     open (OUT, "> out$$.tmp") or die "Cannot create out$$.tmp: $!\n";
     stderr_save;
-    $parser->parse_from_file ("tmp$$.pod", \*OUT);
+    eval { $parser->parse_from_file ("tmp$$.pod", \*OUT) };
+    my $exception = $@;
     stderr_restore;
     close OUT;
     open (TMP, "out$$.tmp") or die "Cannot open out$$.tmp: $!\n";
@@ -79,6 +81,10 @@ while (<DATA>) {
     close ERR;
     $errors =~ s/\Qtmp$$.pod/tmp.pod/g;
     1 while unlink ("out$$.err");
+    if ($exception) {
+        $exception =~ s/ at .*//;
+        $errors .= "EXCEPTION: $exception";
+    }
     $expected = '';
     while (<DATA>) {
         last if $_ eq "###\n";
@@ -254,3 +260,94 @@ NEXT
 ###
 tmp.pod around line 7: You forgot a '=back' before '=head1'
 ###
+
+###
+nourls 1
+###
+=head1 URL suppression
+
+L<anchor|http://www.example.com/>
+###
+URL suppression
+    anchor
+
+###
+###
+
+###
+errors stderr
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+    Foo Bar.
+
+NEXT
+###
+tmp.pod around line 7: You forgot a '=back' before '=head1'
+###
+
+###
+errors die
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+    Foo Bar.
+
+NEXT
+###
+tmp.pod around line 7: You forgot a '=back' before '=head1'
+EXCEPTION: POD document had syntax errors
+###
+
+###
+errors pod
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+    Foo Bar.
+
+NEXT
+POD ERRORS
+    Hey! The above document had some coding errors, which are explained
+    below:
+
+    Around line 7:
+        You forgot a '=back' before '=head1'
+
+###
+###
+
+###
+errors none
+###
+=over 4
+
+=item Foo
+
+Bar.
+
+=head1 NEXT
+###
+    Foo Bar.
+
+NEXT
+###
+###