@node perlpod, perlbook, perlstyle, Top
@unnumbered plain old documentation


@unnumberedsec NAME

perlpod - plain old documentation

@unnumberedsec DESCRIPTION

A pod-to-whatever translator reads a pod file paragraph by paragraph,
and translates it to the appropriate output format.  There are
three kinds of paragraphs:

@itemize @bullet
@item 
A verbatim paragraph, distinguished by being indented (that is,
it starts with space or tab).  It should be reproduced exactly,
with tabs assumed to be on 8-column boundaries.  There are no
special formatting escapes, so you can@'t italicize or anything
like that.  A \ means \, and nothing else.

@item 
A command.  All command paragraphs start with "=", followed by an
identifier, followed by arbitrary text that the command can
use however it pleases.  Currently recognized commands are

@example
=head1 heading
=head2 heading
=item text
=over N
=back
=cut
=pod
@end example

The "=pod" directive does nothing beyond telling the compiler to lay
off of through the next "=cut".  It@'s useful for adding another 
paragraph to the doc if you@'re mixing up code and pod a lot.  

Head1 and head2 produce first and second level headings, with the text on
the same paragraph as "=headn" forming the heading description.

Item, over, and back require a little more explanation: Over starts a
section specifically for the generation of a list using =item commands. At
the end of your list, use =back to end it. You will probably want to give
"4" as the number to =over, as some formatters will use this for indentation.
This should probably be a default. Note also that there are some basic rules
to using =item: don@'t use them outside of an =over/=back block, use at least
one inside an =over/=back block, you don@'t _have_ to include the =back if
the list just runs off the document, and perhaps most importantly, keep the
items consistent: either use "=item *" for all of them, to produce bullets,
or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use
"=item foo", "=item bar", etc., i.e., things that looks nothing like bullets
or numbers. If you start with bullets or numbers, stick with them, as many
formatters use the first =item type to decide how to format the list.  

And don@'t forget, when using any command, that that command lasts up until
the end of the @strong{paragraph}, not the line. Hence in the examples below, you
can see the blank lines after each command to end its paragraph.

Some examples of lists include:

@example
=over 4
@end example

@example
=item *
@end example

@example
First item
@end example

@example
=item *
@end example

@example
Second item
@end example

@example
=back
@end example

@example
=over 4
@end example

@example
=item Foo()
@end example

@example
Description of Foo function
@end example

@example
=item Bar()
@end example

@example
Description of Bar function
@end example

@example
=back
@end example

@item 
An ordinary block of text.  It will be filled, and maybe even
justified.  Certain interior sequences are recognized both
here and in commands:

@example
I<text>     italicize text, used for emphasis or variables
B<text>     embolden text, used for switches and programs
S<text>     text contains non-breaking spaces
C<code>	literal code 
L<name>     A link (cross reference) to name
		    L<name>		manpage
		    L<name/ident>	item in manpage
		    L<name/"sec">	section in other manpage
		    L<"sec">		section in this manpage
					(the quotes are optional)
		    L</"sec">		ditto
F<file>	Used for filenames
X<index>	An index entry
Z<>         A zero-width character
@end example

@end itemize
That@'s it.  The intent is simplicity, not power.  I wanted paragraphs
to look like paragraphs (block format), so that they stand out
visually, and so that I could run them through fmt easily to reformat
them (that@'s F7 in my version of @strong{vi}).  I wanted the translator (and not
me) to worry about whether " or @' is a left quote or a right quote
within filled text, and I wanted it to leave the quotes alone dammit in
verbatim mode, so I could slurp in a working program, shift it over 4
spaces, and have it print out, er, verbatim.  And presumably in a
constant width font.

In particular, you can leave things like this verbatim in your text:

@example
Perl
FILEHANDLE
$variable
function()
manpage(3r)
@end example

Doubtless a few other commands or sequences will need to be added along
the way, but I@'ve gotten along surprisingly well with just these.

Note that I@'m not at all claiming this to be sufficient for producing a
book.  I@'m just trying to make an idiot-proof common source for nroff,
TeX, and other markup languages, as used for online documentation.
Translators exist for pod2man  (that@'s for nroff(1) and troff(1)),
@strong{pod2html}, @strong{pod2latex}, and @strong{pod2fm}.

@unnumberedsec Embedding Pods in Perl Modules

You can embed pod documentation in your Perl scripts.  Start your
documentation with a =head1 command at the beg, and end it with 
an =cut command.  Perl will ignore the pod text.  See any of the
supplied library modules for examples.  If you@'re going to put
your pods at the end of the file, and you@'re using an __END__
or __DATA__ cut mark, make sure to put a blank line there before
the first pod directive.

@example
__END__
@end example

@example
=head1 NAME
@end example

@example
modern - I am a modern module
@end example

If you had not had that blank line there, then the translators wouldn@'t
have seen it.

@unnumberedsec SEE ALSO

@samp{pod2man} in this node and @samp{"PODs: Embedded Documentation"}, @xref{perlsyn,Perlsyn},

@unnumberedsec AUTHOR

Larry Wall

