Front page | perl.perl6.documentation |
Postings from July 2003
Re: Perldoc Project
From: Nick Pinckernell
July 24, 2003 09:55
Re: Perldoc Project
Message ID: email@example.com
Ok, wow, didn't think I'd generate this much feedback.
First of all, let me say that yes, I agree, the perldoc name
for the sourceforge project is bad--I was going to change it.
Second, I was originally thinking about this for Perl 5.
However, after reading some of the Perl 6 RFC's I would want
to aim it at Perl 6, because there is still room for suggestion
in some of the internals.
Third, I also agree that POD is pretty cool. However, here
are a few things (taken from various sources, and one of
my own) that I think POD is a *little* lacking in.
I agree with the first three items right out of
1. IT'S NOT INTUITIVE
2. IT'S NOT DOCUMENTATION
BTW, I don't think the Perl 6 RFC 357 (XML for Documentation)
Is the way to go either, that would add too much extra text
in the documentation.
3. IT DOESN'T ENCOURAGE CONSISTENCY
3a. I have seen consistency with quite a few POD documents
Maintainer: Michael J. Mathews <firstname.lastname@example.org>
Date: 14 Aug 2000
Mailing List: email@example.com
But my question is, is that a standard way to write
the VERSION header, is the VERSION header even standard?
4. IT'S NOT STRICTLY STRUCTURED
A lot of the Perl POD documents, like
are very useful, but there is no 'standard'. Take the VERSION
head for example, if it were required for every POD document,
and Maintainer||Author and Date were required, it would be much
easier to read, because they would all have to be formatted
that way. Although, Date and Number, and maybe a few others
would exist, but be optional (yet, they would have to be
predefined, and if they weren't on the list of 'options' for
the VERSION head, then a standard POD reader wouldn't recognize
5. Currently, the POD directives require too much whitespace
(newlines too). For example, for POD to look write you have to
write it as:
works nicely, and does:
However, this doesn't:
Being addressed by http://dev.perl.org/rfc/216.html
My goal was attempting to emulate Javadoc in Perl, where some pod2html
documents would reference each other and everything, but POD already
does some of that.
I would just like to see POD become a little more strict.
And, after that post from Randal, I think I'll shut up.