Front page | perl.perl5.porters |
Postings from December 2004
From: Ronald J Kimball
December 24, 2004 08:56
Message ID: 20041224165630.GA8230@penkwe.pair.com
On Fri, Dec 24, 2004 at 11:12:05AM +0100, Juerd wrote:
This looks like a very helpful tutorial. I just have a few nits... :)
> =head1 NAME
> perlpodtut - Plain Old Documentation in 5 minutes
> =head1 DESCRIPTION
> This short tutorial will teach you how to write documentation with POD. POD
> stands for Plain Old Documentation and is the formatting language that the
> official Perl documentation and CPAN modules use. For it exist several
> translators, which can turn POD into manpages, HTML, LaTeX, RTF, etcetera.
Several translators exist for it, which can turn POD into manpages, HTML,
LaTeX, RTF, etc.
> =head2 Headings in POD
> Logical structure is important. So we use headings. There are four levels, and
> this should be enough. We use the C<=head1> .. C<=head4> commands (They are
> called I<command paragraphs> officially. They are paragraphs because they're
> separated from the rest of the POD by blank lines).
We use the C<=head1> .. C<=head4> commands. (They are called I<command
paragraphs officially. They are paragraphs because they're separated from
the rest of the POD by blank lines.)
> =item SYNOPSIS
> means "see together" and shows example usage.
A synopsis is a brief summary. The derivation of the word doesn't seem
> =head2 Lists
> An example is much clearer than an explanation here.
> =head2 Methods
> =over 12
I think that should be =over 4, since the example shows an indent of 4 from
> "new" Returns a new My::Module object.
> "as_string" Returns a stringified representation of the
> object. This is mainly for debugging purposes.