1PERLDOC(1)            User Contributed Perl Documentation           PERLDOC(1)
2
3
4

NAME

6       perldoc - Look up Perl documentation in Pod format.
7

SYNOPSIS

9           perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-U] [-F]
10               [-i] [-V] [-T] [-r]
11               [-d destination_file]
12               [-o formatname]
13               [-M FormatterClassName]
14               [-w formatteroption:value]
15               [-n nroff-replacement]
16               [-X]
17               [-L language_code]
18               PageName|ModuleName|ProgramName|URL
19
20       Examples:
21
22           perldoc -f BuiltinFunction
23
24           perldoc -L it -f BuiltinFunction
25
26           perldoc -q FAQ Keyword
27
28           perldoc -L fr -q FAQ Keyword
29
30           perldoc -v PerlVariable
31
32           perldoc -a PerlAPI
33
34       See below for more description of the switches.
35

DESCRIPTION

37       perldoc looks up documentation in .pod format that is embedded in the
38       perl installation tree or in a perl script, and displays it using a
39       variety of formatters.  This is primarily used for the documentation
40       for the perl library modules.
41
42       Your system may also have man pages installed for those modules, in
43       which case you can probably just use the man(1) command.
44
45       If you are looking for a table of contents to the Perl library modules
46       documentation, see the perltoc page.
47

OPTIONS

49       -h   Prints out a brief help message.
50
51       -D   Describes search for the item in detail.
52
53       -t   Display docs using plain text converter, instead of nroff. This
54            may be faster, but it probably won't look as nice.
55
56       -u   Skip the real Pod formatting, and just show the raw Pod source
57            (Unformatted)
58
59       -m module
60            Display the entire module: both code and unformatted pod
61            documentation.  This may be useful if the docs don't explain a
62            function in the detail you need, and you'd like to inspect the
63            code directly; perldoc will find the file for you and simply hand
64            it off for display.
65
66       -l   Display only the file name of the module found.
67
68       -U   When running as the superuser, don't attempt drop privileges for
69            security.  This option is implied with -F.
70
71            NOTE: Please see the heading SECURITY below for more information.
72
73       -F   Consider arguments as file names; no search in directories will be
74            performed.  Implies -U if run as the superuser.
75
76       -f perlfunc
77            The -f option followed by the name of a perl built-in function
78            will extract the documentation of this function from perlfunc.
79
80            Example:
81
82                  perldoc -f sprintf
83
84       -q perlfaq-search-regexp
85            The -q option takes a regular expression as an argument.  It will
86            search the question headings in perlfaq[1-9] and print the entries
87            matching the regular expression.
88
89            Example:
90
91                 perldoc -q shuffle
92
93       -a perlapifunc
94            The -a option followed by the name of a perl api function will
95            extract the documentation of this function from perlapi.
96
97            Example:
98
99                 perldoc -a newHV
100
101       -v perlvar
102            The -v option followed by the name of a Perl predefined variable
103            will extract the documentation of this variable from perlvar.
104
105            Examples:
106
107                 perldoc -v '$"'
108                 perldoc -v @+
109                 perldoc -v DATA
110
111       -T   This specifies that the output is not to be sent to a pager, but
112            is to be sent directly to STDOUT.
113
114       -d destination-filename
115            This specifies that the output is to be sent neither to a pager
116            nor to STDOUT, but is to be saved to the specified filename.
117            Example: "perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap"
118
119       -o output-formatname
120            This specifies that you want Perldoc to try using a Pod-formatting
121            class for the output format that you specify.  For example:
122            "-oman".  This is actually just a wrapper around the "-M" switch;
123            using "-oformatname" just looks for a loadable class by adding
124            that format name (with different capitalizations) to the end of
125            different classname prefixes.
126
127            For example, "-oLaTeX" currently tries all of the following
128            classes: Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex
129            Pod::Perldoc::ToLatex Pod::Perldoc::ToLATEX Pod::Simple::LaTeX
130            Pod::Simple::latex Pod::Simple::Latex Pod::Simple::LATEX
131            Pod::LaTeX Pod::latex Pod::Latex Pod::LATEX.
132
133       -M module-name
134            This specifies the module that you want to try using for
135            formatting the pod.  The class must at least provide a
136            "parse_from_file" method.  For example: "perldoc
137            -MPod::Perldoc::ToChecker".
138
139            You can specify several classes to try by joining them with commas
140            or semicolons, as in "-MTk::SuperPod;Tk::Pod".
141
142       -w option:value or -w option
143            This specifies an option to call the formatter with.  For example,
144            "-w textsize:15" will call "$formatter->textsize(15)" on the
145            formatter object before it is used to format the object.  For this
146            to be valid, the formatter class must provide such a method, and
147            the value you pass should be valid.  (So if "textsize" expects an
148            integer, and you do "-w textsize:big", expect trouble.)
149
150            You can use "-w optionname" (without a value) as shorthand for "-w
151            optionname:TRUE".  This is presumably useful in cases of on/off
152            features like: "-w page_numbering".
153
154            You can use an "=" instead of the ":", as in: "-w textsize=15".
155            This might be more (or less) convenient, depending on what shell
156            you use.
157
158       -X   Use an index if it is present. The -X option looks for an entry
159            whose basename matches the name given on the command line in the
160            file "$Config{archlib}/pod.idx". The pod.idx file should contain
161            fully qualified filenames, one per line.
162
163       -L language_code
164            This allows one to specify the language code for the desired
165            language translation. If the "POD2::<language_code>" package isn't
166            installed in your system, the switch is ignored.  All available
167            translation packages are to be found under the "POD2::" namespace.
168            See POD2::IT (or POD2::FR) to see how to create new localized
169            "POD2::*" documentation packages and integrate them into
170            Pod::Perldoc.
171
172       PageName|ModuleName|ProgramName|URL
173            The item you want to look up.  Nested modules (such as
174            "File::Basename") are specified either as "File::Basename" or
175            "File/Basename".  You may also give a descriptive name of a page,
176            such as "perlfunc".  For URLs, HTTP and HTTPS are the only kind
177            currently supported.
178
179            For simple names like 'foo', when the normal search fails to find
180            a matching page, a search with the "perl" prefix is tried as well.
181            So "perldoc intro" is enough to find/render "perlintro.pod".
182
183       -n some-formatter
184            Specify replacement for groff
185
186       -r   Recursive search.
187
188       -i   Ignore case.
189
190       -V   Displays the version of perldoc you're running.
191

SECURITY

193       Because perldoc does not run properly tainted, and is known to have
194       security issues, when run as the superuser it will attempt to drop
195       privileges by setting the effective and real IDs to nobody's or
196       nouser's account, or -2 if unavailable.  If it cannot relinquish its
197       privileges, it will not run.
198
199       See the "-U" option if you do not want this behavior but beware that
200       there are significant security risks if you choose to use "-U".
201
202       Since 3.26, using "-F" as the superuser also implies "-U" as opening
203       most files and traversing directories requires privileges that are
204       above the nobody/nogroup level.
205

ENVIRONMENT

207       Any switches in the "PERLDOC" environment variable will be used before
208       the command line arguments.
209
210       Useful values for "PERLDOC" include "-oterm", "-otext", "-ortf",
211       "-oxml", and so on, depending on what modules you have on hand; or the
212       formatter class may be specified exactly with "-MPod::Perldoc::ToTerm"
213       or the like.
214
215       "perldoc" also searches directories specified by the "PERL5LIB" (or
216       "PERLLIB" if "PERL5LIB" is not defined) and "PATH" environment
217       variables.  (The latter is so that embedded pods for executables, such
218       as "perldoc" itself, are available.)
219
220       In directories where either "Makefile.PL" or "Build.PL" exist,
221       "perldoc" will add "." and "lib" first to its search path, and as long
222       as you're not the superuser will add "blib" too.  This is really
223       helpful if you're working inside of a build directory and want to read
224       through the docs even if you have a version of a module previously
225       installed.
226
227       "perldoc" will use, in order of preference, the pager defined in
228       "PERLDOC_PAGER", "MANPAGER", or "PAGER" before trying to find a pager
229       on its own. ("MANPAGER" is not used if "perldoc" was told to display
230       plain text or unformatted pod.)
231
232       When using perldoc in it's "-m" mode (display module source code),
233       "perldoc" will attempt to use the pager set in "PERLDOC_SRC_PAGER".  A
234       useful setting for this command is your favorite editor as in
235       "/usr/bin/nano". (Don't judge me.)
236
237       One useful value for "PERLDOC_PAGER" is "less -+C -E".
238
239       Having PERLDOCDEBUG set to a positive integer will make perldoc emit
240       even more descriptive output than the "-D" switch does; the higher the
241       number, the more it emits.
242

CHANGES

244       Up to 3.14_05, the switch -v was used to produce verbose messages of
245       perldoc operation, which is now enabled by -D.
246

SEE ALSO

248       perlpod, Pod::Perldoc
249

AUTHOR

251       Current maintainer: Mark Allen "<mallen@cpan.org>"
252
253       Past contributors are: brian d foy "<bdfoy@cpan.org>" Adriano R.
254       Ferreira "<ferreira@cpan.org>", Sean M. Burke "<sburke@cpan.org>",
255       Kenneth Albanowski "<kjahds@kjahds.com>", Andy Dougherty
256       "<doughera@lafcol.lafayette.edu>", and many others.
257
258
259
260perl v5.34.0                      2021-07-22                        PERLDOC(1)
Impressum