Re: Perldoc Project

At 10:55 AM 2003-07-24 -0600, Nick Pinckernell wrote, of Pod:
>  1.  IT'S NOT INTUITIVE

IT ISN'T?  You can take normal English sentences alternating with 
codeblocks, put "=pod" before and =cut after, and it's got a 99% chance of 
being good as Pod.  That's pretty intuitive, for an intuitively intuitive 
definition of "intuitive".
Now try doing that with HTML!

>  2.  IT'S NOT DOCUMENTATION

So what is it when I write English prose that describes how to use a 
module?  Performance art?  Golly, that means I've been a pretty prolific 
performance artist over the years.  Can I get an NEA grant?

>      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'.

I think we need to settle on a standard definition of "standard" 
here.  There should be a standard for this.

By the way, how many standards on markup languages have you read?  I'd be 
particularly interested in hearing what you think of the SGML standard, as 
an informative document.

>  3.  IT DOESN'T ENCOURAGE CONSISTENCY
and:
>  4.  IT'S NOT STRICTLY STRUCTURED
>  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

If you want things to be standard, suggest them to the pod-people list, and 
we'll think about them.  It might even be something we've thought about 
before.  It might even be alluded to already in perlpodspec.
If we like the idea, we'll implement it in the parser and the standard or 
at least the podchecker.

>  5.  Currently, the POD directives require too much whitespace
>      (newlines too).  For example, for POD to look write you have to
>      write it as:

It's the result of a tradeoff.  Less whitespace would mean more explicit 
codes.  But there are advantages to the current situation (like you can 
freely reflow paragraphs with your editor, without having to say "oops, 
don't reflow the first line, that's the heading").

The current whitespace situation becomes a real problem only in cases where 
people are trying to apply a lot of formatting to relatively little 
content.  Pod is optimized for English prose plus codeblocks and the 
occasional heading or list-item.  So yeah, it happens to be suboptimal for 
cases like:

=over

=item Lower Paleolithic

c. 2 Million - 100,000 BC

=item Middle Paleolithic

100,000 - 30,000 BC

=item Upper Paleolithic

30,000 - 10,000 BC

=item Epipaleolithic Era

10000 - c. 5500 BC

=item Predynastic Period

5500 - 3100 BC

=back

compared to, say:

<dl>
<dt>Lower Paleolithic   <dd>c. 2 Million - 100,000 BC
<dt>Middle Paleolithic  <dd>100,000 - 30,000 BC
<dt>Upper Paleolithic   <dd>30,000 - 10,000 BC
<dt>Epipaleolithic Era  <dd>10000 - c. 5500 BC
<dt>Predynastic Period  <dd>5500 - 3100 BC
</dl>

But frankly, I don't see this as a /pressing/ problem.

--
Sean M. Burke    http://search.cpan.org/~sburke/