• POD PERSPECTIVES

• Placement Styles
• Pod =head1 Sections To Include
• Formatters
• Verifiers
• Nifty Tools
• Misc Annoyances
• Community Conventions
• Summary
• Other

POD PERSPECTIVES

Placement Styles

• Inline
  • Advantages

    Recommended in man perlmodstyle. Should a method be modified the documentation to be also modified is nearby.

  • How To

    At some point preceding the first subroutine / method, you'll have

     =head2 DESCRIPTION

     This module explores bending of light in deep space.

     =over 4

     =cut

    Then, preceding each method,

     =item * parse_input HASH

     Trash all references to Quantum Mechanics.

     =cut

  • Use perltidy to strip out Pod
    • (Optionally) Make a pod only listing:

       perltidy --tee-pod /path/to/Your/Module.pm

      perltidy in it's most typical usage outputs an InputName.tee file. Above created a both Module.pm.tdy and Module.pm.TEE file.

    • Make a code only listing:

       perltidy -st --delete-pod /path/to/Your/Module.pm >Module.nopod

      Note deliberate use of -st (standard out) option to explicitly name the output.

    • perltidy is available from :

      http://perltidy.sourceforge.net

    • Additional notes on the --tee-pod option.

      Use the -opath option to write these to an alternative directory (e.g., if you're doing all modules and don't want to untidy(!) a production directory with a lot of temp files.)

• embedded, entirely following __END__

  (Or, at least following one or more blank lines after the last code line.)

  Easy to strip out for ``code only'' listing. Little chance of clobbering code.

• External file (e.g., Something.pod)
  • Perspective

    ``Any stuff you put in external pod files (.pod) should be tutorial like material (extended documentation) ~ the api spec should be in with the module (.pm )'' - http://www.perlmonks.org/

  • Additionally

    External files (abc.pod) are useful when creating man pages for other-than-Perl software.

Pod =head1 Sections To Include

man perlmodstyle for more complete list.

• NAME

  Your::Module - One line description

• SYNOPSIS

  use Your::Module qw(namex);

• DESCRIPTION

  Two or three sentence description of the functionality. Can be followed with =over , =item(s) describing subroutines (close with =back).

Formatters

• pod2text

  Note on Options: If your module uses an embedded, inline style try this:

   pod2text --code --color /path/to/Your/Module.pm |more

  It's a quick way to view the listing with the formatted Pod next to the appropriate subroutines, and set apart by color.

  Of course you can redirect to a file instead of `| $PAGER` .

  Commandline less in this context may need the option -R.

• pod2html

  Example (actual paths will depend on the local machine):

   pod2html --infile=Pod2U.pod --outfile=Pod2U.html \
   --title="Some Description"
   --podroot=/usr/lib/perl5 \
   --htmlroot=file:///usr/local/share/doc/perl5 \
   --podpath=5.8.8/pod

  The first line of the command above is all that is necessary if you don't need to resolve the links to other html in the local environment.

• pod2man

  Useful to create *nix manual pages for any app, not just Perl!

Verifiers

• Pod::Checker

  Note: The command line script podchecker uses Pod::Checker qw(podchecker). Returns a 0 (zero) if Pod is found,and there are no syntax errors. Or you can write your own script using Pod::Checker for more control:

   use Pod::Checker;
   my %options = ( -warnings => 2, );
   my $pc_rc = podchecker( $ARGV[0], undef, %options );
   printf "File $ARGV[0] has %s\n", 
          ( $pc_rc =~ /^0$/ )?'good Pod':'Problems';

  On a side note, implements Pod::Usage as described below: Pod::Usage

• Pod::Simple:Checker

   use Pod::Simple::Checker;
   my $parser = Pod::Simple::Checker->new();
   $parser->parse_file($ARGV[0]);
   printf "File $ARGV[0] has %s\n", 
          (defined $parser->content_seen)?'Pod.':'NO Pod';

  Might catch different errors vs. Pod::Checker. Basically the same purpose. See comment at Suggested codemod.

• Pod::Coverage

  Simpliest usage is command line invocation:

   perl -MPod::Coverage=Your::Module

  Only works on modules (requires a name like Your:Module).

  Difference from Pod::Checker: Take CGI::Apache (deprecated). It Checks out ok (RC = 0) but rates ``No Coverage'' here because there are no subroutines (therefore no corresponding =items)

• Pod::Find qw(contains_pod)

Nifty Tools

• Pod::Usage

  use Pod::Usage; GetOptions(\%options, qw(help man warnings+ nowarnings)) || pod2usage(2);

  Takes the existing embedded Pod in your application program and formats/outputs it in response to command line options, e.g. -help or -man.

  Example, try :

   podchecker -man

  Man page was generated on the fly. You'll notice the physical file is /tmp/somerandomstring (see last line: assuming your pager is less), and the page title contains User contributed... (compare to display of `man podchecker`).

  pod2usage Anything_with_a_Pod_SYNOPSIS # command line executable.

• Pod::Find qw(pod_find)

  Finds text files with Pod ( *.pod | *.pm | *.pl ) according to supplied paths / options.

Misc Annoyances

• Uneven bold styles in item text (pod2html).

  Apparently occurs with code-like text in item heading.

  =item * some_function($alpha,$beta) produces an html entry wrapped in <code></code> .

  Solution: space out the words and punctuation. Or use simple / short item descriptions. Or Explicitly format =item line text with C<TEXT> or B<TEXT> .

• emacs, perl-mode

  Editing code with inline Pod style : perl-mode syntax hilighting may fail. cperl-mode is better.

Community Conventions

• Pod is typically found in Modules.

  Is Pod expected in Perl Scripts?. A search in a typical nix Perl installation found only 1 .pl lib entry, namely perl5db.pl, contained (A lot of) Pod (plus a lot of regular comments).

• However,

  use -ing Pod::Usage appears to be intended for scripts, i.e., something that can take input from the command line.

Summary

Pod is very useful in terms of the final product, i.e. accessable, multi-linked-page documentation. But the syntax is cumbersome, especially when creating inline Pod.

By comparison, javadoc is easier to use, having only the ``/**'' and @keywords. Short of emulating that, perhaps a Pod-skeleton-builder is in order, which would take source code and insert the minimum Pod structure that could be subsequently filled in.

Ahhh, Laziness, Impatience, Hubris.

Other

• ToDo
  • Searching Pod

    Need a Simple routine for searching only the Pod in a list of perl modules / scripts. Might be useful when looking for a style to emulate.

  • Understanding the =begin :format contruct.

    Reading the documentation it appears that I should be able to do something like

     =begin :html

     Detail with normal Pod commands. Destined only for html.

     =end :html

    ['m already using the =begin; this is with the : (colon) preceding the format name.

• Further Reading
  • man perlpod

    http://www.perl.com/doc/manual/html/pod/perlpod.html

    The starting point.

  • man perlstyle

    http://www.perl.com/doc/manual/html/pod/perlstyle.html

    The section at the end (search for 'Pod', or 'use Pod formatting in a consistent way') has some good advice.

  • man perlmodstyle

    Helpful information under heading DOCUMENTING YOUR MODULE

  • man perlpodspec

    (F?)MTEYEWTK

  • http://en.wikipedia.org/wiki/Pod

    FYI

• Suggested codemod

  Pod::Checker, see also: http://wiki.fini.net/bin/view/RichmondPM/PerlHacks#Proposed_modification_to_Pod_Che

  Need to flag pod which consists of nothing more than =cut.

  More specifically, need to flag missing format-essential-blank-lines before commands. It may be also beneficial to give a warning for the last command in a =forcomment block (as in, Did you really want to do that?)

  Also, it may be good to Warn for each =cut which has no commands preceding. Pod::Simple::Checker appears to do this (although it also misses the fact that the commands preceding may be invalid as they are not preceded by space.)