FiniWiki, Powered by Foswiki Free and Open Source Wiki
RichmondPM > PodPerspectives
FiniWiki webs: Main | System | Sandbox   Login or Register
Users | Groups | Offices | Changes | Index | Search | Go
POD PERSPECTIVES


POD PERSPECTIVES

Placement Styles

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

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


Parents: WebHome
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding FiniWiki? Send feedback