Front page | perl.perl6.documentation |
Postings from July 2003
Re: Perldoc Project
From: Luke Palmer
July 24, 2003 00:09
Re: Perldoc Project
Message ID: email@example.com
Iain Truskett wrote:
> * Nick Pinckernell (firstname.lastname@example.org) [24 Jul 2003 14:50]:
> > The idea is: a structured Javadoc style system for Perl. It would be
> > very dependant on multiline comments (I've seen the Perl 6 RFC).
> Why so?
> > I think this idea would be really good for Perl 6,
> > because, in my opinion, POD is lacking.
> Could you please elaborate on this point?
> POD does lack many things, but why is a javadoc based system
> any better?
I'd just like to say a couple things about my feelings on POD.
POD is wonderful. Here's why:
1. It's simple and easy to learn.
2. It can be placed anywhere, in any kind of text, and painlessly
stripped out with a one-liner.
3. It can be easily read without a special formatter.
4. It doesn't mandate anything about what it's documenting. It
provides optimizations for code (eg. indenting = verbatim), but
there are no special sequences telling the computer what is being
documented. I'll talk about why this is a win below.
Basically, it's focus is simplicity. There are thousands of modules
on the CPAN, and I've only seen one or two that were poorly
documented. #1 is the one that did that.
Because of #2, I document everything with POD. My C code, my E2
writeups (and convert them), just everything. Parrot does too. And
it's easy to do; it doesn't pose any limitations on what I can use it
in or for.
#3 is obvious.
#4 is really important. It fits Perl's culturally dynamic nature.
You can write modules which don't use an OO interface, which don't
even define any subs, and you document them just like you document
#5: There's Only One Way To Do It. While this is opposite Perl's
usual philosophy, it works well with documentation. It means that you
don't (can't) get caught up in the meticulous details of formatting
(which I so often do when I use LaTeX), and it forces you to focus on
So that's my praise of POD.
Indeed, it could use a few changes. For instance, the paragraph rules
could be relaxed to allow for more condensed lists, etc. But those
are the details -- the thing that was so right about POD was the