develooper Front page | perl.perl6.language | Postings from March 2005

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

Thread Previous | Thread Next
Brent 'Dax' Royal-Gordon
March 17, 2005 02:17
Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]
Message ID:
David Storrs <> 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 <>
Perl and Parrot hacker

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

Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About