CECP ('WB protocol') specs

[hgm]

The worst 'pain point' seems to be the setboard feature, because rejection of it implies a non-trivial alternative will be used. Like you say, features that just enable a command simply mean you won't get that command when rejected. That is still damaging for commands that repair an essential defect in the v1 protocol, however, such as "ping". I do already mention support for ping is mandatory for engines. Perhaps I should stress that it is also mandatory for GUIs.

And features that would disable certain commands (colors=0, times=0) IMO are totally pointless, as the effect is exactly the same as just ignoring the commands or replying to them with an error message. So I think the recommendation would have to be to not use the feature and not recognize the command (because that is easiest). Having a GUI react to "Error (unkown command): XXX" instead of "feature XXX=0" by switching off sending of XXX has been possible since v1 of the protocol, and doesn't seem very inferior. You could not gray out a corresponding menu item (like "Mode -> Analysis") in advance, but you could throw up a message "This engine does not support analysis" after the user tries to activate it. The latter is arguably even a better method, because it makes the user aware that the engine is the reason it doesn't work, while they would blame a grayed-out menu on the GUI.

Rejection of "feature usermove=1" also implies an alternative will be used. I have mixed feelings on "usermove=1"; it makes the recognition of moves much less ambiguous, but it is a terrible annoyance when you want to play the engine from the command line. So in my recent engines I usually recognize both, not to anticipate rejection, but just to save me typing "usermove " on the command line. Moves are not that hard to recognize, by their second character (as long as we keep limiting command keywords to lower-case alphabetic only). This would argue for never using usermove=1.

That leaves setboard vs edit. I can be more firm here, and mention that GUIs must support setboard to be considered compliant with v2 of the protocol.

What worries me as the large number of "almost useless" commands, (name, ics, rating, computer, otim, tellics/tellopponent/tellothers/tellall) which drive up the size of the document, and thus help creating the false impression that CECP is very complex.

[ZirconiumX]

What worries me as the large number of "almost useless" commands, (name, ics, rating, computer, otim, tellics/tellopponent/tellothers/tellall) which drive up the size of the document, and thus help creating the false impression that CECP is very complex.

For this, you could perhaps define a core set of commands (new, time, quit, setboard, etc - commands that MUST be implemented for the GUI and engine to communicate), with two supersets - extensions (cores, memory, egtpath, etc - things that SHOULD be implemented for user convenience and control) and legacy/deprecated (ics, telluser, computer, otim, white, black - things that MAY be implemented).

Just my two cents, though, and it could make things longer - although splitting the document into these sections may alleviate this in part.

Matthew:out

[hgm]

I already tried to do something like that by (apart from the initial-handshake section) having sections "basic commands" and "engine to GUI", for the core commands. Anything to do with variants I put in a separate section, as most people would not be interested in it. (Although it is of course the best part of the protocol! ) Most of the "almost useless" stuff went into the section "messages and social interaction" (well, I had to think up some friendly description...). The memory / cores / easy / hard stuff went all into a section "setting engine parameters".

I did now mark a lot of commands as 'advanced', as an encouragement to ignore them.

[ZirconiumX]

I already tried to do something like that by (apart from the initial-handshake section) having sections "basic commands" and "engine to GUI", for the core commands. Anything to do with variants I put in a separate section, as most people would not be interested in it. (Although it is of course the best part of the protocol! ) Most of the "almost useless" stuff went into the section "messages and social interaction" (well, I had to think up some friendly description...). The memory / cores / easy / hard stuff went all into a section "setting engine parameters".

I did now mark a lot of commands as 'advanced', as an encouragement to ignore them.

This still doesn't feel clear to me. The advanced sections are hidden within the text, meaning they don't catch the eye. I'll make a mockup of how I think the specs should be, since I don't process information well when reading it.

Matthew:out

[ZirconiumX]

I already tried to do something like that by (apart from the initial-handshake section) having sections "basic commands" and "engine to GUI", for the core commands. Anything to do with variants I put in a separate section, as most people would not be interested in it. (Although it is of course the best part of the protocol! ) Most of the "almost useless" stuff went into the section "messages and social interaction" (well, I had to think up some friendly description...). The memory / cores / easy / hard stuff went all into a section "setting engine parameters".

I did now mark a lot of commands as 'advanced', as an encouragement to ignore them.

This still doesn't feel clear to me. The advanced sections are hidden within the text, meaning they don't catch the eye. I'll make a mockup of how I think the specs should be, since I don't process information well when reading it.

Matthew:out

Here. It's perhaps not quite as colourful, but I find it easier to understand.

Matthew:out

[kbhearn]

sigint=0 is another significant pain in the land of theoretical rejection. A line making it clear that it's a must-support on the gui side would be good.

[hgm]

Good point.

[Harald]

The use of usermove should be mandatory for the gui in the xboard protocol v2
or at least the gui should alway send it. If an engine wants to allow simple move input
without 'usermove' then it can always do it leaving the xboard specification.
You could start the engine with a '-cmd' parameter or anything else but a first 'xboard' command.
In that case the engine can allow any cmd interface or a very xboard like interface with
some variations. But that would be outside the xboard protocol.

[Harald]

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

This kind of undefined behaviour is not suitable for an interface definition.
Just say in the specs: "The ping number N that the gui sends starts with 1
at the first ping and increments N by 1 with every other ping."

Then the engine can use an unsigned int to store the number N, initialize it with 0,
and detect errors easily.

[hgm]

The use of usermove should be mandatory for the gui in the xboard protocol v2
or at least the gui should alway send it. If an engine wants to allow simple move input
without 'usermove' then it can always do it leaving the xboard specification.
You could start the engine with a '-cmd' parameter or anything else but a first 'xboard' command.
In that case the engine can allow any cmd interface or a very xboard like interface with
some variations. But that would be outside the xboard protocol.

There is nothing against recognizing non-CECP commands in XBoard mode. My engines usually has several. 'p' for printing the board, 'l' for printing the piece list, 0-9 for setting up built-in test positions...

"usermove=1" has never been mandatory in protocol v2. It has not even been default. So what you propose is altering the protocol, and it would break many existing engines (including most of my own...) I think the most that can be required is that GUIs should support usermove=1, and never reject it to engines that request it.

I still don't see a good reason for recommending it for use in non-variant engines. I was actually considering recommending against it. What do you like about "usermove"?