summaryrefslogtreecommitdiff
path: root/systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm
diff options
context:
space:
mode:
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm')
-rw-r--r--systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm561
1 files changed, 392 insertions, 169 deletions
diff --git a/systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm b/systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm
index 56e6e78a86..83a7ce22a8 100644
--- a/systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm
+++ b/systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm
@@ -14,23 +14,20 @@
package Pod::Text;
-use 5.008;
+use 5.010;
use strict;
use warnings;
-use vars qw(@ISA @EXPORT %ESCAPES $VERSION);
-
use Carp qw(carp croak);
use Encode qw(encode);
use Exporter ();
use Pod::Simple ();
-@ISA = qw(Pod::Simple Exporter);
+our @ISA = qw(Pod::Simple Exporter);
+our $VERSION = '5.01';
# We have to export pod2text for backward compatibility.
-@EXPORT = qw(pod2text);
-
-$VERSION = '4.14';
+our @EXPORT = qw(pod2text);
# Ensure that $Pod::Simple::nbsp and $Pod::Simple::shy are available. Code
# taken from Pod::Simple 3.32, but was only added in 3.30.
@@ -43,6 +40,11 @@ if ($Pod::Simple::VERSION ge 3.30) {
$SHY = chr utf8::unicode_to_native(0xAD);
}
+# Import the ASCII constant from Pod::Simple. This is true iff we're in an
+# ASCII-based universe (including such things as ISO 8859-1 and UTF-8), and is
+# generally only false for EBCDIC.
+BEGIN { *ASCII = \&Pod::Simple::ASCII }
+
##############################################################################
# Initialization
##############################################################################
@@ -64,9 +66,6 @@ sub new {
my $class = shift;
my $self = $class->SUPER::new;
- # Tell Pod::Simple to handle S<> by automatically inserting &nbsp;.
- $self->nbsp_for_S (1);
-
# Tell Pod::Simple to keep whitespace whenever possible.
if ($self->can ('preserve_whitespace')) {
$self->preserve_whitespace (1);
@@ -89,16 +88,20 @@ sub new {
my @opts = map { ("opt_$_", $opts{$_}) } keys %opts;
%$self = (%$self, @opts);
- # Send errors to stderr if requested.
+ # Backwards-compatibility support for the stderr option.
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';
+ # Backwards-compatibility support for the utf8 option.
+ if ($$self{opt_utf8} && !$$self{opt_encoding}) {
+ $$self{opt_encoding} = 'UTF-8';
}
+ delete $$self{opt_utf8};
+
+ # Validate the errors parameter and act on it.
+ $$self{opt_errors} //= 'pod';
if ($$self{opt_errors} eq 'stderr' || $$self{opt_errors} eq 'die') {
$self->no_errata_section (1);
$self->complain_stderr (1);
@@ -117,12 +120,12 @@ sub new {
delete $$self{errors};
# Initialize various things from our parameters.
- $$self{opt_alt} = 0 unless defined $$self{opt_alt};
- $$self{opt_indent} = 4 unless defined $$self{opt_indent};
- $$self{opt_margin} = 0 unless defined $$self{opt_margin};
- $$self{opt_loose} = 0 unless defined $$self{opt_loose};
- $$self{opt_sentence} = 0 unless defined $$self{opt_sentence};
- $$self{opt_width} = 76 unless defined $$self{opt_width};
+ $$self{opt_alt} //= 0;
+ $$self{opt_indent} //= 4;
+ $$self{opt_margin} //= 0;
+ $$self{opt_loose} //= 0;
+ $$self{opt_sentence} //= 0;
+ $$self{opt_width} //= 76;
# Figure out what quotes we'll be using for C<> text.
$$self{opt_quotes} ||= '"';
@@ -138,6 +141,17 @@ sub new {
croak qq(Invalid quote specification "$$self{opt_quotes}");
}
+ # Configure guesswork based on options.
+ my $guesswork = $self->{opt_guesswork} || q{};
+ my %guesswork = map { $_ => 1 } split(m{,}xms, $guesswork);
+ if (!%guesswork || $guesswork{all}) {
+ $$self{GUESSWORK} = {quoting => 1};
+ } elsif ($guesswork{none}) {
+ $$self{GUESSWORK} = {};
+ } else {
+ $$self{GUESSWORK} = {%guesswork};
+ }
+
# If requested, do something with the non-POD text.
$self->code_handler (\&handle_code) if $$self{opt_code};
@@ -272,9 +286,7 @@ sub reformat {
}
# Output text to the output device. Replace non-breaking spaces with spaces
-# and soft hyphens with nothing, and then try to fix the output encoding if
-# necessary to match the input encoding unless UTF-8 output is forced. This
-# preserves the traditional pass-through behavior of Pod::Text.
+# and soft hyphens with nothing, and then determine the output encoding.
sub output {
my ($self, @text) = @_;
my $text = join ('', @text);
@@ -284,15 +296,39 @@ sub output {
if ($SHY) {
$text =~ s/$SHY//g;
}
- unless ($$self{opt_utf8}) {
- my $encoding = $$self{encoding} || '';
- if ($encoding && $encoding ne $$self{ENCODING}) {
- $$self{ENCODING} = $encoding;
- eval { binmode ($$self{output_fh}, ":encoding($encoding)") };
- }
- }
+
+ # The logic used here is described in the POD documentation. Prefer the
+ # configured encoding, then the pass-through option of using the same
+ # encoding as the input, and then UTF-8, but commit to an encoding for the
+ # document.
+ #
+ # ENCODE says whether to encode or not and is turned off if there is a
+ # PerlIO encoding layer (in start_document). ENCODING is the encoding
+ # that we previously committed to and is cleared at the start of each
+ # document.
if ($$self{ENCODE}) {
- print { $$self{output_fh} } encode ('UTF-8', $text);
+ my $encoding = $$self{ENCODING};
+ if (!$encoding) {
+ $encoding = $self->encoding();
+ if (!$encoding && ASCII && $text =~ /[^\x00-\x7F]/) {
+ $encoding = 'UTF-8';
+ }
+ if ($encoding) {
+ $$self{ENCODING} = $encoding;
+ }
+ }
+ if ($encoding) {
+ my $check = sub {
+ my ($char) = @_;
+ my $display = '"\x{' . hex($char) . '}"';
+ my $error = "$display does not map to $$self{ENCODING}";
+ $self->whine ($self->line_count(), $error);
+ return Encode::encode ($$self{ENCODING}, chr($char));
+ };
+ print { $$self{output_fh} } encode ($encoding, $text, $check);
+ } else {
+ print { $$self{output_fh} } $text;
+ }
} else {
print { $$self{output_fh} } $text;
}
@@ -322,24 +358,18 @@ sub start_document {
$$self{MARGIN} = $margin; # Default left margin.
$$self{PENDING} = [[]]; # Pending output.
- # We have to redo encoding handling for each document.
- $$self{ENCODING} = '';
-
- # When UTF-8 output is set, check whether our output file handle already
- # has a PerlIO encoding layer set. If it does not, we'll need to encode
- # our output before printing it (handled in the output() sub).
- $$self{ENCODE} = 0;
- if ($$self{opt_utf8}) {
- $$self{ENCODE} = 1;
- eval {
- my @options = (output => 1, details => 1);
- my $flag = (PerlIO::get_layers ($$self{output_fh}, @options))[-1];
- if ($flag && ($flag & PerlIO::F_UTF8 ())) {
- $$self{ENCODE} = 0;
- $$self{ENCODING} = 'UTF-8';
- }
- };
- }
+ # We have to redo encoding handling for each document. Check whether the
+ # output file handle already has a PerlIO encoding layer set and, if so,
+ # disable encoding.
+ $$self{ENCODE} = 1;
+ eval {
+ my @options = (output => 1, details => 1);
+ my $flag = (PerlIO::get_layers ($$self{output_fh}, @options))[-1];
+ if ($flag && ($flag & PerlIO::F_UTF8 ())) {
+ $$self{ENCODE} = 0;
+ }
+ };
+ $$self{ENCODING} = $$self{opt_encoding};
return '';
}
@@ -383,8 +413,7 @@ sub item {
# Calculate the indentation and margin. $fits is set to true if the tag
# will fit into the margin of the paragraph given our indentation level.
- my $indent = $$self{INDENTS}[-1];
- $indent = $$self{opt_indent} unless defined $indent;
+ my $indent = $$self{INDENTS}[-1] // $$self{opt_indent};
my $margin = ' ' x $$self{opt_margin};
my $tag_length = length ($self->strip_format ($tag));
my $fits = ($$self{MARGIN} - $indent >= $tag_length + 1);
@@ -588,6 +617,13 @@ sub cmd_f { return $_[0]{alt} ? "\"$_[2]\"" : $_[2] }
sub cmd_i { return '*' . $_[2] . '*' }
sub cmd_x { return '' }
+# Convert all internal whitespace to $NBSP.
+sub cmd_s {
+ my ($self, $attrs, $text) = @_;
+ $text =~ s{ \s }{$NBSP}xmsg;
+ return $text;
+}
+
# Apply a whole bunch of messy heuristics to not quote things that don't
# benefit from being quoted. These originally come from Barrie Slaymaker and
# largely duplicate code in Pod::Man.
@@ -597,23 +633,35 @@ sub cmd_c {
# A regex that matches the portion of a variable reference that's the
# array or hash index, separated out just because we want to use it in
# several places in the following regex.
- my $index = '(?: \[.*\] | \{.*\} )?';
+ my $index = '(?: \[[^]]+\] | \{[^}]+\} )?';
# Check for things that we don't want to quote, and if we find any of
# them, return the string with just a font change and no quoting.
+ #
+ # Traditionally, Pod::Text has not quoted Perl variables, functions,
+ # numbers, or hex constants, but this is not always desirable. Make this
+ # optional on the quoting guesswork flag.
+ my $extra = qr{(?!)}xms; # never matches
+ if ($$self{GUESSWORK}{quoting}) {
+ $extra = qr{
+ \$+ [\#^]? \S $index # special ($^F, $")
+ | [\$\@%&*]+ \#? [:\'\w]+ $index # plain var or func
+ | [\$\@%&*]* [:\'\w]+
+ (?: -> )? \(\s*[^\s,\)]*\s*\) # 0/1-arg func call
+ | [+-]? ( \d[\d.]* | \.\d+ )
+ (?: [eE][+-]?\d+ )? # a number
+ | 0x [a-fA-F\d]+ # a hex constant
+ }xms;
+ }
$text =~ m{
^\s*
(?:
- ( [\'\`\"] ) .* \1 # already quoted
- | \` .* \' # `quoted'
- | \$+ [\#^]? \S $index # special ($^Foo, $")
- | [\$\@%&*]+ \#? [:\'\w]+ $index # plain var or func
- | [\$\@%&*]* [:\'\w]+ (?: -> )? \(\s*[^\s,]\s*\) # 0/1-arg func call
- | [+-]? ( \d[\d.]* | \.\d+ ) (?: [eE][+-]?\d+ )? # a number
- | 0x [a-fA-F\d]+ # a hex constant
+ ( [\'\`\"] ) .* \1 # already quoted
+ | \` .* \' # `quoted'
+ | $extra
)
\s*\z
- }xo && return $text;
+ }xms and return $text;
# If we didn't return, go ahead and quote the text.
return $$self{opt_alt}
@@ -766,7 +814,7 @@ __END__
=for stopwords
alt stderr Allbery Sean Burke's Christiansen UTF-8 pre-Unicode utf8 nourls
-parsers
+parsers EBCDIC autodetecting superset unrepresentable FH NNN
=head1 NAME
@@ -785,67 +833,180 @@ Pod::Text - Convert POD data to formatted text
=head1 DESCRIPTION
-Pod::Text is a module that can convert documentation in the POD format
-(the preferred language for documenting Perl) into formatted text. It
-uses no special formatting controls or codes whatsoever, and its output is
-therefore suitable for nearly any device.
+Pod::Text is a module that can convert documentation in the POD format (the
+preferred language for documenting Perl) into formatted text. It uses no
+special formatting controls or codes, and its output is therefore suitable for
+nearly any device.
-As a derived class from Pod::Simple, Pod::Text supports the same methods and
-interfaces. See L<Pod::Simple> for all the details; briefly, one creates a
-new parser with C<< Pod::Text->new() >> and then normally calls parse_file().
+=head2 Encoding
-new() can take options, in the form of key/value pairs, that control the
-behavior of the parser. The currently recognized options are:
+Pod::Text uses the following logic to choose an output encoding, in order:
+
+=over 4
+
+=item 1.
+
+If a PerlIO encoding layer is set on the output file handle, do not do any
+output encoding and will instead rely on the PerlIO encoding layer.
+
+=item 2.
+
+If the C<encoding> or C<utf8> options are set, use the output encoding
+specified by those options.
+
+=item 3.
+
+If the input encoding of the POD source file was explicitly specified (using
+C<=encoding>) or automatically detected by Pod::Simple, use that as the output
+encoding as well.
+
+=item 4.
+
+Otherwise, if running on a non-EBCDIC system, use UTF-8 as the output
+encoding. Since this is a superset of ASCII, this will result in ASCII output
+unless the POD input contains non-ASCII characters without declaring or
+autodetecting an encoding (usually via EZ<><> escapes).
+
+=item 5.
+
+Otherwise, for EBCDIC systems, output without doing any encoding and hope
+this works.
+
+=back
+
+One caveat: Pod::Text has to commit to an output encoding the first time it
+outputs a non-ASCII character, and then has to stick with it for consistency.
+However, C<=encoding> commands don't have to be at the beginning of a POD
+document. If someone uses a non-ASCII character early in a document with an
+escape, such as EZ<><0xEF>, and then puts C<=encoding iso-8859-1> later,
+ideally Pod::Text would follow rule 3 and output the entire document as ISO
+8859-1. Instead, it will commit to UTF-8 following rule 4 as soon as it sees
+that escape, and then stick with that encoding for the rest of the document.
+
+Unfortunately, there's no universally good choice for an output encoding.
+Each choice will be incorrect in some circumstances. This approach was chosen
+primarily for backwards compatibility. Callers should consider forcing the
+output encoding via C<encoding> if they have any knowledge about what encoding
+the user may expect.
+
+In particular, consider importing the L<Encode::Locale> module, if available,
+and setting C<encoding> to C<locale> to use an output encoding appropriate to
+the user's locale. But be aware that if the user is not using locales or is
+using a locale of C<C>, Encode::Locale will set the output encoding to
+US-ASCII. This will cause all non-ASCII characters will be replaced with C<?>
+and produce a flurry of warnings about unsupported characters, which may or
+may not be what you want.
+
+=head1 CLASS METHODS
+
+=over 4
+
+=item new(ARGS)
+
+Create a new Pod::Text object. ARGS should be a list of key/value pairs,
+where the keys are chosen from the following. Each option is annotated with
+the version of Pod::Text in which that option was added with its current
+meaning.
=over 4
=item alt
-If set to a true value, selects an alternate output format that, among other
-things, uses a different heading style and marks C<=item> entries with a
+[2.00] If set to a true value, selects an alternate output format that, among
+other things, uses a different heading style and marks C<=item> entries with a
colon in the left margin. Defaults to false.
=item code
-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.
+[2.13] 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 encoding
+
+[5.00] Specifies the encoding of the output. The value must be an encoding
+recognized by the L<Encode> module (see L<Encode::Supported>). If the output
+contains characters that cannot be represented in this encoding, that is an
+error that will be reported as configured by the C<errors> option. If error
+handling is other than C<die>, the unrepresentable character will be replaced
+with the Encode substitution character (normally C<?>).
+
+If the output file handle has a PerlIO encoding layer set, this parameter will
+be ignored and no encoding will be done by Pod::Man. It will instead rely on
+the encoding layer to make whatever output encoding transformations are
+desired.
+
+WARNING: The input encoding of the POD source is independent from the output
+encoding, and setting this option does not affect the interpretation of the
+POD input. Unless your POD source is US-ASCII, its encoding should be
+declared with the C<=encoding> command in the source, as near to the top of
+the file as possible. If this is not done, Pod::Simple will will attempt to
+guess the encoding and may be successful if it's Latin-1 or UTF-8, but it will
+produce warnings. See L<perlpod(1)> for more information.
=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.
+[3.17] 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<pod>.
+=item guesswork
+
+[5.01] By default, Pod::Text applies some default formatting rules based on
+guesswork and regular expressions that are intended to make writing Perl
+documentation easier and require less explicit markup. These rules may not
+always be appropriate, particularly for documentation that isn't about Perl.
+This option allows turning all or some of it off.
+
+The special value C<all> enables all guesswork. This is also the default for
+backward compatibility reasons. The special value C<none> disables all
+guesswork. Otherwise, the value of this option should be a comma-separated
+list of one or more of the following keywords:
+
+=over 4
+
+=item quoting
+
+If no guesswork is enabled, any text enclosed in CZ<><> is surrounded by
+double quotes in nroff (terminal) output unless the contents are already
+quoted. When this guesswork is enabled, quote marks will also be suppressed
+for Perl variables, function names, function calls, numbers, and hex
+constants.
+
+=back
+
+Any unknown guesswork name is silently ignored (for potential future
+compatibility), so be careful about spelling.
+
=item indent
-The number of spaces to indent regular text, and the default indentation for
-C<=over> blocks. Defaults to 4.
+[2.00] The number of spaces to indent regular text, and the default
+indentation for C<=over> blocks. Defaults to 4.
=item loose
-If set to a true value, a blank line is printed after a C<=head1> heading.
-If set to false (the default), no blank line is printed after C<=head1>,
-although one is still printed after C<=head2>. This is the default because
-it's the expected formatting for manual pages; if you're formatting
+[2.00] If set to a true value, a blank line is printed after a C<=head1>
+heading. If set to false (the default), no blank line is printed after
+C<=head1>, although one is still printed after C<=head2>. This is the default
+because it's the expected formatting for manual pages; if you're formatting
arbitrary text documents, setting this to true may result in more pleasing
output.
=item margin
-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 the I<indent> option. To set the right
+[2.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 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:
+[3.17] 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/>
@@ -853,74 +1014,131 @@ 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.
+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
-single character, it is used as both the left and right quote. Otherwise,
-it is split in half, and the first half of the string is used as the left
-quote and the second is used as the right quote.
+[4.00] Sets the quote marks used to surround CE<lt>> text. If the value is a
+single character, it is used as both the left and right quote. Otherwise, it
+is split in half, and the first half of the string is used as the left quote
+and the second is used as the right quote.
This may also be set to the special value C<none>, in which case no quote
marks are added around CE<lt>> text.
=item sentence
-If set to a true value, Pod::Text will assume that each sentence ends in two
-spaces, and will try to preserve that spacing. If set to false, all
-consecutive whitespace in non-verbatim paragraphs is compressed into a
-single space. Defaults to false.
+[3.00] If set to a true value, Pod::Text will assume that each sentence ends
+in two spaces, and will try to preserve that spacing. If set to false, all
+consecutive whitespace in non-verbatim paragraphs is compressed into a single
+space. Defaults to false.
=item stderr
-Send error messages about invalid POD to standard error instead of
-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.
+[3.10] Send error messages about invalid POD to standard error instead of
+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
-By default, Pod::Text uses the same output encoding as the input encoding
-of the POD source (provided that Perl was built with PerlIO; otherwise, it
-doesn't encode its output). If this option is given, the output encoding
-is forced to UTF-8.
-
-Be aware that, when using this option, the input encoding of your POD
-source should be properly declared unless it's US-ASCII. Pod::Simple will
-attempt to guess the encoding and may be successful if it's Latin-1 or
-UTF-8, but it will produce warnings. Use the C<=encoding> command to
-declare the encoding. See L<perlpod(1)> for more information.
+[3.12] If this option is set to a true value, the output encoding is set to
+UTF-8. This is equivalent to setting C<encoding> to C<UTF-8> if C<encoding>
+is not already set. It is supported for backward compatibility.
=item width
-The column at which to wrap text on the right-hand side. Defaults to 76.
+[2.00] The column at which to wrap text on the right-hand side. Defaults to
+76.
+
+=back
+
+=back
+
+=head1 INSTANCE METHODS
+
+As a derived class from Pod::Simple, Pod::Text supports the same methods and
+interfaces. See L<Pod::Simple> for all the details. This section summarizes
+the most-frequently-used methods and the ones added by Pod::Text.
+
+=over 4
+
+=item output_fh(FH)
+
+Direct the output from parse_file(), parse_lines(), or parse_string_document()
+to the file handle FH instead of C<STDOUT>.
+
+=item output_string(REF)
+
+Direct the output from parse_file(), parse_lines(), or parse_string_document()
+to the scalar variable pointed to by REF, rather than C<STDOUT>. For example:
+
+ my $man = Pod::Man->new();
+ my $output;
+ $man->output_string(\$output);
+ $man->parse_file('/some/input/file');
+
+Be aware that the output in that variable will already be encoded (see
+L</Encoding>).
+
+=item parse_file(PATH)
+
+Read the POD source from PATH and format it. By default, the output is sent
+to C<STDOUT>, but this can be changed with the output_fh() or output_string()
+methods.
+
+=item parse_from_file(INPUT, OUTPUT)
+
+=item parse_from_filehandle(FH, OUTPUT)
+
+Read the POD source from INPUT, format it, and output the results to OUTPUT.
+
+parse_from_filehandle() is provided for backward compatibility with older
+versions of Pod::Man. parse_from_file() should be used instead.
+
+=item parse_lines(LINES[, ...[, undef]])
+
+Parse the provided lines as POD source, writing the output to either C<STDOUT>
+or the file handle set with the output_fh() or output_string() methods. This
+method can be called repeatedly to provide more input lines. An explicit
+C<undef> should be passed to indicate the end of input.
+
+This method expects raw bytes, not decoded characters.
+
+=item parse_string_document(INPUT)
+
+Parse the provided scalar variable as POD source, writing the output to either
+C<STDOUT> or the file handle set with the output_fh() or output_string()
+methods.
+
+This method expects raw bytes, not decoded characters.
=back
-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.
+=head1 FUNCTIONS
-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.
+Pod::Text exports one function for backward compatibility with older versions.
+This function is deprecated; instead, use the object-oriented interface
+described above.
-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. Be
-aware that parse_lines() and parse_string_document() both expect raw bytes,
-not decoded characters.
+=over 4
+
+=item pod2text([[-a,] [-NNN,]] INPUT[, OUTPUT])
+
+Convert the POD source from INPUT to text and write it to OUTPUT. If OUTPUT
+is not given, defaults to C<STDOUT>. INPUT can be any expression supported as
+the second argument to two-argument open().
-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().
+If C<-a> is given as an initial argument, pass the C<alt> option to the
+Pod::Text constructor. This enables alternative formatting.
-See L<Pod::Simple> for more specific details on the methods available to
-all derived parsers.
+If C<-NNN> is given as an initial argument, pass the C<width> option to the
+Pod::Text constructor with the number C<NNN> as its argument. This sets the
+wrap line width to NNN.
+
+=back
=head1 DIAGNOSTICS
@@ -955,61 +1173,66 @@ option was set to C<die>.
=back
-=head1 BUGS
+=head1 COMPATIBILITY
-Encoding handling assumes that PerlIO is available and does not work
-properly if it isn't. The C<utf8> option is therefore not supported
-unless Perl is built with PerlIO support.
+Pod::Text 2.03 (based on L<Pod::Parser>) was the first version of this module
+included with Perl, in Perl 5.6.0. Earlier versions of Perl had a different
+Pod::Text module, with a different API.
-=head1 CAVEATS
+The current API based on L<Pod::Simple> was added in Pod::Text 3.00.
+Pod::Text 3.01 was included in Perl 5.9.3, the first version of Perl to
+incorporate those changes. This is the first version that correctly supports
+all modern POD syntax. The parse_from_filehandle() method was re-added for
+backward compatibility in Pod::Text 3.07, included in Perl 5.9.4.
-If Pod::Text is given the C<utf8> option, the encoding of its output file
-handle will be forced to UTF-8 if possible, overriding any existing
-encoding. This will be done even if the file handle is not created by
-Pod::Text and was passed in from outside. This maintains consistency
-regardless of PERL_UNICODE and other settings.
+Pod::Text 3.12, included in Perl 5.10.1, first implemented the current
+practice of attempting to match the default output encoding with the input
+encoding of the POD source, unless overridden by the C<utf8> option or (added
+later) the C<encoding> option.
-If the C<utf8> option is not given, the encoding of its output file handle
-will be forced to the detected encoding of the input POD, which preserves
-whatever the input text is. This ensures backward compatibility with
-earlier, pre-Unicode versions of this module, without large numbers of
-Perl warnings.
+Support for anchor text in LZ<><> links of type URL was added in Pod::Text
+3.14, included in Perl 5.11.5.
-This is not ideal, but it seems to be the best compromise. If it doesn't
-work for you, please let me know the details of how it broke.
+parse_lines(), parse_string_document(), and parse_file() set a default output
+file handle of C<STDOUT> if one was not already set as of Pod::Text 3.18,
+included in Perl 5.19.5.
-=head1 NOTES
+Pod::Text 4.00, included in Perl 5.23.7, aligned the module version and the
+version of the podlators distribution. All modules included in podlators, and
+the podlators distribution itself, share the same version number from this
+point forward.
-This is a replacement for an earlier Pod::Text module written by Tom
-Christiansen. It has a revamped interface, since it now uses Pod::Simple,
-but an interface roughly compatible with the old Pod::Text::pod2text()
-function is still available. Please change to the new calling convention,
-though.
+Pod::Text 4.09, included in Perl 5.25.7, fixed a serious bug on EBCDIC
+systems, present in all versions back to 3.00, that would cause opening
+brackets to disappear.
-The original Pod::Text contained code to do formatting via termcap
-sequences, although it wasn't turned on by default and it was problematic to
-get it to work at all. This rewrite doesn't even try to do that, but a
-subclass of it does. Look for L<Pod::Text::Termcap>.
+Pod::Text 5.00 now defaults, on non-EBCDIC systems, to UTF-8 encoding if it
+sees a non-ASCII character in the input and the input encoding is not
+specified. It also commits to an encoding with the first non-ASCII character
+and does not change the output encoding if the input encoding changes. The
+L<Encode> module is now used for all output encoding rather than PerlIO
+layers, which fixes earlier problems with output to scalars.
=head1 AUTHOR
-Russ Allbery <rra@cpan.org>, based I<very> heavily on the original
-Pod::Text by Tom Christiansen <tchrist@mox.perl.com> and its conversion to
-Pod::Parser by Brad Appleton <bradapp@enteract.com>. Sean Burke's initial
-conversion of Pod::Man to use Pod::Simple provided much-needed guidance on
-how to use Pod::Simple.
+Russ Allbery <rra@cpan.org>, based I<very> heavily on the original Pod::Text
+by Tom Christiansen <tchrist@mox.perl.com> and its conversion to Pod::Parser
+by Brad Appleton <bradapp@enteract.com>. Sean Burke's initial conversion of
+Pod::Man to use Pod::Simple provided much-needed guidance on how to use
+Pod::Simple.
=head1 COPYRIGHT AND LICENSE
-Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019 Russ Allbery
-<rra@cpan.org>
+Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022 Russ
+Allbery <rra@cpan.org>
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
=head1 SEE ALSO
-L<Pod::Simple>, L<Pod::Text::Termcap>, L<perlpod(1)>, L<pod2text(1)>
+L<Encode::Locale>, L<Encode::Supproted>, L<Pod::Simple>,
+L<Pod::Text::Termcap>, L<perlpod(1)>, L<pod2text(1)>
The current version of this module is always available from its web site at
L<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the