Mark Overmeer wrote:
>> Would the following syntax suffice?
>>
>> method isValidPostalCode(str $postalcode) returns bool {...}
>> =PURPOSE Check weather the postal code confirms to the standards
>> =ARG $postalcode
>> a string with blanks trimmed.
>> =RETURN
>> the string is not cleaned-up.
>>
>> Because you can already do precisely that in the current design of Pod 6.
>
> This is syntactically what can be done with the current design,
> but is semantically very different.
I don't think so. It's all just mark-up, no matter what the specific
syntax looks like. The semantics are provided by the behaviour of the tools
that parse and interpret that mark-up. If the tools treat:
=ARG $postalcode
a string with blanks trimmed.
the same as they treat:
`$postalcode: a string with blanks trimmed.
then semantically the two are exactly the same.
> Besides the point that I do not really like the YELLING all the time,
So you create a Pod module that defines "quieter" user-defined block names,
and write:
=use OOdoc:ver<6.0.0>
method isValidPostalCode(str $postalcode) returns bool {...}
=Purpose Check weather the postal code confirms to the standards
=Arg $postalcode
a string with blanks trimmed.
=Return
the string is not cleaned-up.
> You gave the hint that comments are also in the parse tree.
They can be. Better still, the (raw) Pod can also be kept in the parse
tree...since, like comments, the Perl parser still has to recognize it, even
when it's focusing on extracting Perl.
> So, that is sufficient for me:
And for others too, I hope.
Defining Perl 6 and Pod 6 independently opens up so many options for
building documentation tools:
* As you've observed, you can build them on top of the Perl 6
parser, using any mark-up syntax that will fit in a comment;
* And, as I've indicated, you can build them on top of
the Pod parser, using the standard Pod syntax;
* Or you can build them on top of the Perl 6 parser, but using the
standard Pod syntax...by parsing Pod from within the appropriate
nodes of the Perl AST using the Pod parser;
* Or you can build them on top of the Pod parser, using the standard
Pod syntax, by parsing any code-bearing "ambient" nodes within the
Pod DOM using the Perl 6 parser;
* Or you can even build them by using *both* parsers at once and
then walking the two resulting hierarchical representations (AST
and DOM) in parallel, since Perl 6 has very good support for such
concurrent tree traversals.
I don't believe any one of those alternatives will prove to be *the*
universal best approach for implementing all documentation tools, but I
do believe that having all those alternatives will make it as easy as
possible for us to collectively create the best tools for the each of
the many approaches to documentation that the Perl community is
ultimately going to want to support.
And that's what keeping Perl 6 and Pod 6 separate buys you: choice,
options, alternatives, the possibility of creating very different styles
of documentation for very different styles of programming. And for
different kinds of programmer: for the Busy Documentor, tools that
extract documentation automatically from code; for the Exacting
Documentor, a structural mark-up that allows precise manual control over
what's documented...and how; for the Pragmatic Documentor, tools that
allow structural mark-up and automatic extraction to be sensibly mixed.
And therefore I see the very fact that you don't like my design of Pod 6
as a strong argument in *favour* of that design, since that design aims
to provide the necessary syntactic extensibility and the essential
building blocks (parser, DOM, module support) required for the
proponents of each individual documentation philosophy to create a
mark-up system and supporting tools best suited to their specific needs
and objectives.
Damian
