POD in 5 minutes

[Juerd]

Note: This is a copy of http://juerd.nl/site.plp/perlpodtut (2003-04-23). The version on my website may be more up to date.

Plain Old Documentation in 5 minutes

Documentation is important

We all know that, and everyone knows why. I'll skip this section because any detailed discussion of why documentation is important would break my promise that you can learn to document in five minutes.

Documentation in Perl

Perl source code can contain documentation in POD format. POD stands for Plain Old Documentation. You can either mix POD with code, put the POD at the beginning of the file or put the POD at the end of the file. This depends only on what you like. You choose.

Headings in POD

Logical structure is important. So we use headings. There are four levels, and this should be enough. We use the =head1 .. =head4 commands (They are called command paragraphs officially. They are paragraphs because they're separated from the rest of the POD by blank lines).

=head1 NAME

My::Module - An example module

Common sections

To keep things clear, we all use the same sections everywhere. You already saw the NAME section. Yes, it is customary to write head1 paragraphs in ALLCAPS. If you author modules for CPAN, you have to use this style. If not, or if you use POD for other purposes than code documentation (it is a great format to write articles and reports in), it is your own choice.

• NAME contains the module or script name, a dash and a short description.
• SYNOPSIS means "see together" and shows example usage.
• DESCRIPTION contains a long description of what the module does and lists functions.
• BUGS or CAVEATS tells about bugs or issues the user should know about.
• ACKNOWLEDGEMENTS is where you thank bug fixers, testers and you parents.
• COPYRIGHT or LICENSE mentions copyright restrictions. Don't put the entire GPL there, though :)
• AVAILABILITY says where newer versions can be pulled from.
• AUTHOR explains who made it, if COPYRIGHT didn't already do so.
• SEE ALSO refers to additional documentation.

Those are all for =head1.

Functions, methods and things like that are usually explained in a =head2 within DESCRIPTION.

At the very least, document what arguments a function takes and what the function returns. If there is any precondition, mention it. If your function returns undef on error, let people know!

It is okay to write short sentences. Avoid long sentences.

Code examples

Indented paragraphs render as code, with indenting intact. It's that easy!

=head1 SYNOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

This is called a verbatim paragraph.

Markup

POD supports a small set of markup elements. To keep my time promise, I'll just list them:

• B<bold text here>
• I<italic text here>
• U<underlined text here>
• C<code text here>
• B<and you can I<nest> them>

And there are F, S, X and Z, but they're rarely used so not worth explaining in a simple tutorial.

If you ever need to include a > character within a formatting code, you have two options. If you want to render $foo->bar in a code font, this is what you can do:

• C<$foo-E<gt>bar>
• C<< $foo->bar >> (inner whitespace is required!)
• C<<< $foo->bar >>> (inner whitespace is required!)

Entities

You saw how E can be used for entities. These are like HTML entities, with the addition of:

• verbar for a vertical bar
• sol for a slash (solidus)

Numeric entities are decimal, octal (prefixed with 0) or hexadecimal (prefixed with 0x).

Lists

An example is much clearer than an explanation here.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

As you can see, we start this definition list with =over and we end it with =back. In between are =items. The number after over is the indentlevel, used mainly by text renderers for a nice horizontal layout. pod2text renders the previous example as:

  Methods
      "new"       Returns a new
                  My::Module object.

      "as_string" Returns a stringified
                  representation of the
                  object. This is mainly
                  for debugging purposes.

Other POD coolness

You can use L to link to sections and other documents. Pod is ended with =cut to go back to Perl. There are special commands for different output formats. To read the complete POD documentation, type on a command prompt:

perldoc perlpod

A complete example

=head1 NAME

My::Module - An example module

=head1 SYNOPSIS

    use My::Module;
    my $object = My::Module->new();
    print $object->as_string;

=head1 DESCRIPTION

This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.

=head2 Methods

=over 12

=item C<new>

Returns a new My::Module object.

=item C<as_string>

Returns a stringified representation of
the object. This is mainly for debugging
purposes.

=back

=head1 AUTHOR

Juerd - <http://juerd.nl/>

=head1 SEE ALSO

L<perlpod>, L<perlpodspec>

=cut

Conclusion

Documenting using POD is easy. Have fun!

Edit by tye, add READMORE

[mirod]

Very nice intro to POD, juerd++.

One comment: there is one section I woudl like to see expanded: links. I know it always takes me a while to figure out how to link to somewhere else in the file, outside of the file, what I am allowed to link to etc... and half of the time I get it wrong.

[Juerd]

One comment: there is one section I woudl like to see expanded: links. I know it always takes me a while to figure out how to link to somewhere else in the file, outside of the file, what I am allowed to link to etc... and half of the time I get it wrong.

pod2html would break every promise I make, so here's my practical guide to linking in pod:

• Linking to URLs: Just put the URL in there and make sure it's followed by whitespace to avoid having too much interpunction in the link itself.
• Linking to e-mail addresses: Why? Want spam or something? Just put the address in there and it'll probably get linked - and harvested.
• Linking within the same document: pod2html will try to do this automatically.
• Linking to other documents: L<perlfoo>

I use explicit links only in SEE ALSO.

But I think only TorgoX really knows what is and what is not allowed.

Juerd
- http://juerd.nl/
- [e-mail] (do not use).

[PodMaster]

From perlpod

    L<name>     A link (cross reference) to name
                    L<name>             manual page
                    L<name/ident>       item in manual page
                    L<name/"sec">       section in other manual page
                    L<"sec">            section in this manual page
                                        (the quotes are optional)
                    L</"sec">           ditto
                same as above but only 'text' is used for output.
                (Text can not contain the characters '/' and '|', 
                and should contain matched '<' or '>')
                    L<text|name>
                    L<text|name/ident>
                    L<text|name/"sec">
                    L<text|"sec">
                    L<text|/"sec">

perlpodspec will be up updated to make support for L<link text|url> official, so to be on the safe side (with ye old modules), just use L<url> or don't use L at all cause pod2html will autolink it.

Now, what pod2html will do is try to autolink C<=item functioname> if you use C<$foo-E<gt>method>.

Pod::Html will also try to autolink to any core perl functions and the like. This has nothing to do with pod, it's just extra fluff (i like it).

What everybody wants to do is use podchecker. You wanna lookout for "multiple link targets" warnings, like if you have =headN FOO twice.

MJD says you can't just make shit up and expect the computer to know what you mean, retardo! I run a Win32 PPM repository for perl 5.6x+5.8x. I take requests. ** The Third rule of perl club is a statement of fact: pod is sexy.

[jmcnamara]

But I think only TorgoX really knows what is and what is not allowed.

He recently wrote a specification for POD so now everyone can find out what is and what is not allowed.

It is part of 5.8.0: perlpodspec - Plain Old Documentation: format specification and notes.

--
John.

[michaeld]

Exactly what a newbie needs to start documenting his/her code, without having to wade through the perldoc pages!

A big ++ to you Juerd!

Cheers,
MichaelD

[Anonymous Monk]

Just a minor point but as a newbie (with pod) what is the purpose of using pod style formatting and not just # comments ? .. I know there is one, but in the context of the article it doesn't mention anywhere how to actually produce readable documentation from it. Thanks for any pointers.

[PodMaster]

use perldoc, pod2html, pod2man, pod2text, pod2 ... all available from cpan

update: Here is what I acutally have installed ;)(well, installed in my perl -V:bin )

pod2docbook
pod2htmltree
pod2man
pod2pdf
pod2test
pod2text
pod2usage
pod2xhtml
pod2xml
podchecker
podlint
podselect
podstrip -- mine ;) -> Pod::Stripper
podview  -- gui pod viewer, comes with Prima

[planetscape]

For a Spanish translation, please see POD en 5 minutos, by Hue-Bond.

[j3]

Where did this tutorial (and the comments) go?

[Juerd]

The gods have restored them :)