S26 grant proposal

Synopsis 26[1] outlines a new Pod format for Perl 6, one which simplifies and
generalizes features of POD, and also enables bidirectional communication
between the ambient language (typically Perl 6) and the documentation language
(Pod).

The synopsis is clear, complete and self-consistent, but a good guess is that
contact with a Perl 6 implementation will lead to a number of small updates,
corrections, and improvements. Furthermore, in a few known places S26 and
S02[2] (outlining basic syntax and language fundamentals) need to be updated
with respect to each other.

Through the grant outlined by this proposal, I aim to provide Rakudo with a
Pod parser, a Pod data model, and the ability to introspect the Pod data model
from Perl 6 code, or serialize it to pure text and HTML. Parallel to this, I
will update the spec, and write spectests to provide coverage for the new
features.

I know of three implementations of the Perl 6 Pod. The first is CPAN's
Perl6::Perldoc::Parser[3], written by Damian Conway. The second is CPAN's
Perl6::Pod[4], written by Zahatski Aliaksandr. The third is Pod::Parser[5],
written by Martin Berends. The former two are Perl 5 modules, while the
latter is a Perl 6 module. To my knowledge, only Damian Conway's module is
full-featured, to the extent possible without a surrounding Perl 6
implementation with Pod support. Some of the newer features of S26 (such as
the A<> formatting code) are not reflected in the module.

As part of the grant, I will have a look at each of these implementations, to
gather ideas both for how to implement things in Rakudo, as well as the subtle
points and corner cases implied by the spec.

The grant breaks down into the following milestones:

* Make Rakudo parse paragraph blocks.

* Make Rakudo parse abbreviated blocks.

* [There are four types of blocks in Pod. Rakudo already parses the other
  two kinds, delimited blocks and declarator blocks]

* Implement parsing of the pod, para, code, input, output, head, list, item,
  nested, comment, and Semantic subclasses of Pod::Block in Rakudo.

* Implement $=POD introspection in Rakudo. Make it contain a hierarchy of
  the script's Pod::Block::* objects.

* Implement parsing of the B, C, D, E, I, K, L, M, N, P, R, S, T, U, V, X and Z
  formatting codes in Rakudo.

* Implement the --doc command-line option in Rakudo, causing a script not to
  run but rather to have its Pod contents output as text.

* Implement the --doc=html variant in Rakudo, causing the Pod contents to be
  output as HTML.

[1] http://perlcabal.org/syn/S26.html
[2] http://perlcabal.org/syn/S02.html
[3] http://search.cpan.org/~dconway/Perl6-Perldoc-v0.0.5/lib/Perl6/Perldoc/Parser.pm
[4] http://search.cpan.org/dist/Perl6-Pod/lib/Perl6/Pod.pm
[5] http://github.com/perl6/perl6-examples/tree/master/lib/Pod/