|
(Note that in previous drafts of this document and of perlpod, formatting codes were referred
to as "interior sequences", and this term may still be found in the documentation for
Pod parsers, and in error messages from Pod processors.)
There are two syntaxes for formatting codes:
-
A formatting code starts with a capital letter (just US-ASCII [A-Z]) followed by a
"<", any number of characters, and ending with the first matching
">". Examples:
That's what I<you> think!
What's C<dump()> for?
X<C<chmod> and C<unlink()> Under Different Operating Systems>
|
|
-
A formatting code starts with a capital letter (just US-ASCII [A-Z]) followed by two or
more "<"'s, one or more whitespace characters, any number of characters, one or
more whitespace characters, and ending with the first matching sequence of two or more
">"'s, where the number of ">"'s equals the number of
"<"'s in the opening of this formatting code. Examples:
That's what I<< you >> think!
C<<< open(X, ">>thing.dat") || die $! >>>
B<< $foo->bar(); >>
|
|
With this syntax, the whitespace character(s) after the "C<<<" and
before the ">>" (or whatever letter) are not renderable -- they do
not signify whitespace, are merely part of the formatting codes themselves. That is, these
are all synonymous:
C<thing>
C<< thing >>
C<< thing >>
C<<< thing >>>
C<<<<
thing
>>>>
|
|
and so on.
In parsing Pod, a notably tricky part is the correct parsing of (potentially nested!)
formatting codes. Implementors should consult the code in the parse_text routine in
Pod::Parser as an example of a correct implementation.
I<text> -- italic text
- See the brief discussion in perlpod/"Formatting
Codes".
B<text> -- bold text
- See the brief discussion in perlpod/"Formatting
Codes".
C<code> -- code text
- See the brief discussion in perlpod/"Formatting
Codes".
F<filename> -- style
for filenames
- See the brief discussion in perlpod/"Formatting
Codes".
X<topic name> -- an index
entry
-
See the brief discussion in perlpod/"Formatting
Codes".
This code is unusual in that most formatters completely discard this code and its
content. Other formatters will render it with invisible codes that can be used in building
an index of the current document.
Z<> -- a null
(zero-effect) formatting code
-
Discussed briefly in perlpod/"Formatting
Codes".
This code is unusual is that it should have no content. That is, a processor may complain
if it sees Z<potatoes>. Whether or not it complains, the potatoes
text should ignored.
L<name> -- a hyperlink
- The complicated syntaxes of this code are discussed at length in perlpod/"Formatting
Codes", and implementation details are discussed below, in /"About L<...> Codes". Parsing the
contents of L<content> is tricky. Notably, the content has to be checked for whether
it looks like a URL, or whether it has to be split on literal "|" and/or
"/" (in the right order!), and so on, before E<...> codes are
resolved.
E<escape> -- a character
escape
- See perlpod/"Formatting
Codes", and several points in /Notes
on Implementing Pod Processors.
S<text> --
text contains non-breaking spaces
-
This formatting code is syntactically simple, but semantically complex. What it means is
that each space in the printable content of this code signifies a nonbreaking space.
Consider:
C<$x ? $y : $z>
S<C<$x ? $y : $z>>
|
|
Both signify the monospace (c[ode] style) text consisting of "$x", one space,
"?", one space, ":", one space, "$z". The difference is that
in the latter, with the S code, those spaces are not "normal" spaces, but instead
are nonbreaking spaces.
If a Pod processor sees any formatting code other than the ones listed above (as in
"N<...>", or "Q<...>", etc.), that processor must by default
treat this as an error. A Pod parser may allow a way for particular applications to add to the
above list of known formatting codes; a Pod parser might even allow a way to stipulate, for each
additional command, whether it requires some form of special processing, as L<...> does.
Future versions of this specification may add additional formatting codes.
Historical note: A few older Pod processors would not see a ">" as closing a
"C<" code, if the ">" was immediately preceded by a "-".
This was so that this:
would parse as equivalent to this:
instead of as equivalent to a "C" formatting code containing only "$foo-",
and then a "bar>" outside the "C" formatting code. This problem has since
been solved by the addition of syntaxes like this:
Compliant parsers must not treat "->" as special.
Formatting codes absolutely cannot span paragraphs. If a code is opened in one paragraph, and
no closing code is found by the end of that paragraph, the Pod parser must close that formatting
code, and should complain (as in "Unterminated I code in the paragraph starting at line
123: 'Time objects are not...'"). So these two paragraphs:
I<I told you not to do this!
Don't make me say it again!>
|
|
...must not be parsed as two paragraphs in italics (with the I code starting in one
paragraph and starting in another.) Instead, the first paragraph should generate a warning, but
that aside, the above code must parse as if it were:
I<I told you not to do this!>
Don't make me say it again!E<gt>
|
|
(In SGMLish jargon, all Pod commands are like block-level elements, whereas all Pod
formatting codes are like inline-level elements.)
|
|
