like "perldoc perlpod".
=head1 NAME
+X<POD> X<plain old documentation>
perlpod - the Plain Old Documentation format
=head2 Ordinary Paragraph
+X<POD, ordinary paragraph>
Most paragraphs in your documentation will be ordinary blocks
of text, like this one. You can simply type in your text without
=head2 Verbatim Paragraph
+X<POD, verbatim paragraph> X<verbatim>
Verbatim paragraphs are usually used for presenting a codeblock or
other text which does not require any special parsing or formatting,
=head2 Command Paragraph
+X<POD, command>
A command paragraph is used for special treatment of whole chunks
of text, usually as headings or parts of lists.
the command can use however it pleases. Currently recognized commands
are
+ =pod
=head1 Heading Text
=head2 Heading Text
=head3 Heading Text
=over indentlevel
=item stuff
=back
- =cut
- =pod
=begin format
=end format
=for format text...
+ =encoding type
+ =cut
To explain them each in detail:
=over
=item C<=head1 I<Heading Text>>
+X<=head1> X<=head2> X<=head3> X<=head4>
+X<head1> X<head2> X<head3> X<head4>
=item C<=head2 I<Heading Text>>
"L<Formatting Codes|/"Formatting Codes">" section, below.
=item C<=over I<indentlevel>>
+X<=over> X<=item> X<=back> X<over> X<item> X<back>
=item C<=item I<stuff...>>
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. -- namely, things that look nothing like bullets or
+"=item bar", etc.--namely, things that look nothing like bullets or
numbers.
If you start with bullets or numbers, stick with them, as
=back
=item C<=cut>
+X<=cut> X<cut>
To end a Pod block, use a blank line,
then a line beginning with "=cut", and a blank
is not technically necessary, but many older Pod processors require it.)
=item C<=pod>
+X<=pod> X<pod>
The "=pod" command by itself doesn't do much of anything, but it
signals to Perl (and Pod formatters) that a Pod block starts here. A
=cut
=item C<=begin I<formatname>>
+X<=begin> X<=end> X<=for> X<begin> X<end> X<for>
=item C<=end I<formatname>>
will be completely ignored.
A command "=begin I<formatname>", some paragraphs, and a
-command "=end I<formatname>", mean that the text/data inbetween
+command "=end I<formatname>", mean that the text/data in between
is meant for formatters that understand the special format
called I<formatname>. For example,
normal formatting (e.g., may not be a normal-use paragraph, but might
be for formatting as a footnote).
+=item C<=encoding I<encodingname>>
+X<=encoding> X<encoding>
+
+This command is used for declaring the encoding of a document. Most
+users won't need this; but if your encoding isn't US-ASCII or Latin-1,
+then put a C<=encoding I<encodingname>> command early in the document so
+that pod formatters will know how to decode the document. For
+I<encodingname>, use a name recognized by the L<Encode::Supported>
+module. Examples:
+
+ =encoding utf8
+
+ =encoding koi8-r
+
+ =encoding ShiftJIS
+
+ =encoding big5
+
=back
-And don't forget, when using any command, that the command lasts up
+C<=encoding> affects the whole document, and must occur only once.
+
+And don't forget, when using any other command, that the command lasts up
until the end of its I<paragraph>, not its line. So in the
examples below, you can see that every command needs the blank
line after it, to end its paragraph.
=head2 Formatting Codes
+X<POD, formatting code> X<formatting code>
+X<POD, interior sequence> X<interior sequence>
In ordinary paragraphs and in some command paragraphs, various
formatting codes (a.k.a. "interior sequences") can be used:
=over
=item C<IE<lt>textE<gt>> -- italic text
+X<I> X<< IZ<><> >> X<POD, formatting code, italic> X<italic>
Used for emphasis ("C<be IE<lt>careful!E<gt>>") and parameters
("C<redo IE<lt>LABELE<gt>>")
=item C<BE<lt>textE<gt>> -- bold text
+X<B> X<< BZ<><> >> X<POD, formatting code, bold> X<bold>
Used for switches ("C<perl's BE<lt>-nE<gt> switch>"), programs
("C<some systems provide a BE<lt>chfnE<gt> for that>"),
("C<and that feature is known as BE<lt>autovivificationE<gt>>").
=item C<CE<lt>codeE<gt>> -- code text
+X<C> X<< CZ<><> >> X<POD, formatting code, code> X<code>
Renders code in a typewriter font, or gives some other indication that
this represents program text ("C<CE<lt>gmtime($^T)E<gt>>") or some other
form of computerese ("C<CE<lt>drwxr-xr-xE<gt>>").
=item C<LE<lt>nameE<gt>> -- a hyperlink
+X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink> X<hyperlink>
There are various syntaxes, listed below. In the syntaxes given,
C<text>, C<name>, and C<section> cannot contain the characters
Link to a Perl manual page (e.g., C<LE<lt>Net::PingE<gt>>). Note
that C<name> should not contain spaces. This syntax
-is also occasionally used for references to UNIX man pages, as in
+is also occasionally used for references to Unix man pages, as in
C<LE<lt>crontab(5)E<gt>>.
=item *
=item *
-C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>> or C<LE<lt>"sec"E<gt>>
+C<LE<lt>/"sec"E<gt>> or C<LE<lt>/secE<gt>>
Link to a section in this manual page. E.g.,
C<LE<lt>/"Object Methods"E<gt>>
C<LE<lt>text|name/"sec"E<gt>> or C<LE<lt>text|name/secE<gt>>
Link this text to that section in that manual page. E.g.,
-C<LE<lt>SWITCH statements|perlsyn/"Basic BLOCKs and Switch
-Statements"E<gt>>
+C<LE<lt>postfix "if"|perlsyn/"Statement Modifiers"E<gt>>
=item *
C<LE<lt>scheme:...E<gt>>
-Links to an absolute URL. For example,
-C<LE<lt>http://www.perl.org/E<gt>>. But note
-that there is no corresponding C<LE<lt>text|scheme:...E<gt>> syntax, for
-various reasons.
+C<LE<lt>text|scheme:...E<gt>>
+
+Links to an absolute URL. For example, C<LE<lt>http://www.perl.org/E<gt>> or
+C<LE<lt>The Perl Home Page|http://www.perl.org/E<gt>>.
=back
=item C<EE<lt>escapeE<gt>> -- a character escape
+X<E> X<< EZ<><> >> X<POD, formatting code, escape> X<escape>
Very similar to HTML/XML C<&I<foo>;> "entity references":
=back
=item C<FE<lt>filenameE<gt>> -- used for filenames
+X<F> X<< FZ<><> >> X<POD, formatting code, filename> X<filename>
Typically displayed in italics. Example: "C<FE<lt>.cshrcE<gt>>"
=item C<SE<lt>textE<gt>> -- text contains non-breaking spaces
+X<S> X<< SZ<><> >> X<POD, formatting code, non-breaking space>
+X<non-breaking space>
This means that the words in I<text> should not be broken
across lines. Example: S<C<SE<lt>$x ? $y : $zE<gt>>>.
=item C<XE<lt>topic nameE<gt>> -- an index entry
+X<X> X<< XZ<><> >> X<POD, formatting code, index entry> X<index entry>
This is ignored by most formatters, but some may use it for building
indexes. It always renders as empty-string.
Example: C<XE<lt>absolutizing relative URLsE<gt>>
=item C<ZE<lt>E<gt>> -- a null (zero-effect) formatting code
+X<Z> X<< ZZ<><> >> X<POD, formatting code, null> X<null>
This is rarely used. It's one way to get around using an
EE<lt>...E<gt> code sometimes. For example, instead of
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 single ">" to be escaped. With
-the Pod formatters that are standard starting with perl5.5.660, doubled
-angle brackets ("<<" and ">>") may be used I<if and only if there is
+set of delimiters that doesn't require a single ">" to be escaped.
+Doubled angle brackets ("<<" and ">>") may be used I<if and only if there is
whitespace right after the opening delimiter and whitespace right
before the closing delimiter!> For example, the following will
do the trick:
+X<POD, formatting code, escaping with multiple brackets>
C<< $a <=> $b >>
'<' of the opening delimiter, and immediately precedes the first '>'
of the closing delimiter. (The whitespace is ignored.) So the
following will also work:
+X<POD, formatting code, escaping with multiple brackets>
C<<< $a <=> $b >>>
C<<<< $a <=> $b >>>>
C<$a E<lt>=E<gt> $b>
+The multiple-bracket form does not affect the interpretation of the contents of
+the formatting code, only how it must end. That means that the examples above
+are also exactly the same as this:
+
+ C<< $a E<lt>=E<gt> $b >>
+
As a further example, this means that if you wanted to put these bits of
code in C<C> (code) style:
Pod::Parser 1.093 or later, or Pod::Tree 1.02 or later.
=head2 The Intent
+X<POD, intent of>
The intent is simplicity of use, not power of expression. Paragraphs
look like paragraphs (block format), so that they stand out
=head2 Embedding Pods in Perl Modules
+X<POD, embedding>
You can embed Pod documentation in your Perl modules and scripts.
Start your documentation with an empty line, a "=head1" command at the
=over
=item *
+X<podchecker> X<POD, validating>
The B<podchecker> command is provided for checking Pod syntax for errors
and warnings. For example, it checks for completely blank lines in
Older translators might add wording around an LE<lt>E<gt> link, so that
C<LE<lt>Foo::BarE<gt>> may become "the Foo::Bar manpage", for example.
So you shouldn't write things like C<the LE<lt>fooE<gt>
-documentation>, if you want the translated document to read sensibly
--- instead write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
+documentation>, if you want the translated document to read sensibly.
+Instead, write C<the LE<lt>Foo::Bar|Foo::BarE<gt> documentation> or
C<LE<lt>the Foo::Bar documentation|Foo::BarE<gt>>, to control how the
link comes out.
https://perl5.git.perl.org / perl5.git / blobdiff