Debian Codegraph @

upstream/mageia-cauldron/man1/perldoc.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLDOC 1"
61 .TH PERLDOC 1 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perldoc \- Look up Perl documentation in Pod format.
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 10
71 \& perldoc [\-h] [\-D] [\-t] [\-u] [\-m] [\-l] [\-U] [\-F]
72 \& [\-i] [\-V] [\-T] [\-r]
73 \& [\-d destination_file]
74 \& [\-o formatname]
75 \& [\-M FormatterClassName]
76 \& [\-w formatteroption:value]
77 \& [\-n nroff\-replacement]
78 \& [\-X]
79 \& [\-L language_code]
80 \& PageName|ModuleName|ProgramName|URL
81 .Ve
82 .PP
83 Examples:
84 .PP
85 .Vb 1
86 \& perldoc \-f BuiltinFunction
87 \&
88 \& perldoc \-L it \-f BuiltinFunction
89 \&
90 \& perldoc \-q FAQ Keyword
91 \&
92 \& perldoc \-L fr \-q FAQ Keyword
93 \&
94 \& perldoc \-v PerlVariable
95 \&
96 \& perldoc \-a PerlAPI
97 .Ve
98 .PP
99 See below for more description of the switches.
100 .SH DESCRIPTION
101 .IX Header "DESCRIPTION"
102 \&\fBperldoc\fR looks up documentation in .pod format that is embedded in the perl
103 installation tree or in a perl script, and displays it using a variety of
104 formatters. This is primarily used for the documentation for the perl library
105 modules.
106 .PP
107 Your system may also have man pages installed for those modules, in
108 which case you can probably just use the \fBman\fR\|(1) command.
109 .PP
110 If you are looking for a table of contents to the Perl library modules
111 documentation, see the perltoc page.
112 .SH OPTIONS
113 .IX Header "OPTIONS"
114 .IP \fB\-h\fR 5
115 .IX Item "-h"
116 Prints out a brief \fBh\fRelp message.
117 .IP \fB\-D\fR 5
118 .IX Item "-D"
119 \&\fBD\fRescribes search for the item in \fBd\fRetail.
120 .IP \fB\-t\fR 5
121 .IX Item "-t"
122 Display docs using plain \fBt\fRext converter, instead of nroff. This may be faster,
123 but it probably won\*(Aqt look as nice.
124 .IP \fB\-u\fR 5
125 .IX Item "-u"
126 Skip the real Pod formatting, and just show the raw Pod source (\fBU\fRnformatted)
127 .IP "\fB\-m\fR \fImodule\fR" 5
128 .IX Item "-m module"
129 Display the entire module: both code and unformatted pod documentation.
130 This may be useful if the docs don\*(Aqt explain a function in the detail
131 you need, and you\*(Aqd like to inspect the code directly; perldoc will find
132 the file for you and simply hand it off for display.
133 .IP \fB\-l\fR 5
134 .IX Item "-l"
135 Display on\fBl\fRy the file name of the module found.
136 .IP \fB\-U\fR 5
137 .IX Item "-U"
138 When running as the superuser, don\*(Aqt attempt drop privileges for security.
139 This option is implied with \fB\-F\fR.
140 .Sp
141 \&\fBNOTE\fR: Please see the heading SECURITY below for more information.
142 .IP \fB\-F\fR 5
143 .IX Item "-F"
144 Consider arguments as file names; no search in directories will be performed.
145 Implies \fB\-U\fR if run as the superuser.
146 .IP "\fB\-f\fR \fIperlfunc\fR" 5
147 .IX Item "-f perlfunc"
148 The \fB\-f\fR option followed by the name of a perl built\-in function will
149 extract the documentation of this function from perlfunc.
150 .Sp
151 Example:
152 .Sp
153 .Vb 1
154 \& perldoc \-f sprintf
155 .Ve
156 .IP "\fB\-q\fR \fIperlfaq\-search\-regexp\fR" 5
157 .IX Item "-q perlfaq-search-regexp"
158 The \fB\-q\fR option takes a regular expression as an argument. It will search
159 the \fBq\fRuestion headings in perlfaq[1\-9] and print the entries matching
160 the regular expression.
161 .Sp
162 Example:
163 .Sp
164 .Vb 1
165 \& perldoc \-q shuffle
166 .Ve
167 .IP "\fB\-a\fR \fIperlapifunc\fR" 5
168 .IX Item "-a perlapifunc"
169 The \fB\-a\fR option followed by the name of a perl api function will
170 extract the documentation of this function from perlapi.
171 .Sp
172 Example:
173 .Sp
174 .Vb 1
175 \& perldoc \-a newHV
176 .Ve
177 .IP "\fB\-v\fR \fIperlvar\fR" 5
178 .IX Item "-v perlvar"
179 The \fB\-v\fR option followed by the name of a Perl predefined variable will
180 extract the documentation of this variable from perlvar.
181 .Sp
182 Examples:
183 .Sp
184 .Vb 3
185 \& perldoc \-v \*(Aq$"\*(Aq
186 \& perldoc \-v @+
187 \& perldoc \-v DATA
188 .Ve
189 .IP \fB\-T\fR 5
190 .IX Item "-T"
191 This specifies that the output is not to be sent to a pager, but is to
192 be sent directly to STDOUT.
193 .IP "\fB\-d\fR \fIdestination\-filename\fR" 5
194 .IX Item "-d destination-filename"
195 This specifies that the output is to be sent neither to a pager nor
196 to STDOUT, but is to be saved to the specified filename. Example:
197 \&\f(CW\*(C`perldoc \-oLaTeX \-dtextwrapdocs.tex Text::Wrap\*(C'\fR
198 .IP "\fB\-o\fR \fIoutput\-formatname\fR" 5
199 .IX Item "-o output-formatname"
200 This specifies that you want Perldoc to try using a Pod\-formatting
201 class for the output format that you specify. For example:
202 \&\f(CW\*(C`\-oman\*(C'\fR. This is actually just a wrapper around the \f(CW\*(C`\-M\*(C'\fR switch;
203 using \f(CW\*(C`\-o\fR\f(CIformatname\fR\f(CW\*(C'\fR just looks for a loadable class by adding
204 that format name (with different capitalizations) to the end of
205 different classname prefixes.
206 .Sp
207 For example, \f(CW\*(C`\-oLaTeX\*(C'\fR currently tries all of the following classes:
208 Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
209 Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
210 Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
211 Pod::LATEX.
212 .IP "\fB\-M\fR \fImodule\-name\fR" 5
213 .IX Item "-M module-name"
214 This specifies the module that you want to try using for formatting the
215 pod. The class must at least provide a \f(CW\*(C`parse_from_file\*(C'\fR method.
216 For example: \f(CW\*(C`perldoc \-MPod::Perldoc::ToChecker\*(C'\fR.
217 .Sp
218 You can specify several classes to try by joining them with commas
219 or semicolons, as in \f(CW\*(C`\-MTk::SuperPod;Tk::Pod\*(C'\fR.
220 .IP "\fB\-w\fR \fIoption:value\fR or \fB\-w\fR \fIoption\fR" 5
221 .IX Item "-w option:value or -w option"
222 This specifies an option to call the formatter \fBw\fRith. For example,
223 \&\f(CW\*(C`\-w textsize:15\*(C'\fR will call
224 \&\f(CW\*(C`$formatter\->textsize(15)\*(C'\fR on the formatter object before it is
225 used to format the object. For this to be valid, the formatter class
226 must provide such a method, and the value you pass should be valid.
227 (So if \f(CW\*(C`textsize\*(C'\fR expects an integer, and you do \f(CW\*(C`\-w textsize:big\*(C'\fR,
228 expect trouble.)
229 .Sp
230 You can use \f(CW\*(C`\-w optionname\*(C'\fR (without a value) as shorthand for
231 \&\f(CW\*(C`\-w optionname:\fR\f(CITRUE\fR\f(CW\*(C'\fR. This is presumably useful in cases of on/off
232 features like: \f(CW\*(C`\-w page_numbering\*(C'\fR.
233 .Sp
234 You can use an "=" instead of the ":", as in: \f(CW\*(C`\-w textsize=15\*(C'\fR. This
235 might be more (or less) convenient, depending on what shell you use.
236 .IP \fB\-X\fR 5
237 .IX Item "-X"
238 Use an index if it is present. The \fB\-X\fR option looks for an entry
239 whose basename matches the name given on the command line in the file
240 \&\f(CW\*(C`$Config{archlib}/pod.idx\*(C'\fR. The \fIpod.idx\fR file should contain fully
241 qualified filenames, one per line.
242 .IP "\fB\-L\fR \fIlanguage_code\fR" 5
243 .IX Item "-L language_code"
244 This allows one to specify the \fIlanguage code\fR for the desired language
245 translation. If the \f(CW\*(C`POD2::<language_code>\*(C'\fR package isn\*(Aqt
246 installed in your system, the switch is ignored.
247 All available translation packages are to be found under the \f(CW\*(C`POD2::\*(C'\fR
248 namespace. See POD2::IT (or POD2::FR) to see how to create new
249 localized \f(CW\*(C`POD2::*\*(C'\fR documentation packages and integrate them into
250 Pod::Perldoc.
251 .IP \fBPageName|ModuleName|ProgramName|URL\fR 5
252 .IX Item "PageName|ModuleName|ProgramName|URL"
253 The item you want to look up. Nested modules (such as \f(CW\*(C`File::Basename\*(C'\fR)
254 are specified either as \f(CW\*(C`File::Basename\*(C'\fR or \f(CW\*(C`File/Basename\*(C'\fR. You may also
255 give a descriptive name of a page, such as \f(CW\*(C`perlfunc\*(C'\fR. For URLs, HTTP and
256 HTTPS are the only kind currently supported.
257 .Sp
258 For simple names like \*(Aqfoo\*(Aq, when the normal search fails to find
259 a matching page, a search with the "perl" prefix is tried as well.
260 So "perldoc intro" is enough to find/render "perlintro.pod".
261 .IP "\fB\-n\fR \fIsome\-formatter\fR" 5
262 .IX Item "-n some-formatter"
263 Specify replacement for groff
264 .IP \fB\-r\fR 5
265 .IX Item "-r"
266 Recursive search.
267 .IP \fB\-i\fR 5
268 .IX Item "-i"
269 Ignore case.
270 .IP \fB\-V\fR 5
271 .IX Item "-V"
272 Displays the version of perldoc you\*(Aqre running.
273 .SH SECURITY
274 .IX Header "SECURITY"
275 Because \fBperldoc\fR does not run properly tainted, and is known to
276 have security issues, when run as the superuser it will attempt to
277 drop privileges by setting the effective and real IDs to nobody\*(Aqs
278 or nouser\*(Aqs account, or \-2 if unavailable. If it cannot relinquish
279 its privileges, it will not run.
280 .PP
281 See the \f(CW\*(C`\-U\*(C'\fR option if you do not want this behavior but \fBbeware\fR
282 that there are significant security risks if you choose to use \f(CW\*(C`\-U\*(C'\fR.
283 .PP
284 Since 3.26, using \f(CW\*(C`\-F\*(C'\fR as the superuser also implies \f(CW\*(C`\-U\*(C'\fR as opening
285 most files and traversing directories requires privileges that are
286 above the nobody/nogroup level.
287 .SH ENVIRONMENT
288 .IX Header "ENVIRONMENT"
289 Any switches in the \f(CW\*(C`PERLDOC\*(C'\fR environment variable will be used before the
290 command line arguments.
291 .PP
292 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,
293 \&\f(CW\*(C`\-oxml\*(C'\fR, and so on, depending on what modules you have on hand; or
294 the formatter class may be specified exactly with \f(CW\*(C`\-MPod::Perldoc::ToTerm\*(C'\fR
295 or the like.
296 .PP
297 \&\f(CW\*(C`perldoc\*(C'\fR also searches directories
298 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
299 defined) and \f(CW\*(C`PATH\*(C'\fR environment variables.
300 (The latter is so that embedded pods for executables, such as
301 \&\f(CW\*(C`perldoc\*(C'\fR itself, are available.)
302 .PP
303 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
304 will add \f(CW\*(C`.\*(C'\fR and \f(CW\*(C`lib\*(C'\fR first to its search path, and as long as you\*(Aqre not
305 the superuser will add \f(CW\*(C`blib\*(C'\fR too. This is really helpful if you\*(Aqre working
306 inside of a build directory and want to read through the docs even if you
307 have a version of a module previously installed.
308 .PP
309 \&\f(CW\*(C`perldoc\*(C'\fR will use, in order of preference, the pager defined in
310 \&\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
311 on its own. (\f(CW\*(C`MANPAGER\*(C'\fR is not used if \f(CW\*(C`perldoc\*(C'\fR was told to display
312 plain text or unformatted pod.)
313 .PP
314 When using perldoc in it\*(Aqs \f(CW\*(C`\-m\*(C'\fR mode (display module source code),
315 \&\f(CW\*(C`perldoc\*(C'\fR will attempt to use the pager set in \f(CW\*(C`PERLDOC_SRC_PAGER\*(C'\fR.
316 A useful setting for this command is your favorite editor as in
317 \&\f(CW\*(C`/usr/bin/nano\*(C'\fR. (Don\*(Aqt judge me.)
318 .PP
319 One useful value for \f(CW\*(C`PERLDOC_PAGER\*(C'\fR is \f(CW\*(C`less \-+C \-E\*(C'\fR.
320 .PP
321 Having PERLDOCDEBUG set to a positive integer will make perldoc emit
322 even more descriptive output than the \f(CW\*(C`\-D\*(C'\fR switch does; the higher the
323 number, the more it emits.
324 .SH CHANGES
325 .IX Header "CHANGES"
326 Up to 3.14_05, the switch \fB\-v\fR was used to produce verbose
327 messages of \fBperldoc\fR operation, which is now enabled by \fB\-D\fR.
328 .SH "SEE ALSO"
329 .IX Header "SEE ALSO"
330 perlpod, Pod::Perldoc
331 .SH AUTHOR
332 .IX Header "AUTHOR"
333 Current maintainer: Mark Allen \f(CW\*(C`<[email protected]>\*(C'\fR
334 .PP
335 Past contributors are:
336 brian d foy \f(CW\*(C`<[email protected]>\*(C'\fR
337 Adriano R. Ferreira \f(CW\*(C`<[email protected]>\*(C'\fR,
338 Sean M. Burke \f(CW\*(C`<[email protected]>\*(C'\fR,
339 Kenneth Albanowski \f(CW\*(C`<[email protected]>\*(C'\fR,
340 Andy Dougherty \f(CW\*(C`<[email protected]>\*(C'\fR,
341 and many others.