develooper Front page | perl.perl6.language | Postings from August 2006

feedback on the draft documentation spec

Thread Next
Mark Stosberg
August 25, 2006 20:41
feedback on the draft documentation spec
Message ID:

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

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.



Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About