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 CONSISTENCYand:
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/
