Moritz Lenz wrote:
Dave Whipp wrote:
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 { '*' {*} }
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 STD.pm.
My approach so far (see <http://svn.pugscode.org/pugs/misc/perlhints/>)
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 ? )
Steve
