diff options
Diffstat (limited to 'upstream/debian-bookworm/man1/perldoc.1')
| -rw-r--r-- | upstream/debian-bookworm/man1/perldoc.1 | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man1/perldoc.1 b/upstream/debian-bookworm/man1/perldoc.1 new file mode 100644 index 00000000..98eabaa5 --- /dev/null +++ b/upstream/debian-bookworm/man1/perldoc.1 @@ -0,0 +1,354 @@ +.\" Automatically generated by Pod::Man 4.14 (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 +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. 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 "PERLDOC 1" +.TH PERLDOC 1 "2023-11-25" "perl v5.36.0" "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" +perldoc \- Look up Perl documentation in Pod format. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +.Vb 10 +\& perldoc [\-h] [\-D] [\-t] [\-u] [\-m] [\-l] [\-U] [\-F] +\& [\-i] [\-V] [\-T] [\-r] +\& [\-d destination_file] +\& [\-o formatname] +\& [\-M FormatterClassName] +\& [\-w formatteroption:value] +\& [\-n nroff\-replacement] +\& [\-X] +\& [\-L language_code] +\& PageName|ModuleName|ProgramName|URL +.Ve +.PP +Examples: +.PP +.Vb 1 +\& perldoc \-f BuiltinFunction +\& +\& perldoc \-L it \-f BuiltinFunction +\& +\& perldoc \-q FAQ Keyword +\& +\& perldoc \-L fr \-q FAQ Keyword +\& +\& perldoc \-v PerlVariable +\& +\& perldoc \-a PerlAPI +.Ve +.PP +See below for more description of the switches. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBperldoc\fR looks up documentation in .pod format that is embedded in the perl +installation tree or in a perl script, and displays it using a variety of +formatters. This is primarily used for the documentation for the perl library +modules. +.PP +Your system may also have man pages installed for those modules, in +which case you can probably just use the \fBman\fR\|(1) command. +.PP +If you are looking for a table of contents to the Perl library modules +documentation, see the perltoc page. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-h\fR" 5 +.IX Item "-h" +Prints out a brief \fBh\fRelp message. +.IP "\fB\-D\fR" 5 +.IX Item "-D" +\&\fBD\fRescribes search for the item in \fBd\fRetail. +.IP "\fB\-t\fR" 5 +.IX Item "-t" +Display docs using plain \fBt\fRext converter, instead of nroff. This may be faster, +but it probably won't look as nice. +.IP "\fB\-u\fR" 5 +.IX Item "-u" +Skip the real Pod formatting, and just show the raw Pod source (\fBU\fRnformatted) +.IP "\fB\-m\fR \fImodule\fR" 5 +.IX Item "-m module" +Display the entire module: both code and unformatted pod documentation. +This may be useful if the docs don't explain a function in the detail +you need, and you'd like to inspect the code directly; perldoc will find +the file for you and simply hand it off for display. +.IP "\fB\-l\fR" 5 +.IX Item "-l" +Display on\fBl\fRy the file name of the module found. +.IP "\fB\-U\fR" 5 +.IX Item "-U" +When running as the superuser, don't attempt drop privileges for security. +This option is implied with \fB\-F\fR. +.Sp +\&\fB\s-1NOTE\s0\fR: Please see the heading \s-1SECURITY\s0 below for more information. +.IP "\fB\-F\fR" 5 +.IX Item "-F" +Consider arguments as file names; no search in directories will be performed. +Implies \fB\-U\fR if run as the superuser. +.IP "\fB\-f\fR \fIperlfunc\fR" 5 +.IX Item "-f perlfunc" +The \fB\-f\fR option followed by the name of a perl built-in function will +extract the documentation of this function from perlfunc. +.Sp +Example: +.Sp +.Vb 1 +\& perldoc \-f sprintf +.Ve +.IP "\fB\-q\fR \fIperlfaq-search-regexp\fR" 5 +.IX Item "-q perlfaq-search-regexp" +The \fB\-q\fR option takes a regular expression as an argument. It will search +the \fBq\fRuestion headings in perlfaq[1\-9] and print the entries matching +the regular expression. +.Sp +Example: +.Sp +.Vb 1 +\& perldoc \-q shuffle +.Ve +.IP "\fB\-a\fR \fIperlapifunc\fR" 5 +.IX Item "-a perlapifunc" +The \fB\-a\fR option followed by the name of a perl api function will +extract the documentation of this function from perlapi. +.Sp +Example: +.Sp +.Vb 1 +\& perldoc \-a newHV +.Ve +.IP "\fB\-v\fR \fIperlvar\fR" 5 +.IX Item "-v perlvar" +The \fB\-v\fR option followed by the name of a Perl predefined variable will +extract the documentation of this variable from perlvar. +.Sp +Examples: +.Sp +.Vb 3 +\& perldoc \-v \*(Aq$"\*(Aq +\& perldoc \-v @+ +\& perldoc \-v DATA +.Ve +.IP "\fB\-T\fR" 5 +.IX Item "-T" +This specifies that the output is not to be sent to a pager, but is to +be sent directly to \s-1STDOUT.\s0 +.IP "\fB\-d\fR \fIdestination-filename\fR" 5 +.IX Item "-d destination-filename" +This specifies that the output is to be sent neither to a pager nor +to \s-1STDOUT,\s0 but is to be saved to the specified filename. Example: +\&\f(CW\*(C`perldoc \-oLaTeX \-dtextwrapdocs.tex Text::Wrap\*(C'\fR +.IP "\fB\-o\fR \fIoutput-formatname\fR" 5 +.IX Item "-o output-formatname" +This specifies that you want Perldoc to try using a Pod-formatting +class for the output format that you specify. For example: +\&\f(CW\*(C`\-oman\*(C'\fR. This is actually just a wrapper around the \f(CW\*(C`\-M\*(C'\fR switch; +using \f(CW\*(C`\-o\f(CIformatname\f(CW\*(C'\fR just looks for a loadable class by adding +that format name (with different capitalizations) to the end of +different classname prefixes. +.Sp +For example, \f(CW\*(C`\-oLaTeX\*(C'\fR currently tries all of the following classes: +Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex +Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex +Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex +Pod::LATEX. +.IP "\fB\-M\fR \fImodule-name\fR" 5 +.IX Item "-M module-name" +This specifies the module that you want to try using for formatting the +pod. The class must at least provide a \f(CW\*(C`parse_from_file\*(C'\fR method. +For example: \f(CW\*(C`perldoc \-MPod::Perldoc::ToChecker\*(C'\fR. +.Sp +You can specify several classes to try by joining them with commas +or semicolons, as in \f(CW\*(C`\-MTk::SuperPod;Tk::Pod\*(C'\fR. +.IP "\fB\-w\fR \fIoption:value\fR or \fB\-w\fR \fIoption\fR" 5 +.IX Item "-w option:value or -w option" +This specifies an option to call the formatter \fBw\fRith. For example, +\&\f(CW\*(C`\-w textsize:15\*(C'\fR will call +\&\f(CW\*(C`$formatter\->textsize(15)\*(C'\fR on the formatter object before it is +used to format the object. For this to be valid, the formatter class +must provide such a method, and the value you pass should be valid. +(So if \f(CW\*(C`textsize\*(C'\fR expects an integer, and you do \f(CW\*(C`\-w textsize:big\*(C'\fR, +expect trouble.) +.Sp +You can use \f(CW\*(C`\-w optionname\*(C'\fR (without a value) as shorthand for +\&\f(CW\*(C`\-w optionname:\f(CITRUE\f(CW\*(C'\fR. This is presumably useful in cases of on/off +features like: \f(CW\*(C`\-w page_numbering\*(C'\fR. +.Sp +You can use an \*(L"=\*(R" instead of the \*(L":\*(R", as in: \f(CW\*(C`\-w textsize=15\*(C'\fR. This +might be more (or less) convenient, depending on what shell you use. +.IP "\fB\-X\fR" 5 +.IX Item "-X" +Use an index if it is present. The \fB\-X\fR option looks for an entry +whose basename matches the name given on the command line in the file +\&\f(CW\*(C`$Config{archlib}/pod.idx\*(C'\fR. The \fIpod.idx\fR file should contain fully +qualified filenames, one per line. +.IP "\fB\-L\fR \fIlanguage_code\fR" 5 +.IX Item "-L language_code" +This allows one to specify the \fIlanguage code\fR for the desired language +translation. If the \f(CW\*(C`POD2::<language_code>\*(C'\fR package isn't +installed in your system, the switch is ignored. +All available translation packages are to be found under the \f(CW\*(C`POD2::\*(C'\fR +namespace. See \s-1POD2::IT\s0 (or \s-1POD2::FR\s0) to see how to create new +localized \f(CW\*(C`POD2::*\*(C'\fR documentation packages and integrate them into +Pod::Perldoc. +.IP "\fBPageName|ModuleName|ProgramName|URL\fR" 5 +.IX Item "PageName|ModuleName|ProgramName|URL" +The item you want to look up. Nested modules (such as \f(CW\*(C`File::Basename\*(C'\fR) +are specified either as \f(CW\*(C`File::Basename\*(C'\fR or \f(CW\*(C`File/Basename\*(C'\fR. You may also +give a descriptive name of a page, such as \f(CW\*(C`perlfunc\*(C'\fR. For URLs, \s-1HTTP\s0 and +\&\s-1HTTPS\s0 are the only kind currently supported. +.Sp +For simple names like 'foo', when the normal search fails to find +a matching page, a search with the \*(L"perl\*(R" prefix is tried as well. +So \*(L"perldoc intro\*(R" is enough to find/render \*(L"perlintro.pod\*(R". +.IP "\fB\-n\fR \fIsome-formatter\fR" 5 +.IX Item "-n some-formatter" +Specify replacement for groff +.IP "\fB\-r\fR" 5 +.IX Item "-r" +Recursive search. +.IP "\fB\-i\fR" 5 +.IX Item "-i" +Ignore case. +.IP "\fB\-V\fR" 5 +.IX Item "-V" +Displays the version of perldoc you're running. +.SH "SECURITY" +.IX Header "SECURITY" +Because \fBperldoc\fR does not run properly tainted, and is known to +have security issues, when run as the superuser it will attempt to +drop privileges by setting the effective and real IDs to nobody's +or nouser's account, or \-2 if unavailable. If it cannot relinquish +its privileges, it will not run. +.PP +See the \f(CW\*(C`\-U\*(C'\fR option if you do not want this behavior but \fBbeware\fR +that there are significant security risks if you choose to use \f(CW\*(C`\-U\*(C'\fR. +.PP +Since 3.26, using \f(CW\*(C`\-F\*(C'\fR as the superuser also implies \f(CW\*(C`\-U\*(C'\fR as opening +most files and traversing directories requires privileges that are +above the nobody/nogroup level. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +Any switches in the \f(CW\*(C`PERLDOC\*(C'\fR environment variable will be used before the +command line arguments. +.PP +Useful values for \f(CW\*(C`PERLDOC\*(C'\fR include \f(CW\*(C`\-oterm\*(C'\fR, \f(CW\*(C`\-otext\*(C'\fR, \f(CW\*(C`\-ortf\*(C'\fR, +\&\f(CW\*(C`\-oxml\*(C'\fR, and so on, depending on what modules you have on hand; or +the formatter class may be specified exactly with \f(CW\*(C`\-MPod::Perldoc::ToTerm\*(C'\fR +or the like. +.PP +\&\f(CW\*(C`perldoc\*(C'\fR also searches directories +specified by the \f(CW\*(C`PERL5LIB\*(C'\fR (or \f(CW\*(C`PERLLIB\*(C'\fR if \f(CW\*(C`PERL5LIB\*(C'\fR is not +defined) and \f(CW\*(C`PATH\*(C'\fR environment variables. +(The latter is so that embedded pods for executables, such as +\&\f(CW\*(C`perldoc\*(C'\fR itself, are available.) +.PP +In directories where either \f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR exist, \f(CW\*(C`perldoc\*(C'\fR +will add \f(CW\*(C`.\*(C'\fR and \f(CW\*(C`lib\*(C'\fR first to its search path, and as long as you're not +the superuser will add \f(CW\*(C`blib\*(C'\fR too. This is really helpful if you're working +inside of a build directory and want to read through the docs even if you +have a version of a module previously installed. +.PP +\&\f(CW\*(C`perldoc\*(C'\fR will use, in order of preference, the pager defined in +\&\f(CW\*(C`PERLDOC_PAGER\*(C'\fR, \f(CW\*(C`MANPAGER\*(C'\fR, or \f(CW\*(C`PAGER\*(C'\fR before trying to find a pager +on its own. (\f(CW\*(C`MANPAGER\*(C'\fR is not used if \f(CW\*(C`perldoc\*(C'\fR was told to display +plain text or unformatted pod.) +.PP +When using perldoc in it's \f(CW\*(C`\-m\*(C'\fR mode (display module source code), +\&\f(CW\*(C`perldoc\*(C'\fR will attempt to use the pager set in \f(CW\*(C`PERLDOC_SRC_PAGER\*(C'\fR. +A useful setting for this command is your favorite editor as in +\&\f(CW\*(C`/usr/bin/nano\*(C'\fR. (Don't judge me.) +.PP +One useful value for \f(CW\*(C`PERLDOC_PAGER\*(C'\fR is \f(CW\*(C`less \-+C \-E\*(C'\fR. +.PP +Having \s-1PERLDOCDEBUG\s0 set to a positive integer will make perldoc emit +even more descriptive output than the \f(CW\*(C`\-D\*(C'\fR switch does; the higher the +number, the more it emits. +.SH "CHANGES" +.IX Header "CHANGES" +Up to 3.14_05, the switch \fB\-v\fR was used to produce verbose +messages of \fBperldoc\fR operation, which is now enabled by \fB\-D\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +perlpod, Pod::Perldoc +.SH "AUTHOR" +.IX Header "AUTHOR" +Current maintainer: Mark Allen \f(CW\*(C`<mallen@cpan.org>\*(C'\fR +.PP +Past contributors are: +brian d foy \f(CW\*(C`<bdfoy@cpan.org>\*(C'\fR +Adriano R. Ferreira \f(CW\*(C`<ferreira@cpan.org>\*(C'\fR, +Sean M. Burke \f(CW\*(C`<sburke@cpan.org>\*(C'\fR, +Kenneth Albanowski \f(CW\*(C`<kjahds@kjahds.com>\*(C'\fR, +Andy Dougherty \f(CW\*(C`<doughera@lafcol.lafayette.edu>\*(C'\fR, +and many others. |