David Storrs <[EMAIL PROTECTED]> wrote:
> Aside from links, that's pretty much the entire perlpodtut boiled down
> into 7 bullets; a little experimentation to get the hang of it and it
> all holds together nicely, easy to remember.

Yes, yes, yes.

Pod is one of the things Perl 5 did almost exactly right.  It's
simple, intuitive, and stays out of your way.  It gives you most of
the formatting primitives you actually *need*, and nicely balances the
need for easy-to-remember and easy-to-type formatting codes with the
need to avoid using them on accident.  It's a very clean,
low-punctuation format, which makes it visually distinctive from the
surrounding code.

Specifically, I like the use of angle brackets in Pod.  Angle brackets
are simple, distinctive shapes; they remain wide in variable-width
fonts; they're associated with formatting codes in my
(HTML-influenced) mind.  The most common use of them in Perl 5--method
call/dereference--is going away in Perl 6, which makes them even more
usable.  (I never have a problem correctly marking up C<< $foo > $bar
>>, but occasionally I carelessly type C<$foo->bar>.)

Pod needs incremental improvements--tables, (maybe) footnotes, simpler
links, tweaks to =begin/=end, etc.  Pod does *not* need to be ripped
out and replaced with something very different, especially something
that involves adding "line noise" to documents intended for human

In my mind at least, Pod has five goals:
1. Simple.
2. Adequate.
3. Easy to write.
4. Easy to convert.
5. Readable without a formatter.

#5 may be last on the list, but it's not least.

Brent 'Dax' Royal-Gordon <[EMAIL PROTECTED]>
Perl and Parrot hacker

"I used to have a life, but I liked mail-reading so much better."

Reply via email to