updated polyglot protocol

I added a new option type "-reset" to the protocol for the new option feature.
4.4.0 does not implement it yet, but Michel wants it for future Polyglots,
and I think it is best to update the protocol in one big swoop. So I want to already
include it in the specs now. (engine-intf.html)

I made xboard's response to an unknown option type compliant with the new protocol specs.

diff --git a/backend.c b/backend.c
index fda1171..b0d9351 100644 (file)
--- a/backend.c
+++ b/backend.c
@@ -12549,7 +12549,11 @@ ParseFeatures(args, cps)
     if (BoolFeature(&p, "smp", &cps->maxCores, cps)) continue;
     if (StringFeature(&p, "egt", &cps->egtFormats, cps)) continue;
     if (StringFeature(&p, "option", &(cps->option[cps->nrOptions].name), cps)) {
-       ParseOption(&(cps->option[cps->nrOptions++]), cps); // [HGM] options: add option feature
+       if(!ParseOption(&(cps->option[cps->nrOptions++]), cps)) { // [HGM] options: add option feature
+           sprintf(buf, "rejected option %s\n", cps->option[--cps->nrOptions].name);
+           SendToProgram(buf, cps);
+           continue;
+       }
        if(cps->nrOptions >= MAX_OPTIONS) {
            cps->nrOptions--;
            sprintf(buf, "%s engine has too many options\n", cps->which);

diff --git a/engine-intf.html b/engine-intf.html
index bd6bcd7..8ff98ce 100644 (file)
--- a/engine-intf.html
+++ b/engine-intf.html
@@ -8,7 +8,7 @@
 <h1>Chess Engine Communication Protocol</h1>\r
 <h2><a href="http://www.tim-mann.org/">Tim Mann</a> &amp; <a href="http://home.hccnet.nl/h.g.muller/winboardF.html">H.G.Muller</a></h2>\r
 <p>\r
-Version 2; implemented in xboard/WinBoard 4.2.1 and later.<br>\r
+Version 2; implemented in xboard/WinBoard 4.2.1 and later. (Sept 3, 2009)<br>\r
 Changes since version 1 are indicated in <font color=red>red</font>.<br>\r
 Changes for WinBoard 4.3.xx are indicated in <font color=green>green</font>.<br>\r
 Changes for WinBoard 4.4.xx are indicated in <font color=blue>blue</font>.\r
@@ -1212,6 +1212,10 @@ protocol version by rejecting some features that are defined in that
 version; however, you should realize that engine authors are likely to\r
 code for xboard and may not be prepared to have a feature that they\r
 depend on be rejected.\r
+<font color=blue>If the GUI rejects an option feature because of the\r
+syntax of the value, it should print the value string with the\r
+"rejected" command, e.g. "rejected option nonsense" in response\r
+to receiving feature option="nonsense".</font>\r
 </p>\r
 \r
 <p>\r
@@ -1453,14 +1457,19 @@ and will not send any "egtpath" commands to inform the engine about their wherea
 </font>\r
 <dd><font color=blue>\r
 This feature is used by the engine to define an option command to appear in a GUI menu,\r
-so that the user can change the corresponding setting of the engine through the GUI.\r
+so that the user can change the corresponding setting of the engine through the GUI interactively.\r
 The string describes the option by defining a name, type, current value and (sometimes) the acceptable value range.\r
-There are nine different options types, each requiring a slighly different syntax of the defining string:\r
+Unlike other features, option features are accumulated by the GUI, \r
+and the GUI must be able to add a new option to the list at any time,\r
+even after having received feature done=1.\r
+There are ten different options types, each requiring a slighly different syntax of the defining string:\r
 <br>\r
 feature option="NAME -button"\r
 <br>\r
 feature option="NAME -save"\r
 <br>\r
+feature option="NAME -reset"\r
+<br>\r
 feature option="NAME -check VALUE"\r
 <br>\r
 feature option="NAME -string VALUE"\r
@@ -1483,13 +1492,20 @@ the minimum or maximum value of numeric (-spin) options,
 or arbitrary text labels (for -combo option).\r
 In the latter case, the current value will be preceded by an asterisk.\r
 The -file and -path options are similar to -string, but can be used to inform the GUI that\r
-the text represents a file name or folder name respectively, so the GUI dialog to set it\r
-could add the appropriate browse button to the text-edit field.\r
+the text represents a file name or folder name respectively, \r
+so the GUI dialog could add the appropriate browse button to the text-edit field.\r
 Similarly, a -slider option is like a -spin, but the GUI might make a different\r
 graphical representation for it.\r
 A -save option is like a -button, and defines an immediate command to be sent by the engine.\r
 With -save the GUI will make sure all current option settings are flushed to the engine\r
 before it sends this command.\r
+A -reset option is like a -button, but use of it purges the list of options before sending \r
+the corresponding option command to the engine.\r
+This enables the engine to completely redefine its options or their current settings,\r
+by sending a new set of option feature commands to the GUI, \r
+terminated by feature done=1.\r
+(The effect of sending an option feature for an option with the same name as was defined before, \r
+without first receiving a -reset option command, is undefined.)\r
 </font>\r
 \r
 <dt><font color=red>\r