-$VERSION = '2.4.2';
+$VERSION = '2.5.0';
# 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
@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
%$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;
# 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;
# 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");
$$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;
}
# 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') {
}
if (not defined ($to) or $to eq $text) {
return "<$text>";
+ } elsif ($$self{nourls}) {
+ return $text;
} else {
return "$text <$$attrs{to}>";
}
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
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
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
=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
(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
=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.
# 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
# We have to export pod2text for backward compatibility.
@EXPORT = qw(pod2text);
-$VERSION = '3.16';
+$VERSION = '3.17';
##############################################################################
# Initialization
%$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};
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
##############################################################################
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}>";
}
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;
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
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
=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
(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
=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
# 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
@ISA = qw(Pod::Text);
-$VERSION = '2.06';
+$VERSION = '2.07';
##############################################################################
# Overrides
# 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
@ISA = qw(Pod::Text);
-$VERSION = '2.04';
+$VERSION = '2.05';
##############################################################################
# Overrides
# 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
@ISA = qw(Pod::Text);
-$VERSION = '2.06';
+$VERSION = '2.07';
##############################################################################
# Overrides
# 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
# 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.
# 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
__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>] ...]
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
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
=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>
=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
=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.
# 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
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};
}
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;
__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>
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.
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
=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>
=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
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
=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.
#!/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.
use strict;
-use Test::More tests => 10;
+use Test::More tests => 25;
BEGIN { use_ok ('Pod::Man') }
# Redirect stderr to a file.
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;
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";
###
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"
+###
+###
#!/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
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.
###
.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
###
###
.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
+###
#!/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.
use strict;
-use Test::More tests => 19;
+use Test::More tests => 34;
BEGIN { use_ok ('Pod::Text') }
# Redirect stderr to a file.
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";
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";
###
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
+###
+###
projects / perl.git / commitdiff
