Dave Whipp wrote: > 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)
Let's hope it does that some day ;)
It was not my original goal, but it's quite tempting ;)
>>> 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 { '*' {*} }
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
(key: the character(s) that the token stands for; name: a uniq name;
dsl: the domain-specific language the token occurs in (empty if "plain"
p6; syn: synopsis. desc: description (one to three lines usually); ex:
example; link: reference to the official specs).
It has the advantage of being easily parsable, less character/line noise
and no need for any escapes (expect newlines).
However it is not very PODish, so I'd like to ask for other opinions on
the used markup.
With the link: thing we could actually generate smartlinks that tell you
which part of the synopsis are parsed by which token in STD.pm (Agent
Zhang, are you paying attention? ;-). Do you think that would be desirable?
Moritz
--
Moritz Lenz
http://moritz.faui2k3.org/ | http://perl-6.de/
signature.asc
Description: OpenPGP digital signature
