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">.
-=over 4
-
-=item *
+=head2 Verbatim Paragraph
A verbatim paragraph, distinguished by being indented (that is,
it starts with space or tab). It should be reproduced exactly,
special formatting escapes, so you can't italicize or anything
like that. A \ means \, and nothing else.
-=item *
+=head2 Command Paragraph
-A command. All command paragraphs start with "=", followed by an
+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
+ =head3 heading
+ =head4 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 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 indention.
-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 you 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
+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
+
+=item =head3
+
+=item =head4
+
+Head1, head2, head3 and head4 produce first, second, third and fourth
+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.
+The unit of indentation is optional. If the unit is not given the natural
+indentation of the formatting system applied will be used. 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 blank lines after each command to end it's paragraph.
+can see the empty lines after each command to end its paragraph.
Some examples of lists include:
=back
-=item *
+=back
+
+=head2 Ordinary Block of Text
-An ordinary block of text. It will be filled, and maybe even
+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
+ 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> manpage
- L<name/ident> item in manpage
- L<name/"sec"> section in other manpage
- L<"sec"> section in this manpage
+ 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
+ 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
+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.
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<pod2html>, B<pod2latex>, and B<pod2fm>.
+B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>.
-=head1 Embedding Pods in Perl Modules
+=head2 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.
+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__
modern - I am a modern module
-If you had not had that blank line there, then the translators wouldn't
+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> and L<perlsyn/"PODs: Embedded Documentation">
+L<pod2man>, L<perlsyn/"PODs: Embedded Documentation">,
+L<podchecker>
=head1 AUTHOR
projects / p5sagit/p5-mst-13.2.git / blobdiff