Debian Codegraph @

upstream/debian-unstable/man1/perldoc.1

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