diff options
Diffstat (limited to 'cpan/podlators/lib/Pod/Text.pm')
| -rw-r--r-- | cpan/podlators/lib/Pod/Text.pm | 100 |
1 files changed, 84 insertions, 16 deletions
diff --git a/cpan/podlators/lib/Pod/Text.pm b/cpan/podlators/lib/Pod/Text.pm index 1a4fc129aa..f57256f2d9 100644 --- a/cpan/podlators/lib/Pod/Text.pm +++ b/cpan/podlators/lib/Pod/Text.pm @@ -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 @@ -16,6 +10,12 @@ # 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 |