Front page | perl.perl5.porters |
Postings from December 2004
Re: perlpodtut
Thread Previous
|
Thread Next
From:
Ronald J Kimball
Date:
December 24, 2004 08:56
Subject:
Re: perlpodtut
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
useful here.
> =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
the heading:
> Methods
> "new" Returns a new My::Module object.
>
> "as_string" Returns a stringified representation of the
> object. This is mainly for debugging purposes.
Ronald
Thread Previous
|
Thread Next