1PERLDOC(1) Perl Programmers Reference Guide PERLDOC(1)
2
6 perldoc - Look up Perl documentation in Pod format.
7
9 perldoc [-h] [-D] [-t] [-u] [-m] [-l] [-F] [-i] [-V] [-T] [-r]
10 [-ddestination_file] [-oformatname] [-MFormatterClassName]
11 [-wformatteroption:value] [-nnroff-replacement] [-X] [-L language_code]
12 PageName|ModuleName|ProgramName
13 perldoc -f BuiltinFunction
15 perldoc -L it -f BuiltinFunction
17 perldoc -q FAQ Keyword
19 perldoc -L fr -q FAQ Keyword
21 perldoc -v PerlVariable
23 See below for more description of the switches.
25
27 perldoc looks up a piece of documentation in .pod format that is
28 embedded in the perl installation tree or in a perl script, and
29 displays it via "pod2man | nroff -man | $PAGER". (In addition, if
30 running under HP-UX, "col -x" will be used.) This is primarily used for
31 the documentation for the perl library modules.
32 Your system may also have man pages installed for those modules, in
34 which case you can probably just use the man(1) command.
35 If you are looking for a table of contents to the Perl library modules
37 documentation, see the perltoc page.
38
40 -h Prints out a brief help message.
41 -D Describes search for the item in detail.
43 -t Display docs using plain text converter, instead of nroff. This
45 may be faster, but it probably won't look as nice.
46 -u Skip the real Pod formatting, and just show the raw Pod source
48 (Unformatted)
49 -m module
51 Display the entire module: both code and unformatted pod
52 documentation. This may be useful if the docs don't explain a
53 function in the detail you need, and you'd like to inspect the
54 code directly; perldoc will find the file for you and simply hand
55 it off for display.
56 -l Display only the file name of the module found.
58 -F Consider arguments as file names; no search in directories will be
60 performed.
61 -f perlfunc
63 The -f option followed by the name of a perl built in function
64 will extract the documentation of this function from perlfunc.
65 Example:
67 perldoc -f sprintf
69 -q perlfaq-search-regexp
71 The -q option takes a regular expression as an argument. It will
72 search the question headings in perlfaq[1-9] and print the entries
73 matching the regular expression.
74 Example:
76 perldoc -q shuffle
78 -v perlvar
80 The -v option followed by the name of a Perl predefined variable
81 will extract the documentation of this variable from perlvar.
82 Examples:
84 perldoc -v '$"'
86 perldoc -v @+
87 perldoc -v DATA
88 -T This specifies that the output is not to be sent to a pager, but
90 is to be sent right to STDOUT.
91 -d destination-filename
93 This specifies that the output is to be sent neither to a pager
94 nor to STDOUT, but is to be saved to the specified filename.
95 Example: "perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap"
96 -o output-formatname
98 This specifies that you want Perldoc to try using a Pod-formatting
99 class for the output format that you specify. For example:
100 "-oman". This is actually just a wrapper around the "-M" switch;
101 using "-oformatname" just looks for a loadable class by adding
102 that format name (with different capitalizations) to the end of
103 different classname prefixes.
104 For example, "-oLaTeX" currently tries all of the following
106 classes: Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex
107 Pod::Perldoc::ToLatex Pod::Perldoc::ToLATEX Pod::Simple::LaTeX
108 Pod::Simple::latex Pod::Simple::Latex Pod::Simple::LATEX
109 Pod::LaTeX Pod::latex Pod::Latex Pod::LATEX.
110 -M module-name
112 This specifies the module that you want to try using for
113 formatting the pod. The class must at least provide a
114 "parse_from_file" method. For example: "perldoc
115 -MPod::Perldoc::ToChecker".
116 You can specify several classes to try by joining them with commas
118 or semicolons, as in "-MTk::SuperPod;Tk::Pod".
119 -w option:value or -w option
121 This specifies an option to call the formatter with. For example,
122 "-w textsize:15" will call "$formatter->textsize(15)" on the
123 formatter object before it is used to format the object. For this
124 to be valid, the formatter class must provide such a method, and
125 the value you pass should be valid. (So if "textsize" expects an
126 integer, and you do "-w textsize:big", expect trouble.)
127 You can use "-w optionname" (without a value) as shorthand for "-w
129 optionname:TRUE". This is presumably useful in cases of on/off
130 features like: "-w page_numbering".
131 You can use a "=" instead of the ":", as in: "-w textsize=15".
133 This might be more (or less) convenient, depending on what shell
134 you use.
135 -X Use an index if it is present. The -X option looks for an entry
137 whose basename matches the name given on the command line in the
138 file "$Config{archlib}/pod.idx". The pod.idx file should contain
139 fully qualified filenames, one per line.
140 -L language_code
142 This allows to specify the language code for desired language
143 translation. If "POD2::<language_code>" package doesn't exist (or
144 isn't installed in your system), the switch will be ignored. All
145 available translation packages should be found under the "POD2::"
146 namespace. See POD2::IT (or POD2::FR) in order to see how to
147 create and integrate new localized "POD2::*" pod documentation
148 packages in Pod::Perldoc.
149 PageName|ModuleName|ProgramName
151 The item you want to look up. Nested modules (such as
152 "File::Basename") are specified either as "File::Basename" or
153 "File/Basename". You may also give a descriptive name of a page,
154 such as "perlfunc".
155 For simple names like 'foo', when the normal search fails to find
157 a matching page, a search with the "perl" prefix is tried as well.
158 So "perldoc intro" is enough to find/render "perlintro.pod".
159 -n some-formatter
161 Specify replacement for nroff
162 -r Recursive search.
164 -i Ignore case.
166 -V Displays the version of perldoc you're running.
168
170 Because perldoc does not run properly tainted, and is known to have
171 security issues, when run as the superuser it will attempt to drop
172 privileges by setting the effective and real IDs to nobody's or
173 nouser's account, or -2 if unavailable. If it cannot relinquish its
174 privileges, it will not run.
175
177 Any switches in the "PERLDOC" environment variable will be used before
178 the command line arguments.
179 Useful values for "PERLDOC" include "-oman", "-otext", "-otk", "-ortf",
181 "-oxml", and so on, depending on what modules you have on hand; or
182 exactly specify the formatter class with "-MPod::Perldoc::ToMan" or the
183 like.
184 "perldoc" also searches directories specified by the "PERL5LIB" (or
186 "PERLLIB" if "PERL5LIB" is not defined) and "PATH" environment
187 variables. (The latter is so that embedded pods for executables, such
188 as "perldoc" itself, are available.)
189 "perldoc" will use, in order of preference, the pager defined in
191 "PERLDOC_PAGER", "MANPAGER", or "PAGER" before trying to find a pager
192 on its own. ("MANPAGER" is not used if "perldoc" was told to display
193 plain text or unformatted pod.)
194 One useful value for "PERLDOC_PAGER" is "less -+C -E".
196 Having PERLDOCDEBUG set to a positive integer will make perldoc emit
198 even more descriptive output than the "-v" switch does; the higher the
199 number, the more it emits.
200
202 Up to 3.14_05, the switch -v was used to produce verbose messages of
203 perldoc operation, which is now enabled by -D.
204
206 perlpod, Pod::Perldoc
207
209 Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
210 Past contributors are: Sean M. Burke <sburke@cpan.org>, Kenneth
212 Albanowski <kjahds@kjahds.com>, Andy Dougherty
213 <doughera@lafcol.lafayette.edu>, and many others.
214perl v5.12.4 2011-06-07 PERLDOC(1)