home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam    

Book HomeJava and XSLTSearch this book

4.13. 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.

4.13.1. Paragraph Tags

The following paragraph tags are recognized as valid pod commands.

4.13.3. 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.

pod2fm

pod2fm [options] file

Translates pod to FrameMaker format.

Options

-book [bookname]
If set, creates FrameMaker book file. If not specified, bookname defaults to perl; filename extension is .book 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 book after creating it; requires the -book 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.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.







??????????????@Mail.ru