 |  |
| |
Pod is a simple, but surprisingly capable, text formatter that uses tags to tell a translator how to format the text. The tags serve several purposes:
They tell the formatter how to lay out text on the page.
They provide font and cross-reference information.
They start and stop parsing of code.
The last item is indicative of one of pod's most useful features—that it can be intermixed with Perl code. While it can be difficult to force yourself to go back and write documentation for your code after the fact, with Perl you can simply intermingle the documentation with the code, and do it all at once. It also lets you use the same text as both code documentation and user documentation.
A pod translator reads a file paragraph by paragraph, ignoring text that isn't pod, and converting it to the proper format. Paragraphs are separated by blank lines (not just by newlines). The various translators recognize three kinds of paragraphs:
=cut
They can also be followed by text:
=head2 Second-level head
A blank line signals the end of the command.
=head2 Pod Pod is a simple, but surprisingly capable, text formatter that uses tags to tell a translator how to format the text.
Don't fill this paragraph. It's supposed to look exactly like this on the page. There are blanks at the beginning of each line.
The following paragraph tags are recognized as valid pod commands.
| =back |
=back
Moves left margin back to where it was before the last =over. Ends the innermost =over/=back block of indented text. If there are multiple levels of indent, one =back is needed for each level.
| =begin |
=begin format
Starts a block of text that will be passed directly to a particular formatter rather than being treated as pod. For example:
=begin html
A =begin/=end block is like =for except that it doesn't necessarily apply to a single paragraph.
| =cut |
=cut
Indicates the end of pod text. Tells the compiler that there isn't anymore pod (for now) and to start compiling again.
| =head1 |
=head1 text
text following the tag is formatted as a top-level heading. Generally all uppercase.
| =item |
=item text
Starts a list. Lists should always be inside an over/back block. Many translators use the value of text on the first =item to determine the type of list:
=item * This is the text of the bullet.
=item <HTML> Indicates the beginning of an HTML file
The exact appearance of the output depends on the translator you use, but it will look pretty much like this:
<HTML>
Indicates the beginning of an HTML file| =over |
=over n
Specifies the beginning of a list, in which n indicates the depth of the indent. For example, =over 4 will indent four spaces. Another =over before a =back creates nested lists. The =over tag should be followed by at least one =item.
In addition to the paragraph tags, pod has a set of tags that apply within text, either in a paragraph or a command. These interior sequences are:
|
Sequence |
Function |
||
|---|---|---|---|
|
B<text> |
Makes text bold, usually for switches and programs |
||
|
C<code> |
Literal code |
||
|
E<escape> |
Named character: |
||
|
E<gt> |
Literal > |
||
|
E<lt> |
Literal < |
||
|
E<html> |
Non-numeric HTML entity |
||
|
E<n> |
Character number n, usually an ASCII character |
||
|
F<file> |
Filename |
||
|
I<text> |
Italicize text, usually for emphasis or variables |
||
|
L<name> |
Link (cross-reference) to name: |
||
|
L<name> |
Manpage |
||
|
L<name/ident> |
Item in a manpage |
||
|
L<name/"sec"> |
Section in another manpage |
||
|
L<"sec"> |
Section in this manpage; quotes are optional |
||
|
L</"sec"> |
Same as L<"sec"> |
||
|
S<text> |
text has non-breaking spaces |
||
|
X<index> |
Index entry |
||
|
Z<> |
Zero-width character |
As mentioned earlier, a number of utility programs have been written to convert files from pod to a variety of output formats. Some of the utilities are described here, particularly those that are part of the Perl distribution. Other programs are available on CPAN.
| perldoc |
perldoc [options] docname
Formats and displays Perl pod documentation. Extracts the documentation from pod format and displays it. For all options except -f, docname is the name of the manpage, module, or program containing pod to be displayed. For -f, it's the name of a built-in Perl function to be displayed.
perldoc applies switches found in the PERLDOC environment variable before those from the command line. It searches directories specified by the PERL5LIB, PERLLIB (if PERL5LIB isn't defined), and PATH environment variables.
| pod2fm |
pod2fm [options] file
Translates pod to FrameMaker format.
|
Type |
Description |
|---|---|
|
all |
All types (the default) |
|
Character |
Character formats |
|
Paragraph |
Paragraph formats |
|
Page |
Master page layouts |
|
Reference |
Reference page layouts |
|
Table |
Table formats |
|
Variables |
Variable definitions |
|
Math |
Math definitions |
|
Cross |
Cross-reference definitions |
|
Color |
Color definitions |
|
Conditional |
Conditional text definitions |
|
Break |
Preserves page breaks; controls how the other types are used |
|
Other |
Preserves other format changes; controls how the other types are used |
| pod2html |
pod2html [options] inputfile
Translates files from pod to HTML format. Wrapper around the standard module Pod::Html; see Chapter 8, "Standard Modules" for the options, which are passed to Pod::Html as arguments.
| pod2latex |
pod2latex inputfile
Translates files from pod to LaTeX format. Writes output to a file with .tex extension.
| pod2man |
pod2man [options] inputfile
Translates pod directives in file inputfile to Unix manpage format. Converts pod-tagged text to nroff source that can be viewed by the man command, or troff for typesetting.
| pod2text |
pod2text < input
Translates pod to text and displays it. A wrapper around the Pod::Text module.
|  | |
| 4.12. Formats |  | 5. Function Reference |
Copyright © 2002 O'Reilly & Associates. All rights reserved.