Moritz Lenz wrote:

Dave Whipp wrote:
One approach would simply be to edit and add some markup. To pick a token at random:

=p6explain *
An asterix in a version expression matches any version
token whatever { '*' {*} }

You convinced me, in-place documentation is probably the best.

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.

Which leads me to the question how to do the annotation.

First of all I hope there are no objections against fiddling with

My approach so far (see <>)
has been to write blocks for each token like so:

key:  *
name: Regex Quantifier *
dsl:  Regex
syn:  <token>*
desc: matches <token> zero or more times
ex:   'ab'*  # matches the empty string, ab, abab, ababab, ...
link: S05:somwhere

A problem with this might be the lack of multiple language support - especially for the description.

I'm not sure if you would want docs expanded to huge size to fit every language in the sun and beyond, but can see real strengths in allowing it to be inline in order to "get it done".

What might be nice ( from my perspective - others may hate it ) is assigning a URI to each unique instance, so that multiple language support could be tagged on afterwards, and it could also help with the link section ( or replace it by reversing the link to many to one rather than one to one ) - if the synopsis were adjusted to reference these URIs then the linking info would flow back in the other direction?

The key for your index would then become the URI, and the database could then be hosted elsewhere ( of course, developers may wish to make there code contain something similar to the above to help with creating your data ? )


Reply via email to