290 lines
8.2 KiB
Plaintext
290 lines
8.2 KiB
Plaintext
|
=head1 NAME
|
||
|
|
|
||
|
|
perlpod - plain old documentation
|
||
|
|
|
||
|
|
=head1 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:
|
||
|
|
L<verbatim|/"Verbatim Paragraph">,
|
||
|
|
L<command|/"Command Paragraph">, and
|
||
|
|
L<ordinary text|/"Ordinary Block of Text">.
|
||
|
|
|
||
|
|
|
||
|
|
=head2 Verbatim Paragraph
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
=head2 Command Paragraph
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
=head1 heading
|
||
|
|
=head2 heading
|
||
|
|
=item text
|
||
|
|
=over N
|
||
|
|
=back
|
||
|
|
=cut
|
||
|
|
=pod
|
||
|
|
=for X
|
||
|
|
=begin X
|
||
|
|
=end X
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item =pod
|
||
|
|
|
||
|
|
=item =cut
|
||
|
|
|
||
|
|
The "=pod" directive does nothing beyond telling the compiler to lay
|
||
|
|
off parsing code through the next "=cut". It's useful for adding
|
||
|
|
another paragraph to the doc if you're mixing up code and pod a lot.
|
||
|
|
|
||
|
|
=item =head1
|
||
|
|
|
||
|
|
=item =head2
|
||
|
|
|
||
|
|
Head1 and head2 produce first and second level headings, with the text in
|
||
|
|
the same paragraph as the "=headn" directive forming the heading description.
|
||
|
|
|
||
|
|
=item =over
|
||
|
|
|
||
|
|
=item =back
|
||
|
|
|
||
|
|
=item =item
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
|
||
|
|
=item =for
|
||
|
|
|
||
|
|
=item =begin
|
||
|
|
|
||
|
|
=item =end
|
||
|
|
|
||
|
|
For, begin, and end let you include sections that are not interpreted
|
||
|
|
as pod text, but passed directly to particular formatters. A formatter
|
||
|
|
that can utilize that format will use the section, otherwise it will be
|
||
|
|
completely ignored. The directive "=for" specifies that the entire next
|
||
|
|
paragraph is in the format indicated by the first word after
|
||
|
|
"=for", like this:
|
||
|
|
|
||
|
|
=for html <br>
|
||
|
|
<p> This is a raw HTML paragraph </p>
|
||
|
|
|
||
|
|
The paired commands "=begin" and "=end" work very similarly to "=for", but
|
||
|
|
instead of only accepting a single paragraph, all text from "=begin" to a
|
||
|
|
paragraph with a matching "=end" are treated as a particular format.
|
||
|
|
|
||
|
|
Here are some examples of how to use these:
|
||
|
|
|
||
|
|
=begin html
|
||
|
|
|
||
|
|
<br>Figure 1.<IMG SRC="figure1.png"><br>
|
||
|
|
|
||
|
|
=end html
|
||
|
|
|
||
|
|
=begin text
|
||
|
|
|
||
|
|
---------------
|
||
|
|
| foo |
|
||
|
|
| bar |
|
||
|
|
---------------
|
||
|
|
|
||
|
|
^^^^ Figure 1. ^^^^
|
||
|
|
|
||
|
|
=end text
|
||
|
|
|
||
|
|
Some format names that formatters currently are known to accept include
|
||
|
|
"roff", "man", "latex", "tex", "text", and "html". (Some formatters will
|
||
|
|
treat some of these as synonyms.)
|
||
|
|
|
||
|
|
And don't forget, when using any command, that the command lasts up until
|
||
|
|
the end of the B<paragraph>, not the line. Hence in the examples below, you
|
||
|
|
can see the empty lines after each command to end its paragraph.
|
||
|
|
|
||
|
|
Some examples of lists include:
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item *
|
||
|
|
|
||
|
|
First item
|
||
|
|
|
||
|
|
=item *
|
||
|
|
|
||
|
|
Second item
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item Foo()
|
||
|
|
|
||
|
|
Description of Foo function
|
||
|
|
|
||
|
|
=item Bar()
|
||
|
|
|
||
|
|
Description of Bar function
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
|
||
|
|
=head2 Ordinary Block of Text
|
||
|
|
|
||
|
|
It will be filled, and maybe even
|
||
|
|
justified. Certain interior sequences are recognized both
|
||
|
|
here and in commands:
|
||
|
|
|
||
|
|
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> manual page
|
||
|
|
L<name/ident> item in manual page
|
||
|
|
L<name/"sec"> section in other manual page
|
||
|
|
L<"sec"> section in this manual page
|
||
|
|
(the quotes are optional)
|
||
|
|
L</"sec"> ditto
|
||
|
|
same as above but only 'text' is used for output.
|
||
|
|
(Text can not contain the characters '/' and '|',
|
||
|
|
and should contain matched '<' or '>')
|
||
|
|
L<text|name>
|
||
|
|
L<text|name/ident>
|
||
|
|
L<text|name/"sec">
|
||
|
|
L<text|"sec">
|
||
|
|
L<text|/"sec">
|
||
|
|
|
||
|
|
F<file> Used for filenames
|
||
|
|
X<index> An index entry
|
||
|
|
Z<> A zero-width character
|
||
|
|
E<escape> A named character (very similar to HTML escapes)
|
||
|
|
E<lt> A literal <
|
||
|
|
E<gt> A literal >
|
||
|
|
E<sol> A literal /
|
||
|
|
E<verbar> A literal |
|
||
|
|
(these are optional except in other interior
|
||
|
|
sequences and when preceded by a capital letter)
|
||
|
|
E<n> Character number n (probably in ASCII)
|
||
|
|
E<html> Some non-numeric HTML entity, such
|
||
|
|
as E<Agrave>
|
||
|
|
|
||
|
|
|
||
|
|
=head2 The Intent
|
||
|
|
|
||
|
|
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 B<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:
|
||
|
|
|
||
|
|
Perl
|
||
|
|
FILEHANDLE
|
||
|
|
$variable
|
||
|
|
function()
|
||
|
|
manpage(3r)
|
||
|
|
|
||
|
|
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 B<pod2man> (that's for nroff(1) and troff(1)),
|
||
|
|
B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
|
||
|
|
|
||
|
|
|
||
|
|
=head2 Embedding Pods in Perl Modules
|
||
|
|
|
||
|
|
You can embed pod documentation in your Perl scripts. Start your
|
||
|
|
documentation with a "=head1" command at the beginning, and end it
|
||
|
|
with a "=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 an empty line there before the first pod
|
||
|
|
directive.
|
||
|
|
|
||
|
|
__END__
|
||
|
|
|
||
|
|
|
||
|
|
=head1 NAME
|
||
|
|
|
||
|
|
modern - I am a modern module
|
||
|
|
|
||
|
|
If you had not had that empty line there, then the translators wouldn't
|
||
|
|
have seen it.
|
||
|
|
|
||
|
|
|
||
|
|
=head2 Common Pod Pitfalls
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item *
|
||
|
|
|
||
|
|
Pod translators usually will require paragraphs to be separated by
|
||
|
|
completely empty lines. If you have an apparently empty line with
|
||
|
|
some spaces on it, this can cause odd formatting.
|
||
|
|
|
||
|
|
=item *
|
||
|
|
|
||
|
|
Translators will mostly add wording around a LE<lt>E<gt> link, so that
|
||
|
|
C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see
|
||
|
|
B<pod2man> for details). Thus, you shouldn't write things like C<the
|
||
|
|
LE<lt>fooE<gt> manpage>, if you want the translated document to read
|
||
|
|
sensibly.
|
||
|
|
|
||
|
|
If you don need or want total control of the text used for a
|
||
|
|
link in the output use the form LE<lt>show this text|fooE<gt>
|
||
|
|
instead.
|
||
|
|
|
||
|
|
=item *
|
||
|
|
|
||
|
|
The script F<pod/checkpods.PL> in the Perl source distribution
|
||
|
|
provides skeletal checking for lines that look empty but aren't
|
||
|
|
B<only>, but is there as a placeholder until someone writes
|
||
|
|
Pod::Checker. The best way to check your pod is to pass it through
|
||
|
|
one or more translators and proofread the result, or print out the
|
||
|
|
result and proofread that. Some of the problems found may be bugs in
|
||
|
|
the translators, which you may or may not wish to work around.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head1 SEE ALSO
|
||
|
|
|
||
|
|
L<pod2man> and L<perlsyn/"PODs: Embedded Documentation">
|
||
|
|
|
||
|
|
=head1 AUTHOR
|
||
|
|
|
||
|
|
Larry Wall
|
||
|
|
|