Perl6::Spec::Documentation is a draft spec for documentation formats for
use with Perl6.
My own reading of it is that POD still exists and is supported, while a
new wiki-like format "kwid" is added, and a framework for various
dialects is supported.
POD was successful for its simplicity. It was easy to learn, and since
it was simple and a subset of just about everything, it was easy to
translate into many formats.
Kwid is an upgrade to POD that recognizes the success of wiki-like
formats, which are themselves relatively simple, and are pleasantly
easy to read without a kwid2SomethingElse translator.
Considering just about everything but the semicolon seems to be changing
from Perl5 to Perl6, I have no problem replacing POD with Kwid. POD was
easy to learn, and Kwid looks easier.
I'm not sold on the on the generic documentation-framework-with-dialects
though.
The spec opens with this:
"Perldoc is a documentation format specification that is completely
orthogonal to the Perl 6 specification."
If that's the case, what the Perl6 spec says about documentation doesn't
need to stop the broader Perldoc framework project from existing or
being used.
I advocate what the Perl6 spec does say is that Kwid is the official
documentation format of Perl6. Let simplicity succeed again.
Mark
Reference:
http://svn.openfoundry.org/pugs/docs/Perl6/Spec/Documentation.pod
