[uf-dev] How do we (want to) document parsing?

[anders conbere]

On Wed, Jun 11, 2008 at 1:26 PM, Ben Ward <lists at ben-ward.co.uk> wrote:
> Parser devs,
>
> I've been carrying on work on speccing value-excerpting, I'm keen that we
> set a good example of specifying parsing rules with this, with a view to
> requiring a higher standard in future and also going back to better spec the
> other patterns and microformats.
>
> To be honest, I'm underqualified for this. Actually, wait, that's not true,
> I'm amply qualified but haven't applied any of my knowledge of representing
> processes and so forth in the real world. Anyway, digression.
>
> I have, for better, worse or more likely embarrassment, put together a
> shoddy flow chart of how parsing of the value-excerption-pattern could work,
> factoring in the open issue of parsing @titles from empty elements (I'm
> working on the issues one at a time).
>
> We don't have uploading enabled on the wiki, so it's here:
> -ward.co.uk/microformats/value-excerption-pattern/ValueExcerptionParseFlowChart.png

I'm not getting an image back here.

>
> My question is simple, in creating it I came across one open issue with the
> parsing flow, so it's been useful to do, but I need to know is it actually
> useful documentation  in itself? Would you refer to something diagrammatic
> when implementing a parser? Or is there some other, better (perhaps more
> Wiki compatible) means of representing parsing rules and method branching
> that we should adopt? Would pseudo-code be sufficient?

I've been a big fan of representing the parsing rules in terms of
claim or triples. This is how rdf describes it's parsing rules, and
allows for easily codified tests.

~ Anders

>
> I know test cases are also a big thing, and I'll produce some of those as
> well as I work through the issue log.
>
> Thanks,
>
> Ben
> _______________________________________________
> microformats-dev mailing list
> microformats-dev at microformats.org
> http://microformats.org/mailman/listinfo/microformats-dev
>