diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/pod2man.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/pod2man.1 | 419 |
1 files changed, 419 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/pod2man.1 b/upstream/mageia-cauldron/man1/pod2man.1 new file mode 100644 index 00000000..85da7a6b --- /dev/null +++ b/upstream/mageia-cauldron/man1/pod2man.1 @@ -0,0 +1,419 @@ +.\" -*- 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 "POD2MAN 1" +.TH POD2MAN 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 +pod2man \- Convert POD data to formatted *roff input +.SH SYNOPSIS +.IX Header "SYNOPSIS" +pod2man [\fB\-\-center\fR=\fIstring\fR] [\fB\-\-date\fR=\fIstring\fR] + [\fB\-\-encoding\fR=\fIencoding\fR] [\fB\-\-errors\fR=\fIstyle\fR] [\fB\-\-fixed\fR=\fIfont\fR] + [\fB\-\-fixedbold\fR=\fIfont\fR] [\fB\-\-fixeditalic\fR=\fIfont\fR] + [\fB\-\-fixedbolditalic\fR=\fIfont\fR] [\fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...]] + [\fB\-\-name\fR=\fIname\fR] [\fB\-\-nourls\fR] [\fB\-\-official\fR] + [\fB\-\-release\fR=\fIversion\fR] [\fB\-\-section\fR=\fImanext\fR] + [\fB\-\-quotes\fR=\fIquotes\fR] [\fB\-\-lquote\fR=\fIquote\fR] [\fB\-\-rquote\fR=\fIquote\fR] + [\fB\-\-stderr\fR] [\fB\-\-utf8\fR] [\fB\-\-verbose\fR] [\fIinput\fR [\fIoutput\fR] ...] +.PP +pod2man \fB\-\-help\fR +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBpod2man\fR is a wrapper script around the Pod::Man module, using it to +generate *roff input from POD source. The resulting *roff code is suitable +for display on a terminal using \fBnroff\fR\|(1), normally via \fBman\fR\|(1), or +printing using \fBtroff\fR\|(1). +.PP +By default (on non-EBCDIC systems), \fBpod2man\fR outputs UTF\-8 manual pages. +Its output should work with the \fBman\fR program on systems that use \fBgroff\fR +(most Linux distributions) or \fBmandoc\fR (most BSD variants), but may result in +mangled output on older UNIX systems. To choose a different, possibly more +backward-compatible output mangling on such systems, use \f(CW\*(C`\-\-encoding=roff\*(C'\fR +(the default in earlier Pod::Man versions). See the \fB\-\-encoding\fR option and +"ENCODING" in Pod::Man for more details. +.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 \fBpod2man\fR invocation (saving module load and compile times) by +providing multiple pairs of \fIinput\fR and \fIoutput\fR files on the command line. +.PP +\&\fB\-\-section\fR, \fB\-\-release\fR, \fB\-\-center\fR, \fB\-\-date\fR, and \fB\-\-official\fR can be +used to set the headers and footers to use. If not given, Pod::Man will +assume various defaults. See below for details. +.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\-c\fR \fIstring\fR, \fB\-\-center\fR=\fIstring\fR" 4 +.IX Item "-c string, --center=string" +[1.00] Sets the centered page header for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR. The +default is \f(CW\*(C`User Contributed Perl Documentation\*(C'\fR, but also see \fB\-\-official\fR +below. +.IP "\fB\-d\fR \fIstring\fR, \fB\-\-date\fR=\fIstring\fR" 4 +.IX Item "-d string, --date=string" +[4.00] Set the left-hand footer string for the \f(CW\*(C`.TH\*(C'\fR macro to \fIstring\fR. By +default, the first of POD_MAN_DATE, SOURCE_DATE_EPOCH, the modification date +of the input file, or the current date (if input comes from \f(CW\*(C`STDIN\*(C'\fR) will be +used, and the date will be in UTC. See "CLASS METHODS" in Pod::Man for more +details. +.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). The default on +non-EBCDIC systems is UTF\-8. +.Sp +If the output contains characters that cannot be represented in this encoding, +that is an error that will be reported as configured by the \fB\-\-errors\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 \f(CW\*(C`encoding\*(C'\fR option is set to the special value \f(CW\*(C`groff\*(C'\fR (the default on +EBCDIC systems), or if the Encode module is not available and the encoding is +set to anything other than \f(CW\*(C`roff\*(C'\fR (see below), Pod::Man will translate all +non-ASCII characters to \f(CW\*(C`\e[uNNNN]\*(C'\fR Unicode escapes. These are not +traditionally part of the *roff language, but are supported by \fBgroff\fR and +\&\fBmandoc\fR and thus by the majority of manual page processors in use today. +.Sp +If \fIencoding\fR is set to the special value \f(CW\*(C`roff\*(C'\fR, \fBpod2man\fR will do its +historic transformation of (some) ISO 8859\-1 characters into *roff escapes +that may be adequate in troff and may be readable (if ugly) in nroff. This +was the default behavior of versions of \fBpod2man\fR before 5.00. With this +encoding, all other non-ASCII characters will be replaced with \f(CW\*(C`X\*(C'\fR. It may +be required for very old troff and nroff implementations that do not support +UTF\-8, but its representation of any non-ASCII character is very poor and +often specific to European languages. Its use is discouraged. +.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. 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\-\-fixed\fR=\fIfont\fR 4 +.IX Item "--fixed=font" +[1.0] The fixed-width font to use for verbatim text and code. Defaults to +\&\f(CW\*(C`CW\*(C'\fR. Some systems may want \f(CW\*(C`CR\*(C'\fR instead. Only matters for \fBtroff\fR +output. +.IP \fB\-\-fixedbold\fR=\fIfont\fR 4 +.IX Item "--fixedbold=font" +[1.0] Bold version of the fixed-width font. Defaults to \f(CW\*(C`CB\*(C'\fR. Only matters +for \fBtroff\fR output. +.IP \fB\-\-fixeditalic\fR=\fIfont\fR 4 +.IX Item "--fixeditalic=font" +[1.0] Italic version of the fixed-width font (something of a misnomer, since +most fixed-width fonts only have an oblique version, not an italic version). +Defaults to \f(CW\*(C`CI\*(C'\fR. Only matters for \fBtroff\fR output. +.IP \fB\-\-fixedbolditalic\fR=\fIfont\fR 4 +.IX Item "--fixedbolditalic=font" +[1.0] Bold italic (in theory, probably oblique in practice) version of the +fixed-width font. Pod::Man doesn't assume you have this, and defaults to +\&\f(CW\*(C`CB\*(C'\fR. Some systems (such as Solaris) have this font available as \f(CW\*(C`CX\*(C'\fR. +Only matters for \fBtroff\fR output. +.IP \fB\-\-guesswork\fR=\fIrule\fR[,\fIrule\fR...] 4 +.IX Item "--guesswork=rule[,rule...]" +[5.00] By default, \fBpod2man\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 functions 4 +.IX Item "functions" +Convert function references like \f(CWfoo()\fR to bold even if they have no markup. +The function name accepts valid Perl characters for function names (including +\&\f(CW\*(C`:\*(C'\fR), and the trailing parentheses must be present and empty. +.IP manref 4 +.IX Item "manref" +Make the first part (before the parentheses) of man page references like +\&\f(CWfoo(1)\fR bold even if they have no markup. The section must be a single +number optionally followed by lowercase letters. +.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. +.IP variables 4 +.IX Item "variables" +Convert Perl variable names to a fixed-width font even if they have no markup. +This transformation will only be apparent in troff output, or some other +output format (unlike nroff terminal output) that supports fixed-width fonts. +.RE +.RS 4 +.Sp +Any unknown guesswork name is silently ignored (for potential future +compatibility), so be careful about spelling. +.RE +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +.IX Item "-h, --help" +[1.00] Print out usage information. +.IP "\fB\-l\fR, \fB\-\-lax\fR" 4 +.IX Item "-l, --lax" +[1.00] No longer used. \fBpod2man\fR used to check its input for validity as a +manual page, but this should now be done by \fBpodchecker\fR\|(1) instead. +Accepted for backward compatibility; this option no longer does anything. +.IP \fB\-\-language\fR=\fIlanguage\fR 4 +.IX Item "--language=language" +[5.00] Add commands telling \fBgroff\fR that the input file is in the given +language. The value of this setting must be a language abbreviation for which +\&\fBgroff\fR provides supplemental configuration, such as \f(CW\*(C`ja\*(C'\fR (for Japanese) or +\&\f(CW\*(C`zh\*(C'\fR (for Chinese). +.Sp +This adds: +.Sp +.Vb 2 +\& .mso <language>.tmac +\& .hla <language> +.Ve +.Sp +to the start of the file, which configure correct line breaking for the +specified language. Without these commands, groff may not know how to add +proper line breaks for Chinese and Japanese text if the man page is installed +into the normal man page directory, such as \fI/usr/share/man\fR. +.Sp +On many systems, this will be done automatically if the man page is installed +into a language-specific man page directory, such as \fI/usr/share/man/zh_CN\fR. +In that case, this option is not required. +.Sp +Unfortunately, the commands added with this option are specific to \fBgroff\fR +and will not work with other \fBtroff\fR and \fBnroff\fR implementations. +.IP \fB\-\-lquote\fR=\fIquote\fR 4 +.IX Item "--lquote=quote" +.PD 0 +.IP \fB\-\-rquote\fR=\fIquote\fR 4 +.IX Item "--rquote=quote" +.PD +[4.08] Sets the quote marks used to surround C<> text. \fB\-\-lquote\fR sets +the left quote mark and \fB\-\-rquote\fR sets the right quote mark. Either may +also be set to the special value \f(CW\*(C`none\*(C'\fR, in which case no quote mark is added +on that side of C<> text (but the font is still changed for troff output). +.Sp +Also see the \fB\-\-quotes\fR option, which can be used to set both quotes at once. +If both \fB\-\-quotes\fR and one of the other options is set, \fB\-\-lquote\fR or +\&\fB\-\-rquote\fR overrides \fB\-\-quotes\fR. +.IP "\fB\-n\fR \fIname\fR, \fB\-\-name\fR=\fIname\fR" 4 +.IX Item "-n name, --name=name" +[4.08] Set the name of the manual page for the \f(CW\*(C`.TH\*(C'\fR macro to \fIname\fR. +Without this option, the manual name is set to the uppercased base name of the +file being converted unless the manual section is 3, in which case the path is +parsed to see if it is a Perl module path. If it is, a path like +\&\f(CW\*(C`.../lib/Pod/Man.pm\*(C'\fR is converted into a name like \f(CW\*(C`Pod::Man\*(C'\fR. This option, +if given, overrides any automatic determination of the name. +.Sp +Although one does not have to follow this convention, be aware that the +convention for UNIX manual pages is for the title to be in all-uppercase, even +if the command isn't. (Perl modules traditionally use mixed case for the +manual page title, however.) +.Sp +This option is probably not useful when converting multiple POD files at once. +.Sp +When converting POD source from standard input, the name will be set to +\&\f(CW\*(C`STDIN\*(C'\fR if this option is not provided. Providing this option is strongly +recommended to set a meaningful manual page name. +.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\-\-official\fR" 4 +.IX Item "-o, --official" +[1.00] Set the default header to indicate that this page is part of the +standard Perl release, if \fB\-\-center\fR is not also given. +.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 (but the font is still changed for troff +output). +.Sp +Also see the \fB\-\-lquote\fR and \fB\-\-rquote\fR options, which can be used to set the +left and right quotes independently. If both \fB\-\-quotes\fR and one of the other +options is set, \fB\-\-lquote\fR or \fB\-\-rquote\fR overrides \fB\-\-quotes\fR. +.IP "\fB\-r\fR \fIversion\fR, \fB\-\-release\fR=\fIversion\fR" 4 +.IX Item "-r version, --release=version" +[1.00] Set the centered footer for the \f(CW\*(C`.TH\*(C'\fR macro to \fIversion\fR. By +default, this is set to the version of Perl you run \fBpod2man\fR under. Setting +this to the empty string will cause some *roff implementations to use the +system default value. +.Sp +Note that some system \f(CW\*(C`an\*(C'\fR macro sets assume that the centered footer will be +a modification date and will prepend something like \f(CW\*(C`Last modified: \*(C'\fR. If +this is the case for your target system, you may want to set \fB\-\-release\fR to +the last modified date and \fB\-\-date\fR to the version number. +.IP "\fB\-s\fR \fIstring\fR, \fB\-\-section\fR=\fIstring\fR" 4 +.IX Item "-s string, --section=string" +[1.00] Set the section for the \f(CW\*(C`.TH\*(C'\fR macro. The standard section numbering +convention is to use 1 for user commands, 2 for system calls, 3 for functions, +4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous +information, and 8 for administrator commands. There is a lot of variation +here, however; some systems (like Solaris) use 4 for file formats, 5 for +miscellaneous information, and 7 for devices. Still others use 1m instead of +8, or some mix of both. About the only section numbers that are reliably +consistent are 1, 2, and 3. +.Sp +By default, section 1 will be used unless the file ends in \f(CW\*(C`.pm\*(C'\fR, in which +case section 3 will be selected. +.IP \fB\-\-stderr\fR 4 +.IX Item "--stderr" +[2.1.3] By default, \fBpod2man\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 \fBpod2man\fR does not abort. This is equivalent to +\&\f(CW\*(C`\-\-errors=stderr\*(C'\fR and is supported for backward compatibility. +.IP "\fB\-u\fR, \fB\-\-utf8\fR" 4 +.IX Item "-u, --utf8" +[2.1.0] This option used to tell \fBpod2man\fR to produce UTF\-8 output. Since +this is now the default as of version 5.00, it is ignored and does nothing. +.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4 +.IX Item "-v, --verbose" +[1.11] Print out the name of each output file as it is being generated. +.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), +\&\fBpod2man\fR will exit with status 0. If any of the documents being processed +do not result in an output document, \fBpod2man\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, \fBpod2man\fR will abort +immediately with exit status 255. +.SH DIAGNOSTICS +.IX Header "DIAGNOSTICS" +If \fBpod2man\fR fails with errors, see Pod::Man and Pod::Simple for +information about what those errors might mean. +.SH EXAMPLES +.IX Header "EXAMPLES" +.Vb 3 +\& pod2man program > program.1 +\& pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3 +\& pod2man \-\-section=7 note.pod > note.7 +.Ve +.PP +If you would like to print out a lot of man page continuously, you probably +want to set the C and D registers to set contiguous page numbering and +even/odd paging, at least on some versions of \fBman\fR\|(7). +.PP +.Vb 1 +\& troff \-man \-rC1 \-rD1 perl.1 perldata.1 perlsyn.1 ... +.Ve +.PP +To get index entries on \f(CW\*(C`STDERR\*(C'\fR, turn on the F register, as in: +.PP +.Vb 1 +\& troff \-man \-rF1 perl.1 +.Ve +.PP +The indexing merely outputs messages via \f(CW\*(C`.tm\*(C'\fR for each major page, section, +subsection, item, and any \f(CW\*(C`X<>\*(C'\fR directives. +.SH AUTHOR +.IX Header "AUTHOR" +Russ Allbery <rra@cpan.org>, based on the original \fBpod2man\fR by Larry Wall +and Tom Christiansen. +.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" +Pod::Man, Pod::Simple, \fBman\fR\|(1), \fBnroff\fR\|(1), \fBperlpod\fR\|(1), +\&\fBpodchecker\fR\|(1), \fBperlpodstyle\fR\|(1), \fBtroff\fR\|(1), \fBman\fR\|(7) +.PP +The man page documenting the an macro set may be \fBman\fR\|(5) instead of +\&\fBman\fR\|(7) on your system. +.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. |