Item 46: Embed your documentation with POD.


Ahh, documentation! Just what all programmers love to spend their time writing when they could be coding, or perhaps playing NetHack, or even enjoying some non-nerdlike activity like friends , family, or exercise. Given that some developers spend ten, twelve, or more hours a day just getting their code to run, it's not surprising that a lot of documentation winds up being written in a half-hearted way, or is written by non-programmers, or is not written at all.

A good many software developers, especially those working on sizable projects, work to coding standards that require them to start off function definitions with block comments that provide key information about that functionoverview, inputs, outputs, preconditions, change history, and the like. If those embedded comments are formatted precisely enough, they can be parsed by scripts (probably Perl scripts!) and reformatted into documentation. A source file could thus contain (or be) its own programming reference. This is a Good Thing, because it allows developers to tweak the documentation each time they tweak the code without having to locate and edit a separate document. Sometimes this is about all the documentation that a developer can manage to do correctly.

The down side to embedded documentation, however, is that unless you're working in a language or environment that supports it, you or someone in your group has to write and maintain tools that extract the goodies from your source files and generate documentation from them. Someone also has to decide what format the comments are going to be in, and someone has to enforce it. It would be nice, of course, if your comments were formatted like those from other groups so that you could share tools, but without any standards that isn't likely to happen.

Fortunately, Perl directly supports embedded documentation. Perl does it in a standardized way that is part of the core of the language, with a feature called POD, or "Plain Old Documentation." Perl source code can contain embedded documentation in POD format. The Perl parser ignores POD sections when compiling and interpreting scripts, but other programs supplied with the Perl distribution can scan source files for documentation sections and format them as man pages, HTML, plain text, or any of a number of other formats.

POD basics

POD is a very simple markup language designed so that documentation written in POD can be translated readily into other formats (text, HTML, etc.). POD is easily readable in raw form if worse comes to worse , too.

A POD document consists of paragraphs set off by blank lines. There are three different kinds of paragraphs:

  • Verbatim text. A paragraph whose lines are indented will be reproduced exactly as it appearsno line wrapping, no special interpretation of escape sequences, no nothing. Translators that can display different fonts will generally reproduce verbatim text in a fixed-width font.

  • A POD command. A command is a line beginning with the character = , followed by an identifier, then some optional text. Currently defined commands, which may not be understood by all translators, are shown below:

    POD commands

    Command

    Description

    Example

     =head1  =head2 

    Level 1, level 2 headings.

     =head1 Understand Packages and Modules.  =head2 Packages 
     =item 

    An item in a bulleted or numbered list.

     =item 1  =item *  =item B<NOTE> 

    A numbered item.

    A bulleted item.

    A bolded "other" item.

     =over  N  =back 

    Indent over N spaces.

    Go back from indent.

     =over 4  =back 

    4 is the customary number.

     =cut  =pod 

    End of POD.

    Beginning of POD.

     =cut  =pod 
     
     =for  X  
    >

    Next paragraph is of format X.

     =for html  =begin text 

    Next para in HTML.

     =begin  X  =end  X  

    Bracket beginning and end of format X.

     If you can read this, you are using a text translator.  =end text 
  • Filled text. A paragraph that isn't verbatim or a POD command is treated as ordinary text. Formatters generally will turn it into a justified paragraph, in a proportionally spaced font if possible. A number of special formatting sequences are recognized inside filled text:

POD formatting sequences

Sequence

Description

Example

 I<  text  >  B<  text  > 

Italicized text, bolded text.

 You will be I<very> lucky to have  B<John> work for you 
 C<  text  > 

Source code.

 now, add 5 to C<$d[$a,$b]> 
 S<  text  > 

Text with nonbreaking spaces.

 C< S<foreach $k (keys %hash)> > 
 E<  code  > 

A character escape (generally not needed).

 E<lt>  E<34> 

Less-than sign <.

Double quote " (in ASCII)

 L<  text  > 

A link or cross-reference.

 L<name>  L<name/ident>  L<name/"sec">  L<"sec"> 

Man page.

Item in man page.

Section in man page.

Section in this man page.

 F<  name  > 

Filename.

Be careful not to delete F<config.dat>!

 X<  text  > 

Index entry.

 
 Z<  text  > 

Zero-width character.

 

Note that some POD formatters will recognize function names (an identifier followed by parentheses) and other special constructs "in context" and automatically apply appropriate formatting to them. In addition, most POD formatters can convert straight quotes to "smart" matching quotes, doubled hyphens to em dashes, and so forth.

Here is an example POD file:

POD file

 =head1 My POD Example  =head2 My second-level heading  I<POD> is a simple, useful markup language for Perl programmers as  well as others looking for a way to write "Plain Old Documentation."  With POD, you can:  =over 4  =item 1  Create documentation that can be readily translated into many  different formats.  =item 2  Embed documentation directly into Perl programs.  =item 3  Amaze your friends and terrify your enemies.  (Possibly.)  =back    Author: Joseph N. Hall    Date: 1997 

When translatedin this case, by my pod2mif filterit yields:

Translated POD file

My POD Example

My second-level heading

POD is a simple, useful markup language for Perl programmers as well as others looking for a way to write "Plain Old Documentation." With POD, you can:

  1. Create documentation that can be readily translated into many different formats.

  2. Embed documentation directly into Perl programs.

  3. Amaze your friends and terrify your enemies. (Possibly.)

 Author: Joseph N. Hall    Date: 1997 

Man pages in POD

Although you can use POD for many different purposes, man pages written in POD should follow certain conventions so that they will resemble other Unix man pages. Variables and function names should be italicized . Names of programs, as well as command line switches, should be bold .

The man page should have a proper skeleton. The first-level headings traditionally appear in CAPITAL LETTERS. The most important of the first-level headings, in the traditional order, are:

Man page headings

Heading

Description

NAME

Name of the program/library/whatever.

SYNOPSIS

Brief example of usage.

DESCRIPTION

Detailed description, broken into sections if necessary.

EXAMPLES

Show us how we use it.

SEE ALSO

References to other man pages, etc.

BUGS

Things that need a little work yet.

AUTHOR

Your name in lights.

See the pod2man man page for more information about the layout of man pages.



Effective Perl Programming. Writing Better Programs with Perl
Effective Perl Programming: Writing Better Programs with Perl
ISBN: 0201419750
EAN: 2147483647
Year: 1996
Pages: 116

Similar book on Amazon

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net