perltutorial
Juerd
<p>
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.
</p>
<a name=1></a><h1>Plain Old Documentation in 5 minutes</h1>
<a name=2></a><h2>Documentation is important</h2>
<p>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.</p>
<a name=3></a><h2>Documentation in Perl</h2>
<p>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.</p>
<a name=4></a><h2>Headings in POD</h2>
<readmore>
<p>Logical structure is important. So we use headings. There are four levels, and
this should be enough. We use the <tt>=head1</tt> .. <tt>=head4</tt> commands (They are
called <i>command paragraphs</i> officially. They are paragraphs because they're
separated from the rest of the POD by blank lines).</p>
<pre><tt>=head1 NAME
<a href=""></a>
My::Module - An example module</tt></pre>
<a name=5></a><h2>Common sections</h2>
<p>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.</p>
<ul><li><em>NAME</em> contains the module or script name, a dash and a short description.</li>
<li><em>SYNOPSIS</em> means "see together" and shows example usage.</li>
<li><em>DESCRIPTION</em> contains a long description of what the module does and
lists functions.</li>
<li><em>BUGS</em> or <em>CAVEATS</em> tells about bugs or issues the user should know
about.</li>
<li><em>ACKNOWLEDGEMENTS</em> is where you thank bug fixers, testers and you parents.</li>
<li><em>COPYRIGHT</em> or <em>LICENSE</em> mentions copyright restrictions. Don't put
the entire GPL there, though :)</li>
<li><em>AVAILABILITY</em> says where newer versions can be pulled from.</li>
<li><em>AUTHOR</em> explains who made it, if COPYRIGHT didn't already do so.</li>
<li><em>SEE ALSO</em> refers to additional documentation.</li></ul>
<p>Those are all for <tt>=head1</tt>.</p>
<p>Functions, methods and things like that are usually explained in a <tt>=head2</tt>
within DESCRIPTION.</p>
<p>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 <i>undef</i> on error, let people know!</p>
<p>It is okay to write short sentences. Avoid long sentences.</p>
<a name=6></a><h2>Code examples</h2>
<p>Indented paragraphs render as code, with indenting intact. It's that easy!</p>
<pre><tt>=head1 SYNOPSIS
<a href=""></a>
use My::Module;
my $object = My::Module->new();
print $object->as_string;</tt></pre>
<p>This is called a <i>verbatim paragraph</i>.</p>
<a name=7></a><h2>Markup</h2>
<p>POD supports a small set of markup elements. To keep my time promise, I'll just
list them:</p>
<ul><li><tt>B<bold text here></tt></li>
<li><tt>I<italic text here></tt></li>
<li><tt>U<underlined text here></tt></li>
<li><tt>C<code text here></tt></li>
<li><tt>B<and you can I<nest> them></tt></li></ul>
<p>And there are F, S, X and Z, but they're rarely used so not worth explaining in
a simple tutorial.</p>
<p>If you ever need to include a <tt>></tt> character within a <i>formatting code</i>,
you have two options. If you want to render <tt>$foo->bar</tt> in a code font, this
is what you can do:</p>
<ul><li><tt>C<$foo-E<gt>bar></tt></li>
<li><tt>C<< $foo->bar >></tt> (inner whitespace is required!)</li>
<li><tt>C<<< $foo->bar >>></tt> (inner whitespace is required!)</li></ul>
<a name=8></a><h2>Entities</h2>
<p>You saw how E can be used for entities. These are like HTML entities, with the
addition of:</p>
<ul><li><em>verbar</em> for a vertical bar</li>
<li><em>sol</em> for a slash (solidus)</li></ul>
<p>Numeric entities are decimal, octal (prefixed with 0) or hexadecimal (prefixed
with 0x).</p>
<a name=9></a><h2>Lists</h2>
<p>An example is much clearer than an explanation here.</p>
<pre><tt>=head2 Methods
<a href=""></a>
=over 12
<a href=""></a>
=item C<new>
<a href=""></a>
Returns a new My::Module object.
<a href=""></a>
=item C<as_string>
<a href=""></a>
Returns a stringified representation of
the object. This is mainly for debugging
purposes.
<a href=""></a>
=back</tt></pre>
<p>As you can see, we start this definition list with <tt>=over</tt> and we end it
with <tt>=back</tt>. In between are <tt>=item</tt>s. The number after over is the
<i>indentlevel</i>, used mainly by text renderers for a nice horizontal layout.
pod2text renders the previous example as:</p>
<pre><tt><span></span> Methods
"new" Returns a new
My::Module object.
<a href=""></a>
"as_string" Returns a stringified
representation of the
object. This is mainly
for debugging purposes.</tt></pre>
<a name=10></a><h2>Other POD coolness</h2>
<p>You can use L to link to sections and other documents. Pod is ended with
<tt>=cut</tt> to go back to Perl. There are special commands for different output
formats. To read the complete POD documentation, type on a command prompt:</p>
<pre><tt>perldoc perlpod</tt></pre>
<a name=11></a><h2>A complete example</h2>
<pre><tt>=head1 NAME
<a href=""></a>
My::Module - An example module
<a href=""></a>
=head1 SYNOPSIS
<a href=""></a>
use My::Module;
my $object = My::Module->new();
print $object->as_string;
<a href=""></a>
=head1 DESCRIPTION
<a href=""></a>
This module does not really exist, it
was made for the sole purpose of
demonstrating how POD works.
<a href=""></a>
=head2 Methods
<a href=""></a>
=over 12
<a href=""></a>
=item C<new>
<a href=""></a>
Returns a new My::Module object.
<a href=""></a>
=item C<as_string>
<a href=""></a>
Returns a stringified representation of
the object. This is mainly for debugging
purposes.
<a href=""></a>
=back
<a href=""></a>
=head1 AUTHOR
<a href=""></a>
Juerd - <http://juerd.nl/>
<a href=""></a>
=head1 SEE ALSO
<a href=""></a>
L<perlpod>, L<perlpodspec>
<a href=""></a>
=cut</tt></pre>
</readmore>
<a name=12></a><h2>Conclusion</h2>
<p>Documenting using POD is easy. Have fun!
</p>
<p><small>Edit by [tye], add READMORE</small></p>