path: root/upstream/debian-unstable/man3/Pod::Text.3perl

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pod::Text 3perl"
.TH Pod::Text 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Pod::Text \- Convert POD data to formatted text
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use Pod::Text;
\&    my $parser = Pod::Text\->new (sentence => 1, width => 78);
\&
\&    # Read POD from STDIN and write to STDOUT.
\&    $parser\->parse_from_filehandle;
\&
\&    # Read POD from file.pod and write to file.txt.
\&    $parser\->parse_from_file (\*(Aqfile.pod\*(Aq, \*(Aqfile.txt\*(Aq);
.Ve
.SH DESCRIPTION
.IX Header "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, and its output is therefore suitable for
nearly any device.
.SS Encoding
.IX Subsection "Encoding"
Pod::Text uses the following logic to choose an output encoding, in order:
.IP 1. 4
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.
.IP 2. 4
If the \f(CW\*(C`encoding\*(C'\fR or \f(CW\*(C`utf8\*(C'\fR options are set, use the output encoding
specified by those options.
.IP 3. 4
If the input encoding of the POD source file was explicitly specified (using
\&\f(CW\*(C`=encoding\*(C'\fR) or automatically detected by Pod::Simple, use that as the output
encoding as well.
.IP 4. 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 E<> escapes).
.IP 5. 4
Otherwise, for EBCDIC systems, output without doing any encoding and hope
this works.
.PP
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, \f(CW\*(C`=encoding\*(C'\fR 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 E<0xEF>, and then puts \f(CW\*(C`=encoding iso\-8859\-1\*(C'\fR 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.
.PP
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 \f(CW\*(C`encoding\*(C'\fR if they have any knowledge about what encoding
the user may expect.
.PP
In particular, consider importing the Encode::Locale module, if available,
and setting \f(CW\*(C`encoding\*(C'\fR to \f(CW\*(C`locale\*(C'\fR 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 \f(CW\*(C`C\*(C'\fR, Encode::Locale will set the output encoding to
US-ASCII.  This will cause all non-ASCII characters will be replaced with \f(CW\*(C`?\*(C'\fR
and produce a flurry of warnings about unsupported characters, which may or
may not be what you want.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.IP new(ARGS) 4
.IX 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.
.RS 4
.IP alt 4
.IX Item "alt"
[2.00] If set to a true value, selects an alternate output format that, among
other things, uses a different heading style and marks \f(CW\*(C`=item\*(C'\fR entries with a
colon in the left margin.  Defaults to false.
.IP code 4
.IX Item "code"
[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.
.IP encoding 4
.IX Item "encoding"
[5.00] Specifies the encoding of the output.  The value must be an encoding
recognized by the Encode module (see 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 \f(CW\*(C`errors\*(C'\fR option.  If error
handling is other than \f(CW\*(C`die\*(C'\fR, the unrepresentable character will be replaced
with the Encode substitution character (normally \f(CW\*(C`?\*(C'\fR).
.Sp
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.
.Sp
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 \f(CW\*(C`=encoding\*(C'\fR 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 \fBperlpod\fR\|(1) for more information.
.IP errors 4
.IX Item "errors"
[3.17] How to report errors.  \f(CW\*(C`die\*(C'\fR says to throw an exception on any POD
formatting error.  \f(CW\*(C`stderr\*(C'\fR says to report errors on standard error, but not
to throw an exception.  \f(CW\*(C`pod\*(C'\fR says to include a POD ERRORS section in the
resulting documentation summarizing the errors.  \f(CW\*(C`none\*(C'\fR ignores POD errors
entirely, as much as possible.
.Sp
The default is \f(CW\*(C`pod\*(C'\fR.
.IP guesswork 4
.IX 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.
.Sp
The special value \f(CW\*(C`all\*(C'\fR enables all guesswork.  This is also the default for
backward compatibility reasons.  The special value \f(CW\*(C`none\*(C'\fR disables all
guesswork.  Otherwise, the value of this option should be a comma-separated
list of one or more of the following keywords:
.RS 4
.IP quoting 4
.IX Item "quoting"
If no guesswork is enabled, any text enclosed in C<> 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.
.RE
.RS 4
.Sp
Any unknown guesswork name is silently ignored (for potential future
compatibility), so be careful about spelling.
.RE
.IP indent 4
.IX Item "indent"
[2.00] The number of spaces to indent regular text, and the default
indentation for \f(CW\*(C`=over\*(C'\fR blocks.  Defaults to 4.
.IP loose 4
.IX Item "loose"
[2.00] If set to a true value, a blank line is printed after a \f(CW\*(C`=head1\*(C'\fR
heading.  If set to false (the default), no blank line is printed after
\&\f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR.  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.
.IP margin 4
.IX Item "margin"
[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 \fIindent\fR option.  To set the right
margin, see the \fIwidth\fR option.
.IP nourls 4
.IX Item "nourls"
[3.17] Normally, L<> formatting codes with a URL but anchor text are
formatted to show both the anchor text and the URL.  In other words:
.Sp
.Vb 1
\&    L<foo|http://example.com/>
.Ve
.Sp
is formatted as:
.Sp
.Vb 1
\&    foo <http://example.com/>
.Ve
.Sp
This option, if set to a true value, suppresses the URL when anchor text is
given, so this example would be formatted as just \f(CW\*(C`foo\*(C'\fR.  This can produce
less cluttered output in cases where the URLs are not particularly important.
.IP quotes 4
.IX Item "quotes"
[4.00] Sets the quote marks used to surround C<> 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.
.Sp
This may also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote
marks are added around C<> text.
.IP sentence 4
.IX Item "sentence"
[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.
.IP stderr 4
.IX Item "stderr"
[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 \f(CW\*(C`errors\*(C'\fR to \f(CW\*(C`stderr\*(C'\fR if \f(CW\*(C`errors\*(C'\fR is not already set.  It is
supported for backward compatibility.
.IP utf8 4
.IX Item "utf8"
[3.12] If this option is set to a true value, the output encoding is set to
UTF\-8.  This is equivalent to setting \f(CW\*(C`encoding\*(C'\fR to \f(CW\*(C`UTF\-8\*(C'\fR if \f(CW\*(C`encoding\*(C'\fR
is not already set.  It is supported for backward compatibility.
.IP width 4
.IX Item "width"
[2.00] The column at which to wrap text on the right-hand side.  Defaults to
76.
.RE
.RS 4
.RE
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
As a derived class from Pod::Simple, Pod::Text supports the same methods and
interfaces.  See Pod::Simple for all the details.  This section summarizes
the most-frequently-used methods and the ones added by Pod::Text.
.IP output_fh(FH) 4
.IX Item "output_fh(FH)"
Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR
to the file handle FH instead of \f(CW\*(C`STDOUT\*(C'\fR.
.IP output_string(REF) 4
.IX Item "output_string(REF)"
Direct the output from \fBparse_file()\fR, \fBparse_lines()\fR, or \fBparse_string_document()\fR
to the scalar variable pointed to by REF, rather than \f(CW\*(C`STDOUT\*(C'\fR.  For example:
.Sp
.Vb 4
\&    my $man = Pod::Man\->new();
\&    my $output;
\&    $man\->output_string(\e$output);
\&    $man\->parse_file(\*(Aq/some/input/file\*(Aq);
.Ve
.Sp
Be aware that the output in that variable will already be encoded (see
"Encoding").
.IP parse_file(PATH) 4
.IX Item "parse_file(PATH)"
Read the POD source from PATH and format it.  By default, the output is sent
to \f(CW\*(C`STDOUT\*(C'\fR, but this can be changed with the \fBoutput_fh()\fR or \fBoutput_string()\fR
methods.
.IP "parse_from_file(INPUT, OUTPUT)" 4
.IX Item "parse_from_file(INPUT, OUTPUT)"
.PD 0
.IP "parse_from_filehandle(FH, OUTPUT)" 4
.IX Item "parse_from_filehandle(FH, OUTPUT)"
.PD
Read the POD source from INPUT, format it, and output the results to OUTPUT.
.Sp
\&\fBparse_from_filehandle()\fR is provided for backward compatibility with older
versions of Pod::Man.  \fBparse_from_file()\fR should be used instead.
.IP "parse_lines(LINES[, ...[, undef]])" 4
.IX Item "parse_lines(LINES[, ...[, undef]])"
Parse the provided lines as POD source, writing the output to either \f(CW\*(C`STDOUT\*(C'\fR
or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR methods.  This
method can be called repeatedly to provide more input lines.  An explicit
\&\f(CW\*(C`undef\*(C'\fR should be passed to indicate the end of input.
.Sp
This method expects raw bytes, not decoded characters.
.IP parse_string_document(INPUT) 4
.IX Item "parse_string_document(INPUT)"
Parse the provided scalar variable as POD source, writing the output to either
\&\f(CW\*(C`STDOUT\*(C'\fR or the file handle set with the \fBoutput_fh()\fR or \fBoutput_string()\fR
methods.
.Sp
This method expects raw bytes, not decoded characters.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
Pod::Text exports one function for backward compatibility with older versions.
This function is deprecated; instead, use the object-oriented interface
described above.
.IP "pod2text([[\-a,] [\-NNN,]] INPUT[, OUTPUT])" 4
.IX 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 \f(CW\*(C`STDOUT\*(C'\fR.  INPUT can be any expression supported as
the second argument to two-argument \fBopen()\fR.
.Sp
If \f(CW\*(C`\-a\*(C'\fR is given as an initial argument, pass the \f(CW\*(C`alt\*(C'\fR option to the
Pod::Text constructor.  This enables alternative formatting.
.Sp
If \f(CW\*(C`\-NNN\*(C'\fR is given as an initial argument, pass the \f(CW\*(C`width\*(C'\fR option to the
Pod::Text constructor with the number \f(CW\*(C`NNN\*(C'\fR as its argument.  This sets the
wrap line width to NNN.
.SH DIAGNOSTICS
.IX Header "DIAGNOSTICS"
.IP "Bizarre space in item" 4
.IX Item "Bizarre space in item"
.PD 0
.IP "Item called without tag" 4
.IX Item "Item called without tag"
.PD
(W) Something has gone wrong in internal \f(CW\*(C`=item\*(C'\fR processing.  These
messages indicate a bug in Pod::Text; you should never see them.
.ie n .IP "Can't open %s for reading: %s" 4
.el .IP "Can't open \f(CW%s\fR for reading: \f(CW%s\fR" 4
.IX Item "Can't open %s for reading: %s"
(F) Pod::Text was invoked via the compatibility mode \fBpod2text()\fR interface
and the input file it was given could not be opened.
.IP "Invalid errors setting ""%s""" 4
.IX Item "Invalid errors setting ""%s"""
(F) The \f(CW\*(C`errors\*(C'\fR parameter to the constructor was set to an unknown value.
.IP "Invalid quote specification ""%s""" 4
.IX Item "Invalid quote specification ""%s"""
(F) The quote specification given (the \f(CW\*(C`quotes\*(C'\fR option to the
constructor) was invalid.  A quote specification must be either one
character long or an even number (greater than one) characters long.
.IP "POD document had syntax errors" 4
.IX Item "POD document had syntax errors"
(F) The POD document being formatted had syntax errors and the \f(CW\*(C`errors\*(C'\fR
option was set to \f(CW\*(C`die\*(C'\fR.
.SH COMPATIBILITY
.IX Header "COMPATIBILITY"
Pod::Text 2.03 (based on 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.
.PP
The current API based on 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 \fBparse_from_filehandle()\fR method was re-added for
backward compatibility in Pod::Text 3.07, included in Perl 5.9.4.
.PP
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 \f(CW\*(C`utf8\*(C'\fR option or (added
later) the \f(CW\*(C`encoding\*(C'\fR option.
.PP
Support for anchor text in L<> links of type URL was added in Pod::Text
3.14, included in Perl 5.11.5.
.PP
\&\fBparse_lines()\fR, \fBparse_string_document()\fR, and \fBparse_file()\fR set a default output
file handle of \f(CW\*(C`STDOUT\*(C'\fR if one was not already set as of Pod::Text 3.18,
included in Perl 5.19.5.
.PP
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.
.PP
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.
.PP
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
Encode module is now used for all output encoding rather than PerlIO
layers, which fixes earlier problems with output to scalars.
.SH AUTHOR
.IX Header "AUTHOR"
Russ Allbery <rra@cpan.org>, based \fIvery\fR 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.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 1999\-2002, 2004, 2006, 2008\-2009, 2012\-2016, 2018\-2019, 2022 Russ
Allbery <rra@cpan.org>
.PP
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Encode::Locale, Encode::Supproted, Pod::Simple,
Pod::Text::Termcap, \fBperlpod\fR\|(1), \fBpod2text\fR\|(1)
.PP
The current version of this module is always available from its web site at
<https://www.eyrie.org/~eagle/software/podlators/>.  It is also part of the
Perl core distribution as of 5.6.0.