| 1 | =head1 NAME
|
|---|
| 2 |
|
|---|
| 3 | perlutil - utilities packaged with the Perl distribution
|
|---|
| 4 |
|
|---|
| 5 | =head1 DESCRIPTION
|
|---|
| 6 |
|
|---|
| 7 | Along with the Perl interpreter itself, the Perl distribution installs a
|
|---|
| 8 | range of utilities on your system. There are also several utilities
|
|---|
| 9 | which are used by the Perl distribution itself as part of the install
|
|---|
| 10 | process. This document exists to list all of these utilities, explain
|
|---|
| 11 | what they are for and provide pointers to each module's documentation,
|
|---|
| 12 | if appropriate.
|
|---|
| 13 |
|
|---|
| 14 | =head2 DOCUMENTATION
|
|---|
| 15 |
|
|---|
| 16 | =over 3
|
|---|
| 17 |
|
|---|
| 18 | =item L<perldoc|perldoc>
|
|---|
| 19 |
|
|---|
| 20 | The main interface to Perl's documentation is C<perldoc>, although
|
|---|
| 21 | if you're reading this, it's more than likely that you've already found
|
|---|
| 22 | it. F<perldoc> will extract and format the documentation from any file
|
|---|
| 23 | in the current directory, any Perl module installed on the system, or
|
|---|
| 24 | any of the standard documentation pages, such as this one. Use
|
|---|
| 25 | C<perldoc E<lt>nameE<gt>> to get information on any of the utilities
|
|---|
| 26 | described in this document.
|
|---|
| 27 |
|
|---|
| 28 | =item L<pod2man|pod2man> and L<pod2text|pod2text>
|
|---|
| 29 |
|
|---|
| 30 | If it's run from a terminal, F<perldoc> will usually call F<pod2man> to
|
|---|
| 31 | translate POD (Plain Old Documentation - see L<perlpod> for an
|
|---|
| 32 | explanation) into a manpage, and then run F<man> to display it; if
|
|---|
| 33 | F<man> isn't available, F<pod2text> will be used instead and the output
|
|---|
| 34 | piped through your favourite pager.
|
|---|
| 35 |
|
|---|
| 36 | =item L<pod2html|pod2html> and L<pod2latex|pod2latex>
|
|---|
| 37 |
|
|---|
| 38 | As well as these two, there are two other converters: F<pod2html> will
|
|---|
| 39 | produce HTML pages from POD, and F<pod2latex>, which produces LaTeX
|
|---|
| 40 | files.
|
|---|
| 41 |
|
|---|
| 42 | =item L<pod2usage|pod2usage>
|
|---|
| 43 |
|
|---|
| 44 | If you just want to know how to use the utilities described here,
|
|---|
| 45 | F<pod2usage> will just extract the "USAGE" section; some of
|
|---|
| 46 | the utilities will automatically call F<pod2usage> on themselves when
|
|---|
| 47 | you call them with C<-help>.
|
|---|
| 48 |
|
|---|
| 49 | =item L<podselect|podselect>
|
|---|
| 50 |
|
|---|
| 51 | F<pod2usage> is a special case of F<podselect>, a utility to extract
|
|---|
| 52 | named sections from documents written in POD. For instance, while
|
|---|
| 53 | utilities have "USAGE" sections, Perl modules usually have "SYNOPSIS"
|
|---|
| 54 | sections: C<podselect -s "SYNOPSIS" ...> will extract this section for
|
|---|
| 55 | a given file.
|
|---|
| 56 |
|
|---|
| 57 | =item L<podchecker|podchecker>
|
|---|
| 58 |
|
|---|
| 59 | If you're writing your own documentation in POD, the F<podchecker>
|
|---|
| 60 | utility will look for errors in your markup.
|
|---|
| 61 |
|
|---|
| 62 | =item L<splain|splain>
|
|---|
| 63 |
|
|---|
| 64 | F<splain> is an interface to L<perldiag> - paste in your error message
|
|---|
| 65 | to it, and it'll explain it for you.
|
|---|
| 66 |
|
|---|
| 67 | =item L<roffitall|roffitall>
|
|---|
| 68 |
|
|---|
| 69 | The C<roffitall> utility is not installed on your system but lives in
|
|---|
| 70 | the F<pod/> directory of your Perl source kit; it converts all the
|
|---|
| 71 | documentation from the distribution to F<*roff> format, and produces a
|
|---|
| 72 | typeset PostScript or text file of the whole lot.
|
|---|
| 73 |
|
|---|
| 74 | =back
|
|---|
| 75 |
|
|---|
| 76 | =head2 CONVERTORS
|
|---|
| 77 |
|
|---|
| 78 | To help you convert legacy programs to Perl, we've included three
|
|---|
| 79 | conversion filters:
|
|---|
| 80 |
|
|---|
| 81 | =over 3
|
|---|
| 82 |
|
|---|
| 83 | =item L<a2p|a2p>
|
|---|
| 84 |
|
|---|
| 85 | F<a2p> converts F<awk> scripts to Perl programs; for example, C<a2p -F:>
|
|---|
| 86 | on the simple F<awk> script C<{print $2}> will produce a Perl program
|
|---|
| 87 | based around this code:
|
|---|
| 88 |
|
|---|
| 89 | while (<>) {
|
|---|
| 90 | ($Fld1,$Fld2) = split(/[:\n]/, $_, 9999);
|
|---|
| 91 | print $Fld2;
|
|---|
| 92 | }
|
|---|
| 93 |
|
|---|
| 94 | =item L<s2p|s2p>
|
|---|
| 95 |
|
|---|
| 96 | Similarly, F<s2p> converts F<sed> scripts to Perl programs. F<s2p> run
|
|---|
| 97 | on C<s/foo/bar> will produce a Perl program based around this:
|
|---|
| 98 |
|
|---|
| 99 | while (<>) {
|
|---|
|
|---|
