Page 1 of 1

Clear and understandable format spec writing

Posted: Wed Feb 08, 2012 7:24 pm
by finale00
Graphics, audio, images, 3D, etc.
There doesn't seem to be a set standard for spec-writing.

Some of it can be very technical, or very verbose.
Some people are really comfortable with technical specs, while others probably not so much.

Any ideas on making easy-to-understand yet precise format specs?

There's only a finite set of types to work with. Signed values?

Structs would make sense. Defined in-line? Separately?

Array syntax? C-like syntax? Even with an array of structs?

Code: Select all

uint16[10] some ints...

Vertex[20] vertices...
What about strings? Null-terminated strings? Strings with specific encodings? I would like an easy way to say "this is a null-terminated string".
I've been used char_/0 lol

What are some good or bad specs you've seen?

Re: Clear and understandable format spec writing

Posted: Wed Feb 08, 2012 9:07 pm
by Rheini
I just use 010 editor binary templates.

Re: Clear and understandable format spec writing

Posted: Wed Feb 08, 2012 9:16 pm
by howfie
I love reading specifications. Html5, c, c+ +, ecmascript, opengl, sql, certain rfcs... Fun shit. By far the most ugly and most difficult I've read is the sql spec. It is flat out nasty. Every paragraph is filled with two and three letter abbreviations. By far the easiest one to read is html and css specs. Most rfcs are pretty bland too and are difficult to follow because they say stuff like refer to some other rfc for this, another rfc for that... For example the zlib one is pretty bad but the nntp protocol one is very easy.

Re: Clear and understandable format spec writing

Posted: Fri Feb 10, 2012 7:44 am
by Dinoguy1000
The wiki uses a reasonably straightforward method of laying out specs, though said method was originally designed with archive formats in mind and therefore may not be quite developed enough for all image, audio, model, etc. formats.