NAME

Pod Overview - Using Plain Old Documentation format in GP Perl code

SYNOPSIS

 What is Pod?
 Using Pod
 Caveats
 Examples
 See Also
 To Pod or Not to Pod

DESCRIPTION

What is Pod?

POD stands for Plain Old Documentation. Pod is a very simple text markup format that can either be used on its own or interspersed within Perl code.

Pod documentation can be ``sprinkled'' throughout a program file. Any of several pod translators can be used to extract the pod. Perl considers pod to be commentary; the pod translators consider code to be extraneous.

The Perl lexer skips over pod directives when parsing a program for execution, just as pod translators skip over Perl code when parsing pod. With several caveats (below), pod is fairly simple to use.

How pod is extracted and presented depends on the translator you use. Available translators bundled with Perl include

pod2text - extract pod and format as text
pod2man - extract pod and format as a Unix-style man page
pod2html - extract pod and format as HTML suitable for viewing with a browser
pod2latex - extract pod and convert to LaTeX

Additional translators are available for download from the CPAN.

Using Pod

There are a small number of recognized directives. See man perlpod (attached) for complete details. Pod directives are composed of = and an identifier (command). For example

  =head1
  =item
  =over
  =for
  =cut

Several of the directives take argument text, usually (although not necessarily) placed on the same line as the directive. The argument text may be processed differently, depending on the directive and the translators.

  =head1 Heading Text
  =item tag
  =over 4
  =for html
  =cut

CAVEATS

Spacing is absolutely critical. Although Perl is white-space tolerant, generally ignoring whitespace entirely, pod is very white-space picky.
If you like using indentation as a way to organize your text, you will be very disappointed (and ofttimes frustrated) with pod.
If your results do not match your expectations, the most likely cause is whitespace out of place.
a)
Be sure to begin pod directives in column 1 - indentation is not permitted.

b)
All pod directives start with a = (in column 1) immediately followed by an identifier (e.g. head1, item, cut). The directive may be followed by any amount of text; however, the text must be one paragraph. Paragraphs are separated by a blank line. See example below.

c)
Be sure to precede all pod directives with a blank line. Be sure to follow all pod directives with a blank line. See example below.

d)
``Flowed'' text must begin in column 1. Pod will format the text to wrap. Flowed text may contain special sequences to adjust the formatting (slightly), e.g. producing bold or italic if the formatter permits. Note that the formatter may indent flowed text while wrapping... Your mileage may vary.
```
 Verbatim text must be indented by at least one space.
 Pod will set the text as typed
 without
 wrapping.
```
e)
Paragraphs are separated by at least one blank line. Paragraph types cannot be mixed (that is, a paragraph type that starts out flowed, continues flowed, even if some lines are indented in the source. See example below.

Watch out for ``blank'' lines that aren't really empty. A blank line matches
```
  ^$
```
Lines containing spaces or tabs are not ``blank'' to pod.
Pod has no specific comment directive. Kludges (er, workarounds (er, WTDI)) are available. See example below.
If you mistype one of the tags on a =begin/=end pair, the translator will gobble up all of your pod because it won't know when to stop. Be wary.
There is no =head3 directive.
Forcing an additional blank line is tricky. If a line starts with a space it will be set as a blank line by the formatter but this sort of ``invisible'' magic can cause trouble sometimes. Unfortunately, that means headers tend to ``stick'' to their first paragraph. See example below.
Pod translators vary widely. The pod2text translator is pretty minimalistic. Other translators may do syntax checking or require certain formats for the data.
The pod2man script specifically requires that your first pod directive be
```
 =head1 NAME
```
(not ``NAME:'', not ``NAME -'').
pod2man also insists on a - in the NAME paragraph text line.
Pod is not very powerful nor is it nearly as expressive as other formatting languages such as XML, HTML, troff, LaTeX, or most word processors. This was a design consideration, but it's something important to remember.
On the other hand, pod is a bit more powerful and expressive than plain text comments (and, given the various translators, it's a lot more flexible).
The latest and greatest pod functionality may not yet be installed on the server near you...

EXAMPLES

The following examples illustrate some of the quirks of pod.

If you don't precede pod directives with a blank line, they will be treated as text. For example
```
  =back
  =cut
```
will not act as expected (=cut is considered part of the data, the text. It is not recognized as a pod directive in this position.) Add a blank line:
```
  =back
```
```
  =cut
```
This is two directives.

Similarly, you must also follow pod directives with a blank line

If your pod is

 =item ConvertFromExternalAssetIDs
   Description: Convert a hash or array keyed on some external id
 Inputs: 
   $equity - Date on which IDs are valid
  Returns:
   $rOut - Reference to converted hash or array

and you see

ConvertFromExternalAssetIDs Description: Convert a hash or array keyed on some external id Inputs: $equity - Date on which IDs are valid Returns: $rOut - Reference to converted hash or array

when you expected to see

 ConvertFromExternalAssetIDs 
      Description: Convert a hash or array keyed on some external id
      Inputs: 
        $equity - Date on which IDs are valid
      Returns:
        $rOut - Reference to converted hash or array

check for the blank line after

 =item

Pod directives may be followed by ``arguments'' which they use in various ways depending on the directive. However, the argument text must be one paragraph and must immediately follow the directive. In other words, when you reach the first blank line, the pod directive stops processing text.
You can use either
```
 =head1 Heading 1
```
```
 paragraph text
```
which produces
```
    Heading 1
        paragraph text
```
or
```
 =head1
 Heading 2
```
```
 paragraph text
```
which produces
```
    Heading 2
        paragraph text
```
but not
```
 =head1
```
```
 Heading 3
```
```
 paragraph text
```
which produces two indented paragraphs and no heading:
```
        Heading 3
```
```
        paragraph text
```

Paragraph types cannot be mixed. That is, you cannot include an indented list as part of a paragraph:

 There are several possible directives. They include:
         =head1
         =item
         =over
         =for
         =cut

This would be formatted as:

 There are several possible directives. They include: =head1
 =item =over =for =cut

Pod has no =comment directive. Use a =for directive to comment out one paragraph; wrap multiple paragraphs between =begin and =end directives. Exercise caution. =for will only comment out the following paragraph, up to the next blank line.
```
 =for comment
  this text will not be extracted or translated
```
```
  this text will be translated
```
```
 =begin comment
  this line will be skipped
```
```
  as will this one
```
```
  and this one
```
```
 =end comment
```
```
  but this line will be translated and printed.
```
Remember to precede the =end directive with a blank line!
Note that the argument to the =for, =begin, and =end directives is a translator type; the ``comment'' translator does not exist. Actually, any nonexistent translator type could be used (although clarity should be preferred over cuteness).
```
  =for later
  we'll uncomment this part when it works
```
```
  =begin unfinished documentation
  don't include this
```
```
  =end unfinished documentation
```
Depending on the translator, it may be difficult to ``force'' blank lines, for example, between headers and the following paragraph. That is:
```
 =head1 DESCRIPTION
```
```
 POD Overview for Global Platform
```
will be formatted by pod2text as
```
 DESCRIPTION
        POD Overview for Global Platform
```
Error messages from translators may be misleading. For example, when pod2man complains
```
 /usr/local/bin/pod2man: bad option in paragraph 6 of gp-prog.pl: ``-d''
 should be [CB]<-d>
```
you should ignore the [ ] in the error message.

To Pod or Not to Pod

Although it may be tempting to write all of your comments in pod format, consider whether every comment block actually needs to be extracted, translated, and printed. Try to separate printable documentation from ``real'' code comments. Separate interface from implementation.

If you're not sure, think ``man page''. That is, what would you put into a man page for this program? Use pod for documentation a user of your program would care about (said user could be another developer). use comments for documentation a programmer / maintainer would care about.

Use pod for information that can stand alone, separate from the code. Use comments for information that requires the code (comments for contextual documentation).

Recommended guidelines:

a): Use pod for the big header block at the top of the program or module
b): Use pod to describe input and output data formats (if appropriate)
c): Use pod for a header block above each (public or protected) function or method
c): Use comments for private functions
d): Use comments for documenting specific sections of code, explaining algorithms, explanations, references, etc. that aren't required in printed documentation.
e): Use comments for RCS information (including logs).

Use your professional judgement to make exceptions to these guidelines.