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


Placement Styles

Pod =head1 Sections To Include

man perlmodstyle for more complete list.

  • NAME

    Your::Module - One line description


    use Your::Module qw(namex);


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


  • pod2text

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

     pod2text --code --color /path/to/Your/ |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 \

    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!


  • 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();
     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, 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.


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.


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