Programming Perl, 4th Edition

Flowed Text

The third type of paragraph is simply “flowed” text. That is, if a paragraph doesn’t start with either whitespace or an equals sign, it’s taken as a plain paragraph: regular text that’s typed in with as few frills as possible. Newlines are treated as equivalent to spaces. It’s largely up to the translator to make it look nice, because programmers have more important things to do. It is assumed that translators will apply certain common heuristics—see the section Pod Translators and Modules later in this chapter.

You can do some things explicitly, however. Inside either ordinary paragraphs or heading/item directives (but not in verbatim paragraphs) you may use special sequences to adjust the formatting. These sequences always start with a single capital letter followed by a left-angle bracket, and extend through the matching (not necessarily the next) right-angle bracket. Sequences may contain other sequences.

Here are the sequences defined by pod:

I<text>

Italicized text, used for emphasis, book titles, names of ships, and manpage references such as “perlpod(1)”.

B<text>

Emboldened text, used almost exclusively for command-line switches and sometimes for names of programs.

C<text>

Literal code, probably in a fixed-width font like Courier. Not needed on simple items that the translator should be able to infer as code, but you should put it anyway.

S<text>

Text with nonbreaking spaces. Often surrounds other sequences.

L<name>

A cross reference (link) to a name:

L<name>

Manual page