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