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

Wed Jun 11 13:26:26 PDT 2008

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
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 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