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