Suggestions for XBoard documentation

[hgm]

Force mode should not include color assignment nor rely upon an implied color assignment.

Not sure what you mean. "Force mode" does not include any color assignment. It is just one of the engine modes. In fact it is the mode that excludes color assignment...

Every time a program gets its color re-assigned, implicitly or explicitly, it also has to adjust various secondary items. These include PGN tags for White, Black, WhiteElo, BlackElo, and maybe some others.

That depends on how the program is written. For one, CECP engines are not supposed to be aware of PGN tags. As for the Elo it could store ownRating and oppoRating rather than whiteRating and blackRating. Doing the latter is just asking for trouble.

Further there may be the case where the program is playing both colors for some interpretations of analysis.

The protocol does not support that. It would have to be emulated by the GUI by sending a 'go' command after every move. Note that 'playing' means the program will eventually make moves as a result of the search process, and that you would not want this when analyzing games. In analyze mode it does think for both colors, but never makes a move for them. Instead it allows the GUI to feed it moves.

It seems like there is some kind of super-mode enumeration type which combines the various combinations of force, analysis, edit, and normal play. Maybe a few other things as well. I think that this can be cleaned up, but that and other improvements can't be made if there isn't a willingness to drop support for prior protocol version directives; at least when a program requests such.

Again I am not sure what you mean. There are no 'combinations' of force, analysis or normal play. You are always doing one or the other. One could view analysis mode as force mode with pondering on, but that would only be true if you always pondered on the opponent's position. And most programs ponder on a speculative opponnent move, while analysis should always use the current position. There are sub-states of PlayWhite and PlayBlack, namely Thinking and Pondering.

Perhaps you mean that Analyzing as searchState is superfluous, and could be combined with Idle to some Neither (Pondering nor Thinking) state. What commands should be processed during search is different in the 3 cases, however.

The edit command does define a new mode, but it should be considered deprecated. The replacement setboard is an atomic action.

There is a real opportunity here to greatly simplify the task of interfacing a program to XBoard.

I would not call turning the above pseudo-code into a real program even close to complex, so what is there to simplify? Note that you would probably only need half of what is written, because many commands are not given unless you explicitly enable them. Which you most likely would not, as many commands seem completely without interest, unless you are doing very advanced and specific things. Why would an engine be interested in the name of the opponent, the ICS, whether it plays a computer, the opponent time. And it might not implement NPS timing, SMP, EGTs, move exclusion...

A separate section of the documentation -- a rather short section -- could be made with a description of the state variables and the directive semantics. The number of directives could be drastically cut just by introducing a single set directive:

Code: Select all

set <StateVariableName> <new-value>

Perhaps, but what is the gain. Instead of distinguishing separate commands, the program would now have to distinguish separate state-variable names. "set mode force" is hardly an improvement over "force". The crux of the 'white'/'black' commands is that they are atomic: they allow you to change the side to move without triggering an engine search, by changing stm and side the engine played at the same time. And they are deprecated anyway; engines supporting setboard do not need them and would suppress them with colors=0, so they won't have to parse them either.

Further ideas:

1) Combine move, draw offers, and draw claims in a single, atomic response.

Yes, that would be nice.

2) Combine all opponent information into a single directive.

This seems to go in the opposite direction as using a universal 'set' command that would be used for any variable...

3) Avoid sending unneeded state variable updates.

That is an implementation issue. Unless you would declare it a protocol violation to send anything unneeded. Which might make life harder on the GUI designer for no good reason I can see.

4) When the interface wants a move from the program, indicate this with an explicit go directive (which also causes the program to play the move); use a separate search/hint directive when just an unplayed move is wanted. Thus, the need for force and analyze is dropped for a big gain in clarity -- just like setboard eliminates the need for edit and its sub-directives.

Well, that is the type of interface I usually preferred for my programs as well. Instead of a 'go' command I then use an empty line, for minimal typing effort. (E.g. the stand-alone version of micro-Max has that.) This way the engine does not need any notion of which side it is playing for.

But have you thought of the ramifications this has for pondering? If it is black's turn to move, what should the engine do? Already start a search from the current position, in the hope that it will receive a 'go' command? Or speculate on a move for black, hoping that it will receive a 'usermove' command next that provides a ponder hit? For pondering it makes a real difference which side the engine is playing. So you would now need a separate command goponder.

I don't see much advantage in redesigning the protocol in such a drastic way. We might as well design an entirely new protocol from scratch (and be sure no one ever would use it...). Having a variable mode that holds White/Black/None/Analyze and making a move when mode==stm rather than when command=="make1move" does not seem a very relevant change, complexity-wise.

5) Allow a program to query an ICS to retrieve opponent information and perhaps other ICS data (seek ads, resume games, etc.).

The program can already send queries with the tellics command, but it will not see the replies. This would of course be easy to implement: with a new feature chatter=1 the engine could instruct the GUI to forward all text it receives from the ICS to the engine as a new "chat" command. But you might as well connect the engine to the ICS directly in that case. Why would you still want to use an interface if you want to interact with the ICS that intimately?

6) Issue a new directive if and only if a new game is about to start.

I think zippy mode intentionally does the opposite to give an engine more time to initialize. Some engines need large startup time.

7) Replace sd, sd, nps, and level with a unified limit directive. Use decimal seconds for all time values, not a mixture of hours, minutes, and integer seconds.

The level command already specifies 3 parameters in a single command, and it could be made to take over the function of the st command by adopting the convention that negative increment values mean the increment is the corresponding absolute value, but limited to the time you actually used. In combination with a base time this would then specify a Bronstein TC, of which fixed maximum time per move is a special case. This would also be useful for specifying multi-session time controls (such as byoyomi) in an extended level command. But I don't really see what would be gained by always forcing the node rate and depth limit to be present in the same command that sets the times. Peoplemight not even want to implement playing by nodes.

8) Replace otim and time with a single setclock directive, and use decimal seconds instead of centiseconds.

How do you imagine that? Shouldn't there be a "setclock white T" and "setclock black T"? How is that simpler from time and otim? In the latter case you can process time and simply ignore otim, if you haven't any advanced time management that takes opponent time into account (as most engines won't).

9) Formalize analysis response formats; in particular use decimal seconds, decimal pawns, and symbolic scores for forced mate/loses.

The accuracy limit caused by the use of integer centiseconds is a concern, and indeed introducing a feature decimal=1 that would relay all timing info in seconds with an optional decimal fraction could be used to lift it. It hardly makes life easier for the engine programmer, however, who would have to also handle the case where the interface would reject the feature, so that you are still stuck with the old method. Symbolic mate scores also require extra work for the engine programmer, to convert his internal numeric scores to the symbolic ones.

10) Have all of the above activated by a program sending something like:

Code: Select all

feature version="2015.08.31"

in response to the xboard directive. This would inform XBoard to send only directives in force at the given date -- and no directives which were superseded at that date.

This seems to hopelessly complicate things for the engine programmer, who now is suddenly required to implement every directive in existence, rather than just being able to cherry-pick those that seem relevant to his engine. Currently the use of directives for 'advanced' tasks that the engine is not likely to support are off by default.

(And note that feature commands are send in response to "protover 2", not in response to "xboard".)

[D Sceviour]

H.G. Muller wrote,

That the 'force' command should not be followed by moves on the same line should be clear by the syntax description...

It is not clear to the beginner. All commands in the documentation should be dimensioned. There should be no guessing.

boolean force

It should indicate that force does not overload by acting as a string buffer like "feature" does. Part of the problem is the confusion created by the crafty command for force, which should also be clarified for those who are using crafty as an example for winboard protocol.

Another suggestion: Sort the commands alphabetically so they can be located quickly.

[hgm]

Well, NEVER use Crafty as an example for WinBoard protocol. That is not just asking for trouble, it is causing it!

None of the commands acts as a "string buffer", unless explicitly presented as such. The protocol specs always list the full commands. I don't think that adding phrases like "Note that this command is just a single word, as written above, and should not contain any text that is not written there behind it on the same line" to the description of each and every command would enhance the readability of the document... We could also add to every command that it is case sensitive and should not be spelled in capitals, that it should not be translated into French or Japanese, that spaces in it should not be omitted, that they cannot be spelled backwards, etc.

[D Sceviour]

H.G. Muller wrote,

Well, NEVER use Crafty as an example for WinBoard protocol. That is not just asking for trouble, it is causing it!

You can take that issue up with Bob Hyatt. However if I recall correctly, xboard was originally designed as an interface for crafty using crafty's protocol.

[hgm]

No, that is not true at all. XBoard was originally designed as an inteface for GNU Chess. Some really bad peculiarities of GNU Chess were ironed out quickly after that, but XBoard also continued to understand those, although by current standards GNU Chess is not a CECP-compliant program.

Crafty was designed with its own protocol, but can be switched to CECP through the "xboard" command.

[D Sceviour]

H.G. Muller wrote,

We could also add to every command that it is case sensitive...

The documentation already states, "All the commands are case-sensitive." The one command that is case sensitive is "setboard <FEN>". Other than that, winboard is user-friendly concerning case.

[hgm]

And it also already states

All commands from xboard to the engine end with a newline (\n), even where that is not explicitly stated.

from which follows that you should not write 'MOVE' commands on the same line as 'force'.

It is not that I want to claim the specs document is perfect, it is actually far from that. But I don't see ambiguity as to whether 'force' should be followed by a list of moves as a problem. No matter how hard I try, I just cannot find anything that even remotely suggests you should do that. It just says the engine should be set to play neither color.

IMO the main problem with the specs is that it is already way too long. The pseudo-code given above seems much easier to understand.

As to alphabetic order, I am not sure. There also is a lot to be said for ordering them by importance. Especially for a beginner. Alphabetic is only useful if you already know the name of the command.

[Evert]

7) Replace sd, sd, nps, and level with a unified limit directive. Use decimal seconds for all time values, not a mixture of hours, minutes, and integer seconds.

8) Replace otim and time with a single setclock directive, and use decimal seconds instead of centiseconds.

All of my programs read the smallest time argument (whether in seconds or centi-seconds) as a floating point number, for potential sub-centisecond accuracy. I'm not sure how generally useful (or desirable) something like that would be to formalise though.

10) Have all of the above activated by a program sending something like:

Code: Select all

feature version="2015.08.31"

in response to the xboard directive. This would inform XBoard to send only directives in force at the given date -- and no directives which were superseded at that date.

Sounds like a convoluted version of what "protover" does... or am I missing something?

[sje]

The directive setclock is atomic, giving both colors time values simultaneously, the way it should be.

Code: Select all

setclock 123.45 6.789

Expressed in decimal seconds, this allows the program to choose its own internal representation and associated precision. An even better idea is to allow structures instead of just single values for the set directive:

Code: Select all

set clock white 123.45; black 6.789;
set opponent kind human; id "John Doe"; elo 2134;
set ics kind remote; id "chessclub.com";
set limit kind suddendeath; base 300.0; increment 1.0;

With all using an easily parsed format.

All that a set directives does is to set a value in the program's state structure. No implied calculations, no implied searches, etc. With searching done only after an explicit go/search directive, much is simplified. I suppose it's hard to see this if you've already done all the work to get a program connected. But for an author who has never built an interface to XBoard -- well, the current arrangement is not so simple.

Others:

Code: Select all

newgame white program; black opponent;
newposition fen "6Q1/8/3Q4/2K2p2/5P1p/8/4k3/8 b - - 0 79";

While some programs might not care about PGN tags or opponent information, other programs do use this data. Purposely not supplying tag values or the information needed to generate them unfairly hampers some programs at the expense of others. Also, some programs want to generate their own PGN game files using custom tags which aren't provided in XBoard's game file output.

Many of the other objections could be answered in the same way. It's sadly reminiscent of an expensive, largely failed primary education program set at the federal level in the US called "No Child Left Behind". In truth, this turned out to be more like "No Child Allowed to Get Ahead". I'm not saying that support for old, even ancient, programs should be dropped. I am saying that a newcomer author shouldn't be burdened with even reading about deprecated directives.

[hgm]

Basically you want a completely new protocol that in no way even remotely resembles CECP. I don't think there is any demand for that.

All that a set directives does is to set a value in the program's state structure. No implied calculations, no implied searches, etc. With searching done only after an explicit go/search directive, much is simplified. I suppose it's hard to see this if you've already done all the work to get a program connected. But for an author who has never built an interface to XBoard -- well, the current arrangement is not so simple.

Sorry, but I fail to see much difference in complexity between the following two pieces of code

Code: Select all

if(sideToMove == mode) {
  move = Think();
  sideToMove = MakeMove(move);
  printf("move MOVE\n");
}

command = ReadLine();

and

Code: Select all

command = ReadLine();

if(command == "play1move") {
  move = Think();
  sideToMove = MakeMove(move);
  printf("move MOVE\n");
}

Others:

Code: Select all

newgame white=program; black=opponent;
newposition fen="6Q1/8/3Q4/2K2p2/5P1p/8/4k3/8 b - - 0 79";

While some programs might not care about PGN tags or opponent information, other programs do use this data. Purposely not supplying tag values or the information needed to generate them unfairly hampers some programs at the expense of others. Also, some programs want to generate their own PGN game files using custom tags which aren't provided in XBoard's game file output.

Well, CECP does send you opponent name, ratings, variant, initial position, time control. So I wouldn't say it "purposely witholds" anything. You just seem to prefer getting it in another format. A format that just seems to complicates matters for everyone.

How would you handle the case where halfway the game the engine is set to continue for the other color? When it remembers the name of the opponnent that would remain usable without change, as the opponent would stay the same. He would just be playing the other color. So you would have to swap the tags if you keep them as whitePlayer and blackPlayer. And using a per-move go command does not really alterthat, you could also have the same player move for both sides.