diff options
Diffstat (limited to 'systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm')
-rw-r--r-- | systems/texlive/tlnet/tlpkg/tlperl/lib/Pod/Text.pm | 561 |
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 . - $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 |