diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/pod2text.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/pod2text.1 | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/pod2text.1 b/upstream/mageia-cauldron/man1/pod2text.1 new file mode 100644 index 00000000..e286ccf8 --- /dev/null +++ b/upstream/mageia-cauldron/man1/pod2text.1 @@ -0,0 +1,294 @@ +.\" -*- 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 "POD2TEXT 1" +.TH POD2TEXT 1 2023-12-15 "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 +pod2text \- Convert POD data to formatted ASCII text +.SH SYNOPSIS +.IX Header "SYNOPSIS" +pod2text [\fB\-aclostu\fR] [\fB\-\-code\fR] [\fB\-e\fR\ \fIencoding\fR] + [\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]] + [\fB\-i\fR\ \fIindent\fR] [\fB\-q\fR\ \fIquotes\fR] + [\fB\-\-nourls\fR] [\fB\-\-stderr\fR] [\fB\-w\fR\ \fIwidth\fR] [\fIinput\fR [\fIoutput\fR ...]] +.PP +pod2text \fB\-h\fR +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBpod2text\fR is a wrapper script around the Pod::Text and its subclasses. +It uses them to generate formatted text from POD source. It can optionally +use either termcap sequences or ANSI color escape sequences to format the +text. +.PP +\&\fIinput\fR is the file to read for POD source (the POD can be embedded in code). +If \fIinput\fR isn't given, it defaults to \f(CW\*(C`STDIN\*(C'\fR. \fIoutput\fR, if given, is the +file to which to write the formatted output. If \fIoutput\fR isn't given, the +formatted output is written to \f(CW\*(C`STDOUT\*(C'\fR. Several POD files can be processed +in the same \fBpod2text\fR invocation (saving module load and compile times) by +providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line. +.PP +By default, the output encoding is the same as the encoding of the input file, +or UTF\-8 if that encoding is not set (except on EBCDIC systems). See the +\&\fB\-e\fR option to explicitly set the output encoding and "Encoding" in Pod::Text +for more discussion. +.SH OPTIONS +.IX Header "OPTIONS" +Each option is annotated with the version of podlators in which that option +was added with its current meaning. +.IP "\fB\-a\fR, \fB\-\-alt\fR" 4 +.IX Item "-a, --alt" +[1.00] Use 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. +.IP \fB\-\-code\fR 4 +.IX Item "--code" +[1.11] Include any non-POD text from the input file in the output as well. +Useful for viewing code documented with POD blocks with the POD rendered and +the code left intact. +.IP "\fB\-c\fR, \fB\-\-color\fR" 4 +.IX Item "-c, --color" +[1.00] Format the output with ANSI color escape sequences. Using this option +requires that Term::ANSIColor be installed on your system. +.IP "\fB\-e\fR \fIencoding\fR, \fB\-\-encoding\fR=\fIencoding\fR" 4 +.IX Item "-e encoding, --encoding=encoding" +[5.00] Specifies the encoding of the output. \fIencoding\fR 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 +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 \fB\-\-errors\fR=\fIstyle\fR 4 +.IX Item "--errors=style" +[2.5.0] Set the error handling style. \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`die\*(C'\fR. +.IP \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4 +.IX Item "--guesswork=rule[,rule...]" +[5.01] By default, \fBpod2text\fR 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 rule \f(CW\*(C`all\*(C'\fR enables all guesswork. This is also the default for +backward compatibility reasons. The special rule \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 "\fB\-i\fR \fIindent\fR, \fB\-\-indent=\fR\fIindent\fR" 4 +.IX Item "-i indent, --indent=indent" +[1.00] Set the number of spaces to indent regular text, and the default +indentation for \f(CW\*(C`=over\*(C'\fR blocks. Defaults to 4 spaces if this option isn't +given. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +[1.00] Print out usage information and exit. +.IP "\fB\-l\fR, \fB\-\-loose\fR" 4 +.IX Item "-l, --loose" +[1.00] Print a blank line after a \f(CW\*(C`=head1\*(C'\fR heading. Normally, no blank line +is printed after \f(CW\*(C`=head1\*(C'\fR, although one is still printed after \f(CW\*(C`=head2\*(C'\fR, +because this is the expected formatting for manual pages; if you're formatting +arbitrary text documents, using this option is recommended. +.IP "\fB\-m\fR \fIwidth\fR, \fB\-\-left\-margin\fR=\fIwidth\fR, \fB\-\-margin\fR=\fIwidth\fR" 4 +.IX Item "-m width, --left-margin=width, --margin=width" +[1.24] 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 \fB\-i\fR option. +.IP \fB\-\-nourls\fR 4 +.IX Item "--nourls" +[2.5.0] 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 flag, if given, 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 "\fB\-o\fR, \fB\-\-overstrike\fR" 4 +.IX Item "-o, --overstrike" +[1.06] Format the output with overstrike printing. Bold text is rendered as +character, backspace, character. Italics and file names are rendered as +underscore, backspace, character. Many pagers, such as \fBless\fR, know how to +convert this to bold or underlined text. +.IP "\fB\-q\fR \fIquotes\fR, \fB\-\-quotes\fR=\fIquotes\fR" 4 +.IX Item "-q quotes, --quotes=quotes" +[4.00] Sets the quote marks used to surround C<> text to \fIquotes\fR. If +\&\fIquotes\fR 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 +\&\fIquotes\fR 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 "\fB\-s\fR, \fB\-\-sentence\fR" 4 +.IX Item "-s, --sentence" +[1.00] Assume each sentence ends with two spaces and try to preserve that +spacing. Without this option, all consecutive whitespace in non-verbatim +paragraphs is compressed into a single space. +.IP \fB\-\-stderr\fR 4 +.IX Item "--stderr" +[2.1.3] By default, \fBpod2text\fR dies if any errors are detected in the POD +input. If \fB\-\-stderr\fR is given and no \fB\-\-errors\fR flag is present, errors are +sent to standard error, but \fBpod2text\fR does not abort. This is equivalent to +\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility. +.IP "\fB\-t\fR, \fB\-\-termcap\fR" 4 +.IX Item "-t, --termcap" +[1.00] Try to determine the width of the screen and the bold and underline +sequences for the terminal from termcap, and use that information in +formatting the output. Output will be wrapped at two columns less than the +width of your terminal device. Using this option requires that your system +have a termcap file somewhere where Term::Cap can find it and requires that +your system support termios. With this option, the output of \fBpod2text\fR will +contain terminal control sequences for your current terminal type. +.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4 +.IX Item "-u, --utf8" +[2.2.0] Set the output encoding to UTF\-8. This is equivalent to +\&\f(CW\*(C`\-\-encoding=UTF\-8\*(C'\fR and is supported for backward compatibility. +.IP "\fB\-w\fR, \fB\-\-width=\fR\fIwidth\fR, \fB\-\fR\fIwidth\fR" 4 +.IX Item "-w, --width=width, -width" +[1.00] The column at which to wrap text on the right-hand side. Defaults to +76, unless \fB\-t\fR is given, in which case it's two columns less than the width +of your terminal device. +.SH "EXIT STATUS" +.IX Header "EXIT STATUS" +As long as all documents processed result in some output, even if that output +includes errata (a \f(CW\*(C`POD ERRORS\*(C'\fR section generated with \f(CW\*(C`\-\-errors=pod\*(C'\fR), +\&\fBpod2text\fR will exit with status 0. If any of the documents being processed +do not result in an output document, \fBpod2text\fR 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 \f(CW\*(C`die\*(C'\fR, \fBpod2text\fR will abort +immediately with exit status 255. +.SH DIAGNOSTICS +.IX Header "DIAGNOSTICS" +If \fBpod2text\fR fails with errors, see Pod::Text and Pod::Simple for +information about what those errors might mean. Internally, it can also +produce the following diagnostics: +.IP "\-c (\-\-color) requires Term::ANSIColor be installed" 4 +.IX Item "-c (--color) requires Term::ANSIColor be installed" +(F) \fB\-c\fR or \fB\-\-color\fR were given, but Term::ANSIColor could not be loaded. +.ie n .IP "Unknown option: %s" 4 +.el .IP "Unknown option: \f(CW%s\fR" 4 +.IX Item "Unknown option: %s" +(F) An unknown command line option was given. +.PP +In addition, other Getopt::Long error messages may result from invalid +command-line options. +.SH ENVIRONMENT +.IX Header "ENVIRONMENT" +.IP COLUMNS 4 +.IX Item "COLUMNS" +If \fB\-t\fR is given, \fBpod2text\fR will take the current width of your screen from +this environment variable, if available. It overrides terminal width +information in TERMCAP. +.IP TERMCAP 4 +.IX Item "TERMCAP" +If \fB\-t\fR is given, \fBpod2text\fR will use the contents of this environment +variable if available to determine the correct formatting sequences for your +current terminal device. +.SH AUTHOR +.IX Header "AUTHOR" +Russ Allbery <rra@cpan.org>. +.SH "COPYRIGHT AND LICENSE" +.IX Header "COPYRIGHT AND LICENSE" +Copyright 1999\-2001, 2004, 2006, 2008, 2010, 2012\-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::Supported, Pod::Text, Pod::Text::Color, +Pod::Text::Overstrike, Pod::Text::Termcap, Pod::Simple, \fBperlpod\fR\|(1) +.PP +The current version of this script 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. |