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

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

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

  1. Watch out for ``blank'' lines that aren't really empty. A blank line matches

      ^$
    

    Lines containing spaces or tabs are not ``blank'' to pod.

  2. Pod has no specific comment directive. Kludges (er, workarounds (er, WTDI)) are available. See example below.

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

  4. There is no =head3 directive.

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

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

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

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

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

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

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

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

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

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

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


SEE ALSO

There are a number of useful resources for pod.

The perlpod man page is a good place to start, as is chapter 26, ``Plain Old Documentation'' of the 3rd addition of ``Programming Perl'' by Wall et. al. (``The Camel'').

Most Perl modules are documented in pod. You can also look at the pod subdirectory of the installed Perl distribution (try /usr/local/lib/perl5/pod/).

Several of the pod2* translators are written in Perl with embedded pod documentation. Look in /usr/local/bin.

The script newasgp.pl generates a ``code template'' for GP Perl scripts. Note that newasgp.pl is a ``work in progress''; more functionality may be added to the template in the future. See gp-prog.pl for an example of the output from newasgp.pl.


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.