Re: Perldoc Project

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 <[email protected]>
           Date: 14 Aug 2000
           Mailing List: [email protected]
           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