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