POD (was RE: [Doc-SIG] using the same delimiter on the left and right..)

[Tim Peters]

[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.

[Guido]
> 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
better <wink>.

Here's the POD spec:

    http://www.cpan.org/doc/manual/html/pod/perlpod.html

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
form

     "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