Larry and Thom have each ably explained the rhyme and reason of the choices
that we made for Pod 6. Here I will merely summarize those reasons, and answer
a specific question.
* Pod and Perl (or any other ambient source code) are to be syntactically
separated, even when there are semantic interconnections
* Perl 6 will be able to access ambient Pod via $=POD (and other
$=WHATEVER variables)
* It doesn't make sense for Pod to access ambient Perl, since Pod is a
passive mark-up notation, not an executable language
* It is self-evidently the case that documentation can be usefully
derived from source code, as well as from explicit mark-up
* That does not, however, mean that source code and explicit mark-up are
(or should be) either equivalent or syntactically commingled
* Rather, it means that the *tools* that extract such documentation need to
be able to extract it from both explicit mark-up and source code
* This will be possible in Perl 6, since both the Pod and Perl 6 parsers
will be accessible from Perl 6.
* Pod 6 is not a presentational mark-up scheme; in fact, it has no
presentational elements at all
* Pod 6 is both a structural and a semantic scheme; you can specify both the
structure of a document, and the meaning of its various components
* Structural mark-up features are entirely lower-case (=head, =item, =table)
at the block level, and single-letter upper-case (B<>, N<>, S<>) at the
embedded level
* Semantic mark-up features are entirely upper-case (=METHOD, =PURPOSE,
=DEFAULT)
* The semantic features are intended to be used to facilitate the creation and
use of tools that can autoextract documentation elements directly from code
* Such tools would (usually) convert the information extracted from
[source + semantic-Pod] into purely structural Pod, which could then
be fed to any suitable pod-to-whatever converter
* In other words, the tool-chain envisaged is something like:
perl6doc pod2whatever
source
+ purely
structural Pod -------> structural -----------> plaintext
+ Pod \----------> HTML
semantic Pod \---------> XML
\--------> roff
\-------> MPEG
\etc.
* Which means that Pod 6 needs to be a suitable pure-structural-mark-up
target language with an extensible semantic overlayer
* Which is precisely what it has already been designed to be
* To summarize the summary:
- Use Perl for what Perl is good for (specification)
- Use Pod for what Pod is good for (commentary)
- Then generate unified documentation by extracting information from
wherever its available (source or mark-up), according to what the
reader asks for
- The issue is not having sufficiently powerful Pod syntax;
the issue is having sufficiently powerful documentation-generating *tools*
To answer Mark's specific question:
> class Mail::Message {
> `base class for message types
>
> .has $msgid;
> `The (internet wide) unique string which identifies this
> `message object. May be undef as long as the message is
> `begin composed.
>
> .has $content_type = 'text/plain';
> }
>
> Damian, can you show how you would document the same code in POD6
> syntax to get a comparible short man-page?
Like so:
class Mail::Message {
=PURPOSE Base class for message types
has $msgid;
=for PURPOSE
The (internet wide) unique string which identifies this
message object. May be undef as long as the message is
begin composed.
has $content_type = 'text/plain';
}
Damian
PS: I agree that there needs to be a mechanism for abstracting names
within Pod and for extracting those names from ambient code. I will
propose such a mechanism and the syntax for it in a subsequent email
(probably early next week).
