Chapter 4. Embedded Documentation

Tools exist to extract embedded documentation and generate input suitable for several formatters like troff, LATEX, and HTML. The following commands can be used to control embedded documentation:


See =over below.

=begin fmt

Sets the subsequent text up to a matching =end to be included only when processed for formatter fmt.


Ends a document section.

=end fmt

See =begin.

=for fmt

Restricts the remainder of just this paragraph to be included only when processed for formatter fmt.

=headN heading

Produces a heading. N must be 1, 2, 3, or 4.

=item text

See =over below.

=over N

Starts an enumeration with indent N. Items are specified using =item. The enumeration is ended with =back.


Introduces a document section. Any of the = commands can be used to introduce a document section.

Each of the preceding commands applies to the paragraph of text that follows them; paragraphs are terminated by at least one empty line.

An indented paragraph is considered to be verbatim text and will be rendered as such.

Within normal paragraphs, markup sequences can be inserted:


Bold text (for switches and programs).


Literal code.


A named character, e.g., E<lt> means a < and E<gt> means a >.




Italic text (for emphasis and variables).

L< [ text | ] [ ref ] [ / section ] >

A cross reference. text, if present, is used for output.


Text that cannot break on spaces.


An index entry.


A zero-width character.

Markup sequences may be nested. If a markup sequence has to contain > characters, use C<< ... >> or C<<< . . . >>>, etc. The last of the opening < must be followed by whitespace, and whitespace must precede the first of the closing >.

perlpod, perlpodspec.

Get Perl Pocket Reference, 4th Edition now with the O’Reilly learning platform.

O’Reilly members experience live online training, plus books, videos, and digital content from nearly 200 publishers.