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