Suggestions for XBoard documentation

[sje]

A go/search directive would always initiate a search based on the side-to-move of the current position, not on player color assignments. I suppose a swaproles directive could be added, although I don't see it getting much use.

Writing a a simple parser for a set directive is easy. It's also very general, and example source code could be provided.

Having a unified set syntax enforces the idea of "one basetype" = "one external representation". There's no danger of a need to use quoted strings in one area (like feature) and unquoted stings in another (like ics, name, result, etc.).

Counts are always unsigned integers, times are always decimal seconds, strings are always quoted, and symbols (like moves) are always unquoted identifiers selected from a fixed set. All easily generated, easily parsed, and also human readable.

Less directive kinds is simpler than more directive kinds.
Less directives sent is better than more directives sent.
Bundling semantically related values in a single, atomic directive is better than spreading them out over multiple directives.

[D Sceviour]

How does one set the default hash size in the winboard.ini file?

Code: Select all

/defaultHashSize=64

sends a hash size of 64 bytes, which makes no sense because the documentation states "This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes."

64K and 64M are rejected by Winboard with: "Bad integer value 64M". The user should not be required to guess the suffix size, or that MegaBytes should be implied. This might be another Crafty compatibility problem.

[hgm]

How does one set the default hash size in the winboard.ini file?

Code: Select all

/defaultHashSize=64

sends a hash size of 64 bytes, which makes no sense because the documentation states "This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes."

It sends memory 64, and according to the specs that means "use 64 MB".

64K and 64M are rejected by Winboard with: "Bad integer value 64M". The user should not be required to guess the suffix size, or that MegaBytes should be implied. This might be another Crafty compatibility problem.

The field in the menu dialog where you have to enter this is called "Hash Size (MB)" in WinBoard, and "Hash-Table Size (MB)" in XBoard. So I wouldn't say there is anything left to guess for the user. If you are so foolhardy as to edit the ini file, you should of course expect to be on your own.

[Ferdy]

How does one set the default hash size in the winboard.ini file?

Code: Select all

/defaultHashSize=64

sends a hash size of 64 bytes, which makes no sense because the documentation states "This command informs the engine on how much memory it is allowed to use maximally, in MegaBytes."

64K and 64M are rejected by Winboard with: "Bad integer value 64M". The user should not be required to guess the suffix size, or that MegaBytes should be implied. This might be another Crafty compatibility problem.

This /defaultHashSize=64, is only applicable for
1. uci engines
2. winboard engines that supports memory command

According to the manual, included in the winboard installation.

Code: Select all

specifies the size of the main hash table for UCI engines and WinBoard engines implementing the memory command

And in the help file, from the winboard gui.

Code: Select all

/defaultHashSize number
Sets the size of the hash table to number MegaBytes.

[hgm]

A go/search directive would always initiate a search based on the side-to-move of the current position, not on player color assignments. I suppose a swaproles directive could be added, although I don't see it getting much use.

Yes, I understand that. I called that command "play1move" to not confuse it with the already existing "go" command of CECP that assigns a color, and thus starts the search indirectly. But the implementation I showed above for the two cases was virtually the same. You also don't save on commands: in CECP you have to handle force and go, while in your proposal you would have to handle play1move and pondernextmove.

Writing a a simple parser for a set directive is easy. It's also very general, and example source code could be provided.

Well, as the example above showed, writing a parser for the existing CECP commands is even easier. So no gain there...

Less directive kinds is simpler than more directive kinds.
Less directives sent is better than more directives sent.
Bundling semantically related values in a single, atomic directive is better than spreading them out over multiple directives.

Well, you propose to send more directives: an explicit 'play1move' and an explicit 'pondernextmove' for every move in the game. So by your own standards that makes your proposal worse. That "less directive kinds is better" just seems an opinion. I don't share it. Basically it amounts to prefixing a lot of directives that are now different with the same keyword, and then laiming they are now the same. In that spirit we might as well prefix all the CECP commands with the word 'do', and claim we now have the ultimately simple protocol, with only a single command in it: 'do'. Having "ponder on" and "ponder off" instead of "hard" and "easy" is not a real simplification. Making it "set ponder on" and "set ponder off" neither. A difference that makes no difference is no difference...

The bundling might be an issue, but it is not obvious what 'semantically related' means. You seem to want to bundle things that IMO do not logically belong together, such as search depth and time-control settings (which are orthogonal parameters). Bundling stuff the user needs with stuff that he'd rather not touch at all IMO would be a bad thing.

[D Sceviour]

H.G. Muller wrote,

If you are so foolhardy as to edit the ini file, you should of course expect to be on your own.

Perhaps the question should have asked, "How does one read the default hash size in the winboard.ini file?" It seems that extra special code will have to written to interpret the memory command with xboard if the

feature memory=1

command is used, which will confuse and interfere with the ini file numbers as suggested by Graham Banks. For the novice, a note clarifying the user has to guess the syntax in the winboard.ini file would help considerably in the documentation. Eventually these things are sorted out, but the documentation is matter of making it easier.

[hgm]

Perhaps the question should have asked, "How does one read the default hash size in the winboard.ini file?"

The winboard.ini file is a private WinBoard file to save its settings from one run to the next, and is not really intended for human reading. If you are an expert hacker you might be able to achieve what you want there, but for normal users it is not recommended to touch it.

It seems that extra special code will have to written to interpret the memory command with xboard if the

feature memory=1

command is used, which will confuse and interfere with the ini file numbers as suggested by Graham Banks.

That is true, unless you consider the value in the ini file just as a default value that is used when no memory command is received. To be fully XBoard compliant the memory command should be implemented and prevail over the value in the engine ini file. If that is not to Graham's liking you have the choice of being either XBoard compatible or Graham compatible...

I am not sure what you mean by "extra special code". Of course for any command the engine has to recognize it needs code to recognize it, and code to implement the action it requests. In this case purging the old hash table, and allocating a new one (if the size changed).

For the novice, a note clarifying the user has to guess the syntax in the winboard.ini file would help considerably in the documentation. Eventually these things are sorted out, but the documentation is matter of making it easier.

Novices should not look in or mess with the winboard.ini file. For experts the contents of the file is explained concisely in WinBoard's help file (or XBoard's man file), in the section on command-line arguments. But that is a very long read, and it is very rare that you would need to do anything that requires touching the file that could not be done far better through the menu dialogs.

[D Sceviour]

It is not clear if the question has been answered. How does one set the default memory if the

feature memory=1

command is used? Assuming everything else is correct with Winboard and the engine, the engine ends up with 64 megabytes of memory. The only way to override this is for the engine to use an ini file.

[hgm]

Well, in my engine Simple (now renamed to King Slayer) I just allocate 1MB hash by default (to make it easier to run some quick tests from the command line). This is hard-coded, but I could coneivably have started by reading a simple.ini file, with some data in it that would be used for this startup allocation.

When it receives the memory N command it calls SetMemorySize(N), which then (if N is not accidentally equal to the already allocated amount) frees the current hash table, and allocates a new one of N megabytes.

As WinBoard would always send the memory command to an engine that specified feature memory=1 the whole exercise of startup allocation is pointless when running under WinBoard. But there could be interfaces that would reply rejected memory because they don't implement this feature of CECP, (or I could be running the engine from the command line), and then there would be no memory command at all, and you would be left running from the startup allocation.

Overriding what WinBoard says in the memory command would make the engine non-compliant. Don't do it!

[sje]

Semantically related means semantically related. Here, it means describing a single state variable which may be a structure. Two items bound to the same structure are more closely related than are two different structures.

Modal programming is what might have been taught forty years ago, but it's been out of date for at least three decades.

Having a unified view of state variable management allows for easy expansion while at the same time avoiding idiosyncrasies. Stuff like posting (two different directives), random (a toggle), pondering (two different directives), sd/st vs level (conflicting directives), and new mode variables required for additional functionality. Without a general unification, the ugly never goes away. Without a general unification, the newcomer coder has to slog through a document loaded with references to a long-gone chess engine.

A go/search action can be bundled on a usermove directive just by adding another field; there will already be field definitions for a draw offer and a draw claim, so adding a third field requesting a reply does not affect the general unification. With this, the total count of directives sent will be less than that of the current scheme.