Andy Armstrong wrote:
Yeah, that could work. I wonder which is more likely to gain traction:
* backwards compatible / slightly verbose
* incompatible / concise
I suppose either would be adopted if there were tools that made good use
of it. And the backwards compatible approach clearly has the advantage
of backwards compatibility :)
By my understanding, POD was never meant to be all that expressive, just
simple and straightforward. Sure, it's a weakness when you want to do
more complex stuff like assert extra semantics, but I think
over-engineering it would have been a mistake. I gave an "intro to POD"
talk recently and it took 20 minutes, after which I'm fairly sure the
beginners I was talking to could document their code in the proper Perl
manner. I think that's a Good Thing.
The backwards-compatibility thing is important if you want your docs to
be widely read by a disparate audience. Your suggested syntax renders a
document near-useless (totally missing headers, plus error messages) if
the POD reader isn't "enhanced POD" capable. That doesn't sound like a
recipe for gaining traction.... The drawback of extra verbosity is that
it requires documenters to remember to use it, though.
If you're developing an enhanced documentation system for, say,
departmental use, where you are able control the tools developers use,
then it's less of an issue. You could produce an EPOD-to-POD translator
that generates publicly-readable docs, but that seems like effort. You
could hide your EPOD docs with =begin/=end, but that seems... unfriendly.
Life would be so much easier if there weren't 1,000,001 ad-hoc POD
parsers out there.
Oh, but so much less fun! For some values of "fun".
Ian
