Evert wrote: (well, you could - a list of Engine->GUI and GUI->Engine commands as an appendix is possible and would cover that; not sure it's really needed).
Yes, this sounds like a good idea. I can make two main columns, for engine->GUI and GUI->engine, and vertically keep the same distribution in sections (where possble putting the command and its reply in the same row).
There actually is a use for being able to tell when a particular feature was added, but it doesn't need to be colour-coded the way the old document was. A short appendix listing the major additions per XBoard version would be enough for that. The use-case is that you may want to check that certain features are available on a particular version of XBoard.
The old document was a strange mixture between protocol specs and description of XBoard behavior, and I tried to cleanse it as much as possible from the latter. It would not do any harm to devote an appendix table to XBoard. Or perhaps just an extra column in the command overview table to list the 'introduction version' of the command.
I did find the "recommended" value listed for features quite useful, as they help identify the newer features that the engine should try to support (say, ping). There is a measure of arbitraryness to this, of course, so we don't necessarily need it for all of them.
As far as I am concerned this really only applies to 'ping'. It cannot be stressed enough how important 'ping' is; without it the protocol sucks, and causes problems with moves from one game flowing over into the next. Whether people implement 'analyze', 'draw' or 'setboard' is really just a personal preference. Perhaps using san=1 deserves to be strongly recommended against. (What if a GUI rejects it?)
I guess I could point out the essential importace of 'ping' in the general text on the handshaking, where it is now only said the engine should print done=1.
In general, be very careful that you do not change the protocol by rephrasing things, because that will lead to incompatibilities and buggy behaviour. Commands should still have the same documented behaviour.
I agree of course about the genral principle. But on the patricular case of 'edit', if the descriptions are different, then what is actually the difference? If you expect the wording in terms of a 'mode' to allow an immediate Error response to 'edit' to prevent the remaining lines of the command to be sent, than this would definitely be the wrong description. Because despite the fact that this is the wording used in the original specs, there exists not a single GUI on the planet that would behave that way. The de-facto standard is that GUIs, and certainly all XBpard/WinBoard versions, just dump the command plus all the lines upto the period, before starting to process input again. Engines can respond immediately to 'edit' with an 'Error', but this reply will just sit in the pipe untill the GUI is done.
If there is a discrepancy between the de-facto standard and the specs, I think it is better to change the specs. It would be in no one's interest to retroactively declare all existing GUIs broken, and put unreasonable demands on future GUIs, just to rescue the exact meaning of the old description.
I guess there is a fundamental flaw here in the protocol, that can only be repaired here by an extra rule:a GUIs must not send 'edit' to an engine that has sent 'setboard=1' in combination with 'san=1', even when they reject 'setboard'. (Or, more drastically, require that any v2 GUI must support setboard. Which is probably more in line with what existing engines expect: no engine I know of that sends setboard=1 would be able to understand the edit command.) For v1 GUIs, which never get to see the features because they don't send 'protover', so they will also never send SAN. So we could add the remark that when running on a v1 GUI engines should never parse input lines as if they were SAN.