This is a raw HTML paragraph
=end html The command "=for formatname text..." specifies that the remainder of just this paragraph (starting right after formatname) is in that spe- cial format. =for html
This is a raw HTML paragraph
This means the same thing as the above "=begin html" ... "=end html" region. That is, with "=for", you can have only one paragraph's worth of text (i.e., the text in "=foo targetname text..."), but with "=begin target- name" ... "=end targetname", you can have any amount of stuff in be- tween. (Note that there still must be a blank line after the "=begin" command and a blank line before the "=end" command.) Here are some examples of how to use these: =begin html
" -- code text
Renders code in a typewriter font, or gives some other indication that
this represents program text (""C"") or some other form of
computerese (""C"").
"L" -- a hyperlink
There are various syntaxes, listed below. In the syntaxes given,
"text", "name", and "section" cannot contain the characters '/' and
'|'; and any '<' or '>' should be matched.
* "L"
Link to a Perl manual page (e.g., "L"). Note that
"name" should not contain spaces. This syntax is also occasionally
used for references to Unix man pages, as in "L".
* "L" or "L"
Link to a section in other manual page. E.g., "L"
* "L" or "L"
Link to a section in this manual page. E.g., "L"
A section is started by the named heading or item. For example,
"L" or "L" both link to the section started
by ""=item $."" in perlvar. And "L" or "L" both link to the section started by ""=head2 For
Loops"" in perlsyn.
To control what text is used for display, you use ""L"", as
in:
* "L"
Link this text to that manual page. E.g., "L"
* "L" or "L"
Link this text to that section in that manual page. E.g., "L"
* "L" or "L" or "L"
Link this text to that section in this manual page. E.g., "L"
Or you can link to a web page:
* "L"
"L"
Links to an absolute URL. For example, "L" -- a character escape
Very similar to HTML/XML "&foo;" "entity references":
* "E" -- a literal < (less than)
* "E" -- a literal > (greater than)
* "E" -- a literal | (vertical bar)
* "E" -- a literal / (solidus)
The above four are optional except in other formatting codes, no-
tably "L<...>", and when preceded by a capital letter.
* "E"
Some non-numeric HTML entity name, such as "E", meaning the
same thing as "é" in HTML -- i.e., a lowercase e with an
acute (/-shaped) accent.
* "E"
The ASCII/Latin-1/Unicode character with that number. A leading
"0x" means that number is hex, as in "E<0x201E>". A leading "0"
means that number is octal, as in "E<075>". Otherwise number is
interpreted as being in decimal, as in "E<181>".
Note that older Pod formatters might not recognize octal or hex nu-
meric escapes, and that many formatters cannot reliably render
characters above 255. (Some formatters may even have to use com-
promised renderings of Latin-1/CP-1252 characters, like rendering
"E" as just a plain "e".)
"F" -- used for filenames
Typically displayed in italics. Example: ""F<.cshrc>""
"S" -- text contains non-breaking spaces
This means that the words in text should not be broken across lines.
Example: "S<$x ? $y : $z>".
"X" -- an index entry
This is ignored by most formatters, but some may use it for building
indexes. It always renders as empty-string. Example: "X"
"Z<>" -- a null (zero-effect) formatting code
This is rarely used. It's one way to get around using an E<...> code
sometimes. For example, instead of ""NE3"" (for "N<3") you could
write ""NZ<><3"" (the "Z<>" breaks up the "N" and the "<" so they can't
be considered the part of a (fictitious) "N<...>" code).
Another use is to indicate that stuff in "=item Z<>stuff..." is not to
be considered to be a bullet or number. For example, without the
"Z<>", the line
=item Z<>500 Server error
could possibly be parsed as an item in a numbered list when it isn't
meant to be.
Still another use is to maintain visual space between "=item" lines.
If you specify
=item foo
=item bar
it will typically get rendered as
foo
bar
That may be what you want, but if what you really want is
foo
bar
you can use "Z<>" to accomplish that
=item foo
Z<>
=item bar
Most of the time, you will need only a single set of angle brackets to de-
limit the beginning and end of formatting codes. However, sometimes you
will want to put a real right angle bracket (a greater-than sign, '>') in-
side of a formatting code. This is particularly common when using a for-
matting code 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 "E" code:
C<$a E=E $b>
This will produce: ""$a <=> $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. Doubled angle
brackets ("<<" and ">>") may be used 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:
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.
(The whitespace is ignored.) So the following will also work:
C<<< $a <=> $b >>>
C<<<< $a <=> $b >>>>
And they all mean exactly the same as this:
C<$a E=E $b>
The multiple-bracket form does not affect the interpretation of the con-
tents 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=E $b >>
As a further example, this means that if you wanted to put these bits of
code in "C" (code) style:
open(X, ">>thing.dat") || die $!
$foo->bar();
you could do it like so:
C<<< open(X, ">>thing.dat") || die $! >>>
C<< $foo->bar(); >>
which is presumably easier to read than the old way:
CEthing.dat") || die $!>
C<$foo-Ebar();>
This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man),
and any other pod2xxx or Pod::Xxxx translators that use Pod::Parser 1.093
or later, or Pod::Tree 1.02 or later.
The Intent
The intent is simplicity of use, not power of expression. Paragraphs 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 vi, or Esc Q in my version of emacs). I wanted the transla-
tor to always leave the "'" and "`" and """ quotes alone, in verbatim mode,
so I could slurp in a working program, shift it over four spaces, and have
it print out, er, verbatim. And presumably in a monospace font.
The Pod format is not necessarily sufficient for writing a book. Pod is
just meant to be an idiot-proof common source for nroff, HTML, TeX, and
other markup languages, as used for online documentation. Translators ex-
ist for pod2text, pod2html, pod2man (that's for nroff(1) and troff(1)),
pod2latex, and pod2fm. Various others are available in CPAN.
Embedding Pods in Perl Modules
You can embed Pod documentation in your Perl modules and scripts. Start
your documentation with an empty line, a "=head1" command at the beginning,
and end it with a "=cut" command and an empty line. The perl executable
will ignore the Pod text. You can place a Pod statement where perl expects
the beginning of a new statement, but not within a statement, as that would
result in an error. See any of the supplied library modules for examples.
If you're going to put your Pod at the end of the file, and you're using an
"__END__" or "__DATA__" cut mark, make sure to put an empty line there be-
fore the first Pod command.
__END__
=head1 NAME
Time::Local - efficiently compute time from local and GMT time
Without that empty line before the "=head1", many translators wouldn't have
recognized the "=head1" as starting a Pod block.
Hints for Writing Pod
*
The podchecker command is provided for checking Pod syntax for errors
and warnings. For example, it checks for completely blank lines in Pod
blocks and for unknown commands and formatting codes. You should still
also pass your document 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.
* If you're more familiar with writing in HTML than with writing in Pod,
you can try your hand at writing documentation in simple HTML, and con-
verting it to Pod with the experimental Pod::HTML2Pod module, (avail-
able in CPAN), and looking at the resulting code. The experimental
Pod::PXML module in CPAN might also be useful.
* Many older Pod translators require the lines before every Pod command
and after every Pod command (including "=cut"!) to be a blank line.
Having something like this:
# - - - - - - - - - - - -
=item $firecracker->boom()
This noisily detonates the firecracker object.
=cut
sub boom {
...
...will make such Pod translators completely fail to see the Pod block
at all.
Instead, have it like this:
# - - - - - - - - - - - -
=item $firecracker->boom()
This noisily detonates the firecracker object.
=cut
sub boom {
...
* Some older Pod translators require paragraphs (including command para-
graphs like "=head2 Functions") to be separated by completely empty
lines. If you have an apparently empty line with some spaces on it,
this might not count as a separator for those translators, and that
could cause odd formatting.
* Older translators might add wording around an L<> link, so that
"L" may become "the Foo::Bar manpage", for example. So you
shouldn't write things like "the L documentation", if you want the
translated document to read sensibly. Instead, write "the
L documentation" or "L", to control how the link comes out.
* Going past the 70th column in a verbatim block might be ungracefully
wrapped by some formatters.
SEE ALSO
perlpodspec, "PODs: Embedded Documentation" in perlsyn, perlnewmod, perl-
doc, pod2html, pod2man, podchecker.
AUTHOR
Larry Wall, Sean M. Burke
perl v5.44.0 2026-06-22 PERLPOD(1)