[Perl.sig] Plain old documentation- perl tip
Litss Coordinator
litss.coord at anu.edu.au
Mon Apr 11 14:13:39 EST 2005
==== News ====
Stas Bekman, author of of Practical mod_perl and mod_perl developer,
will be presenting mod_perl courses in Melbourne and Sydney during June
2005. Places must be booked by ``29th May 2005''. See end of tip for
more information.
==== Plain Old Documentation ====
In our previous tip we spoke about using ``perldoc'' to access
documentation about Perl. Most of the help pages ``perldoc'' accesses
are written in POD (plain old documentation). In this tip we're going
to
cover the basics of how to write POD.
POD is designed to be a simple, clean documentation language. It's
goals
are to be:
: * Easy to parse
: * Easy to convert to other formats (such as HTML and text)
: * Easy to write in, even with the addition of sample code
: * Easy to read in the native format.
Almost all Perl modules include their documentation in POD format.
Although this is occasionally done as ``.pod'' files it's much more
common to include the POD directly into the code. This has the
advantage
that it becomes much harder to accidently separate the code from its
documentation.
== Paragraphs ==
POD uses three kinds of paragraphs (text preceded by and followed by a
blank line). These are:
Text paragraphs
Plain text paragraphs which the formatter can reformat if required.
Code paragraphs
Text paragraphs which the formatter must not reformat. These
paragraphs are typically used for code. For example:
use strict;
my $test = 1;
You signal to the formatter that some text is a code paragraph by
starting each line in the paragraph with at least one space (or
tab)
character.
Command paragraphs
Unlike the previous two paragraph styles, the content of these
paragraphs are not seen by the user. These exist to signal to the
formatter which lines are for it to parse, and to provide some
indication of how you want your text to appear. POD command start
with the equals character (``='') in the first column and are
listed
below.
These are often called command *lines* however it should be
recognised that the specification for these *lines* is that they
appear on a line preceded and followed by blank lines. Thus a
paragraph.
``=head1'', ``=head2'' ...
These denote headings for first level, second level and so on.
For example:
=head1 Plain Old Documentation
``=pod''
Tells the POD formatter that this is the start of a section of
POD and thus to start formatting. This lasts until the ``=cut''
command is seen. This will cause the Perl interpreter to skip
this section.
``=cut''
Tells the POD formatter that this is the end of a section of
POD
and thus to stop. This will cause the Perl interpreter to
resume
looking for Perl code.
``=over n''
This moves the indent level over by n spaces. This is used for
creating itemized and descriptive lists.
``=item string''
This creates a list item with the descriptive term set to
``string''. Use an ``*'' (asterisk) to represent itemized
lists.
``=back''
Moves the indent level back to the level prior to the last
``=over''. This is used for closing the current list level.
``=for format'', ``=begin format'', ``=end''
POD allows you to write different content for different
formats.
Thus you might have a table created by spaces for text based
content, a html table and a LaTeX table each specified where
required. These commands provide this functionality. eg:
=for html
<table>
<tr><td>1</td><td>Rhymes with
sun</td></tr>
<tr><td>2</td><td>Rhymes with
shoe</td></tr>
</table>
=for text
1 Rhymes with sun
2 Rhymes with shoe
``=for'' applies only to the next paragraph whereas ``=begin''
will run until the next ``=end'' or ``=cut''.
That's almost it to writing POD. There are also few formatting codes to
allow you to specify ``bold'' text ( B<bold> ), *italicised* text
( I<italicised> ) and ``code'' style ( C<code> ) and similar effects.
You can read more about these in ``perldoc perlpodspec'' and
``perldoc perlpod''.
== An example ==
#!/usr/bin/perl -w
use strict;
# ...
# POD traditionally goes entirely at the top or entirely at the
# bottom of the file.
=pod
=head1 LoremIpsum.pm
=head2 Synopsis
use LoremIpsum;
aenean($dignissim);
vivamus($accumsan, $semper, $elit, $eget, $odio);
lacinia($nonummym $congue);
=head2 Description
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Mauris
nec wisi. Cras vitae justo. Nullam congue auctor libero.
Suspendisse ut libero et ante condimentum pellentesque. Donec
tincidunt.
Aenean dignissim. Proin elit nibh, placerat nec, lacinia
at, malesuada sit amet, nisl. In egestas pulvinar arcu.
Praesent in
neque nec elit gravida dictum. Aenean et pede nec purus
convallis
accumsan. Proin dolor. Donec id orci. Vivamus non augue feugiat
dolor viverra vehicula. Mauris vel wisi. Fusce in leo. Sed non
nulla. Fusce orci.
=over 4
=item C<aenean>
Aenean ultricies, ligula vel feugiat lobortis, arcu tortor
fermentum metus, ac rhoncus turpis lectus ac orci. Sed posuere
tellus in lectus eleifend rhoncus. Nam id massa.
=item C<vivamus>
Donec aliquam justo ut ante. Morbi tincidunt, sem a auctor
faucibus, felis leo blandit justo, in vestibulum felis dolor at
lorem.
=item C<lacinia>
Suspendisse lacinia sem eu ligula. Donec blandit molestie
nulla.
Fusce a augue. Vestibulum ante ipsum primis in faucibus orci
luctus et ultrices posuere cubilia Curae.
=back
=cut
1;
==== Upcoming Courses in Canberra ====
http://perltraining.com.au/bookings/Canberra.html
Introduction to Perl: 17th - 18th May
Intermediate Perl: 19th - 20th May
Database Programming with Perl: 23rd June
Perl Security: 24th June
Note that the ``Early Bird Date'' for the introduction courses is
``15 April 2005''!.
==== Upcoming Courses in Melbourne ====
http://perltraining.com.au/bookings/Melbourne.html
Database Programming with Perl: 26th May
Perl Security: 27th May
Getting started with mod_perl: 6th June
mod_perl 2.0, the next generation: 7th June
Object Oriented Perl: 7th - 8th July
Note that the ``Early Bird Date'' for the first four courses is
``29th April 2005''!.
==== Upcoming Courses in Sydney ====
http://perltraining.com.au/bookings/Sydney.html
Database Programming with Perl: 9th June
Perl Security: 10th June
Getting started with mod_perl: 13th June
mod_perl 2.0, the next generation: 14th June
Object Oriented Perl: 21st - 22nd July
Note that the ``Early Bird Date'' for the mod_perl courses is
``29th April 2005''!.
==== Corporate Courses ====
http://perltraining.com.au/corporate.html
Do you have a large group, or the need for training at a particular
time? Perl Training Australia is happy to arrange a course in the time
and place that best suits you. For more information read our page on
Corporate Courses at http://perltraining.com.au/corporate.html or call
us on +61-3-9354-6001.
_______________________________________________
This Perl tooltip and associated text is Copyright Perl Training Australia.
You may freely distribute this text so long as it is distributed in full
with this Copyright noticed attached.
If you have any questions please don't hesitate to contact us:
Email: contact at perltraining.com.au
Phone: 03 9354 6001
Perl-tips mailing list
To change your subscription details visit:
http://perltraining.com.au/cgi-bin/mailman/listinfo/perl-tips
More information about the Perl.sig
mailing list