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,

* 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

         +                     purely
   structural Pod  ------->  structural  -----------> plaintext
         +                      Pod      \----------> HTML
    semantic Pod                          \---------> XML
                                           \--------> roff
                                            \-------> MPEG

* 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';


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).

Reply via email to