feedback on the draft documentation spec
Mark Stosberg
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
Damian Conway
...is *way* out of date. It predates the meeting Ingy, Larry, Audrey,
and I had in Tokyo, in which most of the kinks were ironed out. I have
a new draft of S26 with the design team at the moment, and am close to
having a first cut at a parser for that mark-up notation. The new Pod
looks very much like the old POD, only cleaned up and simplified.
Kinda like Perl 6 itself. Stay tuned. If I hear nothing more from the
design team, and if I can get the parser stable in the next week or
so, I'll post a new S26 here RSN.
Damian