Pod

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:

  • Command
  • Commands begin with =, followed immediately by the command identifier: 
    =cut

    They can also be followed by text: 

    =head2 Second-level head

    A blank line signals the end of the command.

  • Text
  • A paragraph consisting of a block of text, generally filled and possibly justified, depending on the translator. For example, a command such as =head2 will probably be followed with a text paragraph: 
    =head2 Pod Pod is a simple, but surprisingly capable, text formatter that uses tags to tell a translator how to format the text.
  • Verbatim
  • A paragraph that is to be reproduced as is, with no filling or justification. To create a verbatim paragraph, indent each line of text with at least one space: 
    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.

Paragraph Tags

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.

=end 
=end

Ends a =begin block. Tells the translator to treat what follows as pod again.

=for 
=for format

Indicates a format change, for the next paragraph only.

=head1 
=head1 text

text following the tag is formatted as a top-level heading. Generally all uppercase.

=head2 
=head2 text

text following the tag is formatted as a second-level heading.

=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 *
  • Bulleted list. An asterisk (*) is commonly used for the bullet, but can be replaced with any other single character. Followed by a blank line and then the text of the bulleted item: 
    =item * This is the text of the bullet.
  • =item n
  • Numbered list. Replace n with on the first item, on the second, and so on. Pod does not automatically generate the numbers.
  • =item text
  • Definition list. Formats text as the term and the following paragraph as the body of the list item. For example: 
    =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.

=pod 
=pod

Indicates the beginning of pod text. A translator starts to pay attention when it sees this tag, and the compiler ignores everything from there to the next =cut.

Interior Sequences

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"> in another manpage
L<"sec"> 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

Pod Utilities

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.

Options

  • -f function
  • Formats and displays documentation for the specified Perl function.
  • -h
  • Displays help message.
  • -l
  • Displays full path to the module.
  • -m
  • Displays entire module, both code and pod text, without formatting the pod.
  • -t
  • Displays using text formatter instead of nroff. Faster, but output is less fancy.
  • -u
  • Unformatted. Finds and displays the document without formatting it.
  • -v
  • Verbose. Describes search for the file, showing directories searched and where file was found.

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.

Options

  • -tutorial [tutorialname]
  • If set, creates FrameMaker tutorial file. If not specified, tutorialname defaults to perl; filename extension is tutorial in either case.
  • -[no]doc
  • Whether to convert a MIF-format doc output file to binary FrameMaker format. Default is -doc.
  • -format type
  • Which format to copy from the template document specified with the -template option. Type can be a comma-separated list, and -format can also be specified more than once. Legal types are:
    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
  • -[no]index
  • Whether to generate an index. Defaults to -noindex.
  • -[no]lock
  • Whether to lock file as read-only so you can use hypertext marker feature. Defaults to -nolock.
  • -[no]mmlonly
  • Whether to stop execution after generating the MML version of the file. Default is -nommlonly.
  • -[no]open
  • Whether to try to open the tutorial after creating it; requires the -tutorial option.
  • -template document
  • Specifies a template document for pod2fm copies a format for use in formatting the output. document is the path to the template document.
  • -[no]toc
  • Whether to generate a table of contents. Defaults to -notoc.
pod2html 
pod2html [options] inputfile

Translates files from pod to HTML format. Wrapper around the standard module Pod::Html; see "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.

Options

  • --center=string
  • Sets centered header to string. Defaults to "User Contributed Perl Documentation" unless -\-official flag is set, in which case it defaults to "Perl Developers Reference Guide."
  • --date=string
  • Sets left-hand footer string to date.
  • --fixed=font
  • Specifies the fixed-width font to use for code examples.
  • --lax
  • If set, ignores missing sections.
  • --official
  • If set, uses default header as shown for -\-center above.
  • --release=rel
  • Sets centered footer. Defaults to current Perl release.
  • --section=manext
  • Sets manpage section for nroff .TH macro. Default is (functions) if filename ends in pm; otherwise (user commands).
pod2text 
pod2text < input

Translates pod to text and displays it. A wrapper around the Pod::Text module.

Options

  • --help
  • Displays help information.
  • --htmlroot=name
  • Sets base URL for the HTML files to name.
  • --index
  • Generates index at top of the HTML file (default).
  • --infile=name
  • Converts pod file name. Default is to take input from STDIN.
  • --libpods=name:...:name
  • List of page names (e.g., "perlfunc") that contain linkable =item s.
  • --outfile=name
  • Creates HTML file name. Default is to send output to STDOUT.
  • --podroot=name
  • Uses name as base directory for finding library pods.
  • --podpath=name:...:name
  • Lists podroot subdirectories with pod files whose HTML-converted forms can be linked to in cross-references.
  • --netscape
  • Uses Netscape HTML directives when applicable.
  • --noindex
  • Does not generate index at top of the HTML file.
  • --nonetscape
  • Does not use Netscape HTML directives (default).
  • --norecurse
  • Does not recurse into subdirectories specified in podpath.
  • --recurse
  • Recurses into subdirectories specified in podpath (default).
  • --title=title
  • Specifies title for the resulting HTML file.
  • --verbose
  • Displays progress messages.