Hackathon #3: P6Doc is reborn!

The P6Doc sub-project has started again, building on the hierarchy sketched out by Skud and Andrew Savige a while ago.  We are taking material from the design documents, various quick references and other documents in the Pugs  docs tree, and present them in an accessible fashion.

Currently, they are divided into five categories: Overview, Tutorial, FAQ, Spec and API.  Moving quickrefs into Overview/Tutorial/FAQ is an ongoing task -- commits are most welcome. :-)

The Spec category contains both the normative Synopses, such as Perl6::Spec::Operator (aka S03), as well as various drafts, such as Perl6::Spec::Concurrency (previously known as S17draft).  Non-binding drafts are clearly marked as such -- a conforming Perl 6 implementation does not need to implement them, until the design team promote them into normative specs.

I hope that using words (the Rules Spec and Perl6::Spec::Rules) instead of numbers (the 5th Synopsis or Perl6::Bible::S05) will make lookup and discussion easier, and free the partitioning of language specification from the Camel book's chapters.

Also, I have removed references to the historical Apocalypse documents from the Synopses text, to make them more self-contained.  Consequently, if there are some part of Apocalypse missing from the specs, they need to be copied over, or be considered non-normative.

While the Spec documents talk about language (aka requirement specification for Perl 6 implementors), the API documents spell out how the core objects are exposed on the language level, and is thus aimed at people writing Perl 6 programs.

For example, Perl6::API::Code and Perl6::API::Sigs will enumerate the public methods of a &code object and its signatures, including lexical pad, references to outer scopes, and so on.  Similarily, Perl6::API::Object and Perl6::API::Class would define the metaobject protocol; Perl6::API::Rule and Perl6::API::Grammar would define the interfaces to the rules engine.

In other words, the API documents capture our current approach in building a self-hosting Perl 6 implementation, and gives Pugs backend authors a concrete set of API, so the backends can implement them as primitives to replace the portable-but-slower bootstrap code written in Perl 6.

It is important to stress that currently all Perl6::API documents within the Pugs tree are considered non-binding drafts.  There may very well be other Perl 6 implementations with a better API, for example using Parrot-native objects instead of Perl 6 objects to represent core types, and they will still be conforming implementations.  However, we still choose to call them (non-normative) Perl6::API instead of Pugs::API, as the bootstrap code can run on any Perl 6 implementation conforming to the Synopses.

Currently, the P6Doc files are installed along with Pugs, into Perl5's sitelib path and formatted as manpages.  We plan to release them separately on CPAN and replace the current Perl6::Bible distribution, and work on the bundled p6doc program to provide additional features, such as full-text search and explain this Perl 6 code snippet.

Comments

[grumpY!]

audrey, the more i read your blogs the more i see you as the heir apparent to larry in the perl world. i sincerely hope you will give us a state of the onion style presentation of your experiences in perl world at somer point. bravo and thanks for all of us lurkers.

[Randal L. Schwartz]

Thank you... your inspiration has revitalized the Perl6 effort, and will make my job easier when I have to come along and make a perl6 llama and alpaca and cookbook and camel and ...