On Wed, Mar 12, 2014 at 12:49 PM, John Levine <johnl@xxxxxxxxx> wrote:
If I may step out of the bikeshed for a moment, the editing part is
much harder than using whatever software checks in the edits.
The piece I find hard is always making sure that the text and code are in sync. I am very suspicious of a specification without any examples of on-the-wire data messages. But people try to avoid putting them in because examples are invariably considered to be the most normative text in a specification.
If I am implementing a spec with a 'non-normative' example that disagrees with some EBNF, unless it is obviously a mistake or there is an errata I will take the example because I know that is what 90% of implementers will go for and that is what will give me interoperability. Unless of course the objective is compliance rather than interop.
The problem comes when the spec is changed. Someone changes a tag at 23 points in the text but forget point 24. So someone has to go through and look and check.
So examples are essential but they are a huge liability. Which is why I built ProtoGen which is a protocol compiler that takes a schema that describes the abstract data structure, the mapping to on-the wire format (currently JSON and RFC822 style) and descriptive text. From these I generate the reference sections of the Internet Draft, a reference implementation and examples. It would also be possible to develop a conformance testing tool.
Website: http://hallambaker.com/