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

[Ben Ward]

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