Perl - Plain Old Documentation

Programmers are notorious for writing the code first and the documentation never, so the designers of Perl built in a documentation system which makes writing documentation so easy that anyone can and will do so. The name of the built in system is pod which stands for plain old documentation. It allows you to embed documentation right in your program using a very simple markup format. The markup 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

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. This way you can also use the same text as both code documentation and user documentation if you wish.

Along with Perl are shipped several translators that filter generic pod format into specific output styles. These include pod2man to change your pods into troff for use with the UNIX man program or for phototypesetting and printing; pod2html for creating web pages (which works even on non-Unix systems); and pod2text for plain ASCII. Other translators, like pod2ipf, pod2fm, pod2texi, pod2latex, and pod2ps, may also be available or can be found on CPAN (the Certified Perl Archive Network).

A pod translator reads a file paragraph by paragraph, ignoring text that isn't pod, and converting pod text to the proper format. Paragraphs are separated from each other by blank lines (not just by a newline). The various translators recognize three kinds of paragraphs:

Command

Commands begin with =, followed immediately by the command identifier, e. g.,

	=cut

They can also be followed by text:

	=head2 Second-level heading
		
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 like =head2 is probably 
going to 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.

The following paragraph tags are recognized as valid pod commands:

=back
=begin
=cut
=end
=for
=head1
=head2
=item
=over
=pod

In addition to the paragraph tags (above), pod has a set of tags that apply within text, either in a paragraph or a command. For information on those tags, see the Perl built-in documentation available by entering perldoc perlpod at your MS DOS or UNIX Perl command prompt.

I highlighted the pod2html reference above because I think that it's the neatest translator. The following two links are to an actual "live" example of pod2html output and the perl program from which it was generated:

	sort.html

	sort.pl (text file [so that it does not execute the Perl script])

Again, additional information on its usage can be had by entering perldoc pod2html at your MS DOS or UNIX Perl command prompt.

In our next to the last lesson for this module, we will sum up our stroll through Perl.

See you next lesson!

=back

Moves the 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.

Return to the page from whence you came

=begin

=begin format

Starts a block of text that is to 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.

Return to the page from whence you came

=cut

Indicates the end of pod text. Tells the compiler that there isn't any more pod (for now) and to start compiling again.

Return to the page from whence you came

=end

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

Return to the page from whence you came

=for

=for format

Indicates a format change, for the next paragraph only.

Return to the page from whence you came

=head1

=head1 text

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

Return to the page from whence you came

=head2

=head2 text

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

Return to the page from whence you came

=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 1 on the first item, 2 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 what translator you use, but it will look pretty much like this:

	<HTML>
		Indicates the beginning of an HTML file

Return to the page from whence you came

=over

=over n

Specifies the beginning of a list, where 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.
Return to the page from whence you came

=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

Return to the page from whence you came