regcomp.c: Move [] inversion optimization
[perl.git] / pod / perldoc.pod
1
2 =head1 NAME
3
4 perldoc - Look up Perl documentation in Pod format.
5
6 =head1 SYNOPSIS
7
8 B<perldoc> [B<-h>] [B<-D>] [B<-t>] [B<-u>] [B<-m>] [B<-l>] [B<-F>]
9 [B<-i>] [B<-V>] [B<-T>] [B<-r>]
10 [B<-dI<destination_file>>]
11 [B<-oI<formatname>>]
12 [B<-MI<FormatterClassName>>]
13 [B<-wI<formatteroption:value>>]
14 [B<-n>I<nroff-replacement>]
15 [B<-X>]
16 [B<-L> I<language_code>]
17 PageName|ModuleName|ProgramName
18
19 B<perldoc> B<-f> BuiltinFunction
20
21 B<perldoc> B<-L> it B<-f> BuiltinFunction
22
23 B<perldoc> B<-q> FAQ Keyword
24
25 B<perldoc> B<-L> fr B<-q> FAQ Keyword
26
27 B<perldoc> B<-v> PerlVariable
28
29 See below for more description of the switches.
30
31 =head1 DESCRIPTION
32
33 I<perldoc> looks up a piece of documentation in .pod format that is embedded
34 in the perl installation tree or in a perl script, and displays it via
35 C<pod2man | nroff -man | $PAGER>. (In addition, if running under HP-UX,
36 C<col -x> will be used.) This is primarily used for the documentation for
37 the perl library modules.
38
39 Your system may also have man pages installed for those modules, in
40 which case you can probably just use the man(1) command.
41
42 If you are looking for a table of contents to the Perl library modules
43 documentation, see the L<perltoc> page.
44
45 =head1 OPTIONS
46
47 =over 5
48
49 =item B<-h>
50
51 Prints out a brief B<h>elp message.
52
53 =item B<-D>
54
55 B<D>escribes search for the item in B<d>etail.
56
57 =item B<-t>
58
59 Display docs using plain B<t>ext converter, instead of nroff. This may be faster,
60 but it probably won't look as nice.
61
62 =item B<-u>
63
64 Skip the real Pod formatting, and just show the raw Pod source (B<U>nformatted)
65
66 =item B<-m> I<module>
67
68 Display the entire module: both code and unformatted pod documentation.
69 This may be useful if the docs don't explain a function in the detail
70 you need, and you'd like to inspect the code directly; perldoc will find
71 the file for you and simply hand it off for display.
72
73 =item B<-l>
74
75 Display onB<l>y the file name of the module found.
76
77 =item B<-F>
78
79 Consider arguments as file names; no search in directories will be performed.
80
81 =item B<-f> I<perlfunc>
82
83 The B<-f> option followed by the name of a perl built in function will
84 extract the documentation of this function from L<perlfunc>.
85
86 Example:
87
88       perldoc -f sprintf
89
90
91 =item B<-q> I<perlfaq-search-regexp>
92
93 The B<-q> option takes a regular expression as an argument.  It will search
94 the B<q>uestion headings in perlfaq[1-9] and print the entries matching
95 the regular expression.
96
97 Example:
98
99      perldoc -q shuffle
100
101
102 =item B<-v> I<perlvar>
103
104 The B<-v> option followed by the name of a Perl predefined variable will
105 extract the documentation of this variable from L<perlvar>.
106
107 Examples:
108
109      perldoc -v '$"'
110      perldoc -v @+
111      perldoc -v DATA
112
113
114 =item B<-T>
115
116 This specifies that the output is not to be sent to a pager, but is to
117 be sent right to STDOUT.
118
119 =item B<-d> I<destination-filename>
120
121 This specifies that the output is to be sent neither to a pager nor
122 to STDOUT, but is to be saved to the specified filename.  Example:
123 C<perldoc -oLaTeX -dtextwrapdocs.tex Text::Wrap>
124
125 =item B<-o> I<output-formatname>
126
127 This specifies that you want Perldoc to try using a Pod-formatting
128 class for the output format that you specify.  For example:
129 C<-oman>.  This is actually just a wrapper around the C<-M> switch;
130 using C<-oI<formatname>> just looks for a loadable class by adding
131 that format name (with different capitalizations) to the end of
132 different classname prefixes.
133
134 For example, C<-oLaTeX> currently tries all of the following classes:
135 Pod::Perldoc::ToLaTeX Pod::Perldoc::Tolatex Pod::Perldoc::ToLatex
136 Pod::Perldoc::ToLATEX Pod::Simple::LaTeX Pod::Simple::latex
137 Pod::Simple::Latex Pod::Simple::LATEX Pod::LaTeX Pod::latex Pod::Latex
138 Pod::LATEX.
139
140 =item B<-M> I<module-name>
141
142 This specifies the module that you want to try using for formatting the
143 pod.  The class must at least provide a C<parse_from_file> method.
144 For example: C<perldoc -MPod::Perldoc::ToChecker>.
145
146 You can specify several classes to try by joining them with commas
147 or semicolons, as in C<-MTk::SuperPod;Tk::Pod>.
148
149 =item B<-w> I<option:value> or B<-w> I<option> 
150
151 This specifies an option to call the formatter B<w>ith.  For example,
152 C<-w textsize:15> will call
153 C<< $formatter->textsize(15) >> on the formatter object before it is
154 used to format the object.  For this to be valid, the formatter class
155 must provide such a method, and the value you pass should be valid.
156 (So if C<textsize> expects an integer, and you do C<-w textsize:big>,
157 expect trouble.)
158
159 You can use C<-w optionname> (without a value) as shorthand for
160 C<-w optionname:I<TRUE>>.  This is presumably useful in cases of on/off
161 features like: C<-w page_numbering>.
162
163 You can use a "=" instead of the ":", as in: C<-w textsize=15>.  This
164 might be more (or less) convenient, depending on what shell you use.
165
166 =item B<-X>
167
168 Use an index if it is present. The B<-X> option looks for an entry
169 whose basename matches the name given on the command line in the file
170 C<$Config{archlib}/pod.idx>. The F<pod.idx> file should contain fully
171 qualified filenames, one per line.
172
173 =item B<-L> I<language_code>
174
175 This allows to specify the I<language code> for desired language translation.
176 If C<POD2::E<lt>language_codeE<gt>> package doesn't exist (or isn't installed
177 in your system), the switch will be ignored. 
178 All available translation packages should be found under the C<POD2::>
179 namespace. See L<POD2::IT> (or L<POD2::FR>) in order to see how to create and
180 integrate new localized C<POD2::*> pod documentation packages in
181 L<Pod::Perldoc>.
182
183 =item B<PageName|ModuleName|ProgramName>
184
185 The item you want to look up.  Nested modules (such as C<File::Basename>)
186 are specified either as C<File::Basename> or C<File/Basename>.  You may also
187 give a descriptive name of a page, such as C<perlfunc>.
188
189 For simple names like 'foo', when the normal search fails to find
190 a matching page, a search with the "perl" prefix is tried as well.
191 So "perldoc intro" is enough to find/render "perlintro.pod".
192
193 =item B<-n> I<some-formatter>
194
195 Specify replacement for nroff
196
197 =item B<-r>
198
199 Recursive search.
200
201 =item B<-i>
202
203 Ignore case.
204
205 =item B<-V>
206
207 Displays the version of perldoc you're running.
208
209 =back
210
211
212
213 =head1 SECURITY
214
215 Because B<perldoc> does not run properly tainted, and is known to
216 have security issues, when run as the superuser it will attempt to
217 drop privileges by setting the effective and real IDs to nobody's
218 or nouser's account, or -2 if unavailable.  If it cannot relinquish
219 its privileges, it will not run.  
220
221
222 =head1 ENVIRONMENT
223
224 Any switches in the C<PERLDOC> environment variable will be used before the
225 command line arguments.
226
227 Useful values for C<PERLDOC> include C<-oman>, C<-otext>, C<-otk>, C<-ortf>,
228 C<-oxml>, and so on, depending on what modules you have on hand; or
229 exactly specify the formatter class with C<-MPod::Perldoc::ToMan>
230 or the like.
231
232 C<perldoc> also searches directories
233 specified by the C<PERL5LIB> (or C<PERLLIB> if C<PERL5LIB> is not
234 defined) and C<PATH> environment variables.
235 (The latter is so that embedded pods for executables, such as
236 C<perldoc> itself, are available.)
237
238 C<perldoc> will use, in order of preference, the pager defined in
239 C<PERLDOC_PAGER>, C<MANPAGER>, or C<PAGER> before trying to find a pager
240 on its own. (C<MANPAGER> is not used if C<perldoc> was told to display
241 plain text or unformatted pod.)
242
243 One useful value for C<PERLDOC_PAGER> is C<less -+C -E>.
244
245 Having PERLDOCDEBUG set to a positive integer will make perldoc emit
246 even more descriptive output than the C<-v> switch does; the higher the
247 number, the more it emits.
248
249
250 =head1 CHANGES
251
252 Up to 3.14_05, the switch B<-v> was used to produce verbose
253 messages of B<perldoc> operation, which is now enabled by B<-D>.
254
255 =head1 SEE ALSO
256
257 L<perlpod>, L<Pod::Perldoc>
258
259 =head1 AUTHOR
260
261 Current maintainer: Adriano R. Ferreira <ferreira@cpan.org>
262
263 Past contributors are:
264 Sean M. Burke <sburke@cpan.org>,
265 Kenneth Albanowski <kjahds@kjahds.com>,
266 Andy Dougherty  <doughera@lafcol.lafayette.edu>,
267 and many others.
268
269 =cut
270