POD (was RE: [Doc-SIG] using the same delimiter on the left and right..)
Thu, 29 Mar 2001 14:40:53 -0500
[Tony J Ibbs (Tibs)
> Pod is used successfully in the Perl world, and is a clear winner there.
> I find it intensely unreadable, as a lightweight format.
> I haven't seen too much POD, so you may be right there. Is it worse
> than Latex?
Well, you can include LaTeX sections in POD, so formally I guess it can't be
Here's the POD spec:
It's smaller than half the msgs in this debate <0.9 wink -- but it's really
not enough of "a spec" to answer all practical questions>. Do note that
perlpod.html was generated from a POD doc, though.
Short course: the input is broken into paragraphs (via blank-line
separation). A paragraph then falls into one of three categories: verbatim,
command or ordinary text.
Verbatim is like a Python raw-string: *nothing* about it is altered. A
paragraph is verbatim iff its first line begins with whitespace.
If there isn't a space or tab in the first line, it's a command paragraph or
plain text. A command paragraph begins with "=" immediately followed by an
identifier. There are two commands (=head1 and =head2) for headings; three
for dealing with lists (=item, =over, =back); three for embedding docs in
formats other than POD (like HTML or LaTeX, or verbatim text that doesn't
happen to begin with whitespace; =for, =begin, =end); and a couple for
telling the Perl compiler where POD sections begin and end (=pod, =cut).
That's it for commands.
Everything else is ordinary text. There are 8 inline markup gimmicks, of the
"X<" text goes here ">"
where X is a single character, covering italics, bold, text with non-breaking
spaces, literal code, cross-reference links, filenames, index entries, and
Z<> for a zero-width character. Also entity-like "&" escapes.
In practice, I rarely see escapes other than C<the code escape>, and it's
*nice* to have a wholly unambiguous way to include code snippets inline. The
list gimmicks (=over, =item, =back) are visually jarring the first times you
see them; in return, you never get a list by mistake; OTOH, if you want
numbered lists, you supply the numbers yourself; on the fourth hand, if you
want unusual list item bullets or numbering, you just type what you want.
It's easy to use, and is mostly idiot-proof. OTOH, it's not *obvious* at
first glance, particularly not the list stuff. But it's a matter of no more
than two minutes to *learn* the list conventions, and then they're easy too.
pod-is-a-lot-more-pythonic-then-perl-ly y'rs - tim