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