|
This section is intended to supplement and clarify the discussion in perlpod/"Command
Paragraph". These are the currently recognized Pod commands:
- "=head1",
"=head2", "=head3", "=head4"
-
This command indicates that the text in the remainder of the paragraph is a heading. That
text may contain formatting codes. Examples:
=head1 Object Attributes
=head3 What B<Not> to Do!
|
|
- "=pod"
-
This command indicates that this paragraph begins a Pod block. (If we are already in the
middle of a Pod block, this command has no effect at all.) If there is any text in this
command paragraph after "=pod", it must be ignored. Examples:
=pod
This is a plain Pod paragraph.
=pod This text is ignored.
|
|
- "=cut"
-
This command indicates that this line is the end of this previously started Pod block. If
there is any text after "=cut" on the line, it must be ignored. Examples:
=cut
=cut The documentation ends here.
=cut
# This is the first line of program text.
sub foo { # This is the second.
|
|
It is an error to try to start a Pod black with a "=cut" command. In
that case, the Pod processor must halt parsing of the input file, and must by default emit a
warning.
- "=over"
-
This command indicates that this is the start of a list/indent region. If there is any
text following the "=over", it must consist of only a nonzero positive numeral.
The semantics of this numeral is explained in the /"About
=over...=back Regions" section, further below. Formatting codes are not expanded.
Examples:
- "=item"
-
This command indicates that an item in a list begins here. Formatting codes are
processed. The semantics of the (optional) text in the remainder of this paragraph are
explained in the /"About =over...=back
Regions" section, further below. Examples:
=item
=item *
=item *
=item 14
=item 3.
=item C<< $thing->stuff(I<dodad>) >>
=item For transporting us beyond seas to be tried for pretended
offenses
=item He is at this time transporting large armies of foreign
mercenaries to complete the works of death, desolation and
tyranny, already begun with circumstances of cruelty and perfidy
scarcely paralleled in the most barbarous ages, and totally
unworthy the head of a civilized nation.
|
|
- "=back"
- This command indicates that this is the end of the region begun by the most recent
"=over" command. It permits no text after the "=back" command.
- "=begin formatname"
-
This marks the following paragraphs (until the matching "=end formatname") as
being for some special kind of processing. Unless "formatname" begins with a
colon, the contained non-command paragraphs are data paragraphs. But if "formatname"
does begin with a colon, then non-command paragraphs are ordinary paragraphs or data
paragraphs. This is discussed in detail in the section /About Data Paragraphs and
"=begin/=end" Regions.
It is advised that formatnames match the regexp m/\A:?[-a-zA-Z0-9_]+\z/.
Implementors should anticipate future expansion in the semantics and syntax of the first
parameter to "=begin"/"=end"/"=for".
- "=end formatname"
- This marks the end of the region opened by the matching "=begin formatname"
region. If "formatname" is not the formatname of the most recent open "=begin
formatname" region, then this is an error, and must generate an error message. This is
discussed in detail in the section /About Data Paragraphs and
"=begin/=end" Regions.
- "=for formatname text..."
-
This is synonymous with:
=begin formatname
text...
=end formatname
|
|
That is, it creates a region consisting of a single paragraph; that paragraph is to be
treated as a normal paragraph if "formatname" begins with a ":"; if
"formatname" doesn't begin with a colon, then "text..." will
constitute a data paragraph. There is no way to use "=for formatname text..." to
express "text..." as a verbatim paragraph.
If a Pod processor sees any command other than the ones listed above (like "=head",
or "=haed1", or "=stuff", or "=cuttlefish", or "=w123"),
that processor must by default treat this as an error. It must not process the paragraph
beginning with that command, must by default warn of this as an error, and may abort the parse.
A Pod parser may allow a way for particular applications to add to the above list of known
commands, and to stipulate, for each additional command, whether formatting codes should be
processed.
Future versions of this specification may add additional commands.
|
|
