Front page | perl.perl6.documentation |
Postings from July 2003
Re: Perldoc Project
Thread Previous
|
Thread Next
From:
Nick Pinckernell
Date:
July 24, 2003 09:55
Subject:
Re: Perldoc Project
Message ID:
perl.perl6.documentation-580@nntp.perl.org
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
http://dev.perl.org/rfc/5.pod
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
like:
=head1 VERSION
Maintainer: Michael J. Mathews <mmathews@oxygen.com>
Date: 14 Aug 2000
Mailing List: perl6-language-mlc@perl.org
Number: 5
Version: 3
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
-http://perldoc.com/perl5.8.0/pod/perlpod.html
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
them.
5. Currently, the POD directives require too much whitespace
(newlines too). For example, for POD to look write you have to
write it as:
=head1 TITLE
Simple Program
works nicely, and does:
=head1 TITLE
Simple Program
However, this doesn't:
=head1 TITLE
Simple Program
=head1 VERSION
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.
_nick
Thread Previous
|
Thread Next