317 lines
9.7 KiB
Plaintext
317 lines
9.7 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> Render code in a typewriter font, or give some other
|
|
indication that this represents program text
|
|
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>
|
|
|
|
Most of the time, you will only need a single set of angle brackets to
|
|
delimit the beginning and end of interior sequences. However, sometimes
|
|
you will want to put a right angle bracket (or greater-than sign '>')
|
|
inside of a sequence. This is particularly common when using a sequence
|
|
to provide a different font-type for a snippet of code. As with all
|
|
things in Perl, there is more than one way to do it. One way is to
|
|
simply escape the closing bracket using an C<E> sequence:
|
|
|
|
C<$a E<lt>=E<gt> $b>
|
|
|
|
This will produce: "C<$a E<lt>=E<gt> $b>"
|
|
|
|
A more readable, and perhaps more "plain" way is to use an alternate set of
|
|
delimiters that doesn't require a ">" to be escaped. As of perl5.5.660,
|
|
doubled angle brackets ("<<" and ">>") may be used I<if and only if there
|
|
is whitespace immediately following the opening delimiter and immediately
|
|
preceding the closing delimiter!> For example, the following will do the
|
|
trick:
|
|
|
|
C<< $a <=> $b >>
|
|
|
|
In fact, you can use as many repeated angle-brackets as you like so
|
|
long as you have the same number of them in the opening and closing
|
|
delimiters, and make sure that whitespace immediately follows the last
|
|
'<' of the opening delimiter, and immediately precedes the first '>' of
|
|
the closing delimiter. So the following will also work:
|
|
|
|
C<<< $a <=> $b >>>
|
|
C<<<< $a <=> $b >>>>
|
|
|
|
This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
|
|
and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser
|
|
1.093 or later.
|
|
|
|
|
|
=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 need 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 B<podchecker> command is provided to check pod syntax
|
|
for errors and warnings. For example, it checks for completely
|
|
blank lines in pod segments and for unknown escape sequences.
|
|
It is still advised 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>, L<perlsyn/"PODs: Embedded Documentation">,
|
|
L<podchecker>
|
|
|
|
=head1 AUTHOR
|
|
|
|
Larry Wall
|
|
|