hgm wrote:I made a draft for a new specification document of CECP, attempting to get rid of anything that is general programming advice on how to implement pipe I/O, and stuff that only describes XBoard peculiarities. I do not consider it 100% finished, but except for very rare or never-implemented stuff, most should be there now.
I would like to have some feedback on whether this is indeed a step in the right direction, or what else could be done to improve the presentation.
For me, a table version of the specification would be more clear. I mean:
Maybe you can then write a single paragraph to specify the details, after the table of the syntax.
As mentioned by other, some communication sample would be a must.
The "signals" part should be moved at the end of the document, to keep the protocol itself separated from its technical implementation details (the most of the chess engines works on Windows, as far as I know).
PS: The pseudo-code is not really pseudo-code but C... personally I hate the concept of "pseudo-code" in any context, because it simply hide some kind of language; we often find pseudo-code that is pseudo-C or pseudo-JAVa or pseudo-Pascal... it would be more clear if we call it simply "C code". Anybody who doesn't know X can't read pseudo-X code... so why to try to make it readable only calling it "pseudo-X"?
Does the ping mechanism start with 0 or 1?
Are all following pings in order 1, 2, 3, 4, ..., N, N+1, ...?
The engine would then recognise everything else as error.
Great job Harm!
Just spit-balling, but maybe some sort of index as a fixed position sidebar with inpage anchor links to get around and see what the document contains at a glance?
Harald wrote:Does the ping mechanism start with 0 or 1?
Are all following pings in order 1, 2, 3, 4, ..., N, N+1, ...?
The engine would then recognise everything else as error.
XBoard starts at 1, but the original specs do not require anything. The GUI designer can use this freedom to his advantage. The only significance of the numbering is that it makes it easier to match the pins and the pongs, but even that is redundant, as the GUI could also simply have counted them (assuming the engine is compliant), as the pings have to be answered in the order they were received. So I guess you could even design a GUI to always send 'ping 666'.
Maybe you can then write a single paragraph to specify the details, after the table of the syntax.
I have some difficulty imagining this. It seems that it would easily get much longer than it is now, if the 'description' in the table would be the same text as I have now, and I am not sure what the 'notes' would be. The pseudo-code is already a sort of single-line tabular description of most the commands.
As mentioned by other, some communication sample would be a must.
OK, I will add that as another appendix.
PS: The pseudo-code is not really pseudo-code but C...
Well, it is more JavaScript than C. Things like command == "new" would not really work very well in C.
Anybody who doesn't know X can't read pseudo-X code... so why to try to make it readable only calling it "pseudo-X"?
I am not so sure of that. Most languages are pretty much the same, and support the concept of variables, assignment, function calls and if-statements. I don't think people that would know Fortran, BASIC or Pascal would have much trouble understanding that code. And it doesn't require much imagination to understand that {} are used for grouping.
I am not very happy about constructs like StringToNumber(line+7), though. I will probably rewrite that by introducing a variable
params = RemainderOf(line);
behind command = FirstWord(line), so that the execution of the command can refer to 'params'.
As the descriptions of the engine->gui and gui->engine commands in the document are interleaved I would add a visual clue (perhaps using color) to indicate the command direction.
Ideas=science. Simplification=engineering.
Without ideas there is nothing to simplify.
hgm wrote:I would like to have some feedback on whether this is indeed a step in the right direction, or what else could be done to improve the presentation.
* Place the Signals section before Handshake to make Handshake as clear as possible
and that understanding Signals should come first.
* Under Handshake place done=1 as its last part before Basic commands. This would allow
a clearer picture regarding the end of the Handhake. Although done=1 is described
under feature NAME=VALUE, it just complicates the description of feature.
* Perhaps place ping N under Basic commands, this would simplify the Handshake too.
* Describe more about ping N (give an example situation) especially that you are
recommending this to be somewhat mandatory.
* Indicate which of these commands are mandatory so that developers will get an
idea of where to focus first on the protocol.
* Indicate which commands/words required a reply from the engine.
hgm wrote:[...]
I have some difficulty imagining this. It seems that it would easily get much longer than it is now, if the 'description' in the table would be the same text as I have now, and I am not sure what the 'notes' would be. The pseudo-code is already a sort of single-line tabular description of most the commands.
[...]
Of course you need a short description in the table and then you talk about the details as text paragraph. A sample of what I mean is this document:
You can write it using Open Office Write and then export it as a PDF and maybe as HTML too. Using OOW (or Word) can help to add links in the document, so that you can click on the command name in the table and go directly to the paragraph with details.
Having a modern aspect on the documentation would give CECP ten points over UCI
one thing i'd like to see is stronger language on features. specifically the ones an engine (theoretically) has to worry about being rejected. it would be good to either mark each of them as features that 'should' be supported by any gui implementing the protocol in order to be considered compliant or 'deprecated' and not recommended to be requested by an engine at all anymore (even though some guis may continue to support them). One of my biggest problems with the old document was not that it was long but rather that it liked wishy washy language that in theory made you have to have fallback implementations for everything that could clean it up.
This is not so important for features that a rejected can just be ignored (i.e. if exclude=1 gets rejected well then you're just not going to get those commands - good feature!).
I realise you did make these sorts of comments down in the example code section, but it would be good to have it consolidated in a more obvious spot. It's very important to be crystal clear about what should be able to be depended on.
