On Thu, Jul 24, 2003 at 10:55:42AM -0600, Nick Pinckernell wrote:
> I agree with the first three items right out of
> http://dev.perl.org/rfc/5.pod
> 1. IT'S NOT INTUITIVE
"Intuitive" is one of those meaningless buzzwords like "maintainable".
It sounds good, but it's meaningless. See MJD's take on "intuitive" here:
http://use.perl.org/~petdance/journal/12908
> 2. IT'S NOT DOCUMENTATION
The basis of this issue, from RFC5, is:
POD, of course stands for "Plain Old Documentation" but most of the time
comments are not intended to be included in documentation (separate from
the code). This is particularly true when using comments as a debugging
tool. This adds to the Not Intuitive, and Not Consistent problems
mentioned here.
This is a justification for *multi-line comments*, and Pod's the cheapest
way to get that in Perl5. The problem described above is that there are
three kinds of metadata in a Perl program:
- Documentation (in Pod)
- Comments
- Multiline comments
...and the lack of multiline comments leads to Pod abuse, which is bad.
> 3. IT DOESN'T ENCOURAGE CONSISTENCY
> 3a. I have seen consistency with quite a few POD documents [...]
You're referring to the Perl6 RFCs. They are consistently formatted
because I used a tool to pre-process them and post them to the relevant
lists for discussion. You can think of the Perl6 RFC format as
"Pod + epsilon". Pod is quite supportive of little extensions like
this, and that is a net benefit.
This, again, is a tools issue. If there's something significant missing
from Pod docs, the process to fix it is quite simple:
- improve the tools
- document the extensions
- convince people to start adding the extra metadata elements
> 4. IT'S NOT STRICTLY STRUCTURED
Yes, it's sub-optimal that elements such as VERSION, COPYRIGHT, AUTHOR
and DATE aren't explicitly structured. Throwing out the format for this
minor niggle is like building a yacht because your sailboat needs a fresh
coat of paint.
> 5. Currently, the POD directives require too much whitespace
> (newlines too). For example, for POD to look write you have to
> write it as:
I thought this was a problem. So I wrote a tool that was more flexible
and didn't require nearly as much whitespace. I wrote a book using that
format and tool.
That format sucked eggs. Adding *more* whitespace around block elements
and between blocks helped more than eliminating it. Compressing out the
"extraneous" whitespace is a false economy.
But don't take my word for it. Try it out yourself! Show us the code!
Z.
