Steve Pitchford wrote:
> 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".Right. Since English is unofficially Perl's official human language (the specs are in English), it might be a good idea to keep the English version in place, and find a good way to synchronize other languages. For example the combination of 'name' and 'key' (or token name and key) should be uniq for each token, so it could be handled as a reference for other human languages. > 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? I don't like the idea of fiddling with the synopsis (because it makes "my" project seem "official", which makes me "responsible" which I don't like atm ;-). And with URIs you always have to take care that they are not broken. I know that the same applies for using name+key as a reference/anchor, but it's not a problem for the English version at least. > 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 ? ) I hope they will, because I don't think I can handle that alone, and my English might not be good enough for that purpose. Moritz -- Moritz Lenz http://moritz.faui2k3.org/ | http://perl-6.de/
signature.asc
Description: OpenPGP digital signature
