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 consumption. 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."