Moritz Lenz wrote:
You're probably right about that, but somebody who writes his own macros
and operators probably doesn't need such a tool anyway. And should write
very good documentation, otherwise he has lost outright.
(I was thinking that your tool would provide a mechanism for them to
provide that "very good" documentation)
I think the way to approach it would be to define a
POD6 dialect what provides the necessary markup. The standard grammar
would contain this, as would things like prelude. But anyone would be
able to add it to any code they distribute so as to provide more
comprehensive debug info.
Of course that would be the best solution, but I don't see how I can
implement that soonish. Do you have good idea how to do it?
One approach would simply be to edit Perl-6.0.0-STD.pm and add some
markup. To pick a token at random:
=p6explain *
An asterix in a version expression matches any version
=end
token whatever { '*' {*} }
This would have the advantage of better documenting the meaning of all
the tokens/rules in the grammar file, which isn't always immediately
obvious from reading it.
Damian's POD Parser can probably do much of the work of actually finding
the "p6explain" blocks. Establishing a formal link between these and the
token/rule might be more work; but probably isn't necessary, except for
linting purposes.
Dave.
