On Sun, 1 Oct 2000, Adam Turoff wrote:
> POD has three mighty significant advantages over XML:
> - it is easy to learn
> - it is to write
> - it is easy to ignore, if you're spelunking for Perl code
> Try and do that, when <body> interferes with <STDIN> syntactically.
[snip]
> Moving towards a system that adds any friction to the documentation
> process is a *>HUGE<* mistake.
[snip]
> Increasing author effort may make for more beautiful documentation
> for the reader, but it also inhibits authoring content in the first
> place. It's quite possible that switching to an XML docset produces
> a beautiful, unmaintained set of documentation that is of no use
> to anyone.
I like these three paragraphs especially (because I agree with them). One
of the stated(?) goals of POD was to have a syntax so simple that it's
easy to do documentation. Everyone knows that programmers hate to document
stuff. So by providing them with a fairly minimal framework, the amount of
learning effort and the number of decisions required are fairly small,
increasing the chance that code will be documented. If people don't have
to worry about what should be fixed and what not (relying instead on smart
POD translators), they'll be more likely to go ahead an write.
I'm not sure that this bit of the third quoted paragraphs is correct:
"It's quite possible that switching to an XML docset produces a beautiful,
unmaintained set of documentation that is of no use to anyone." I think
it's more likely that switching to an XML docset produces very little
documentation, and what there is will be of widely varying quality. Not
everyone will want to expend the effort involved to plan out, carefully,
their document structure and produce lovely docs.
Cheers,
Philip
--
Philip Newton <[EMAIL PROTECTED]>
I appreciate copies of replies to my messages to Perl6 lists.
