Describe choice command in protocol specs

diff --git a/engine-intf.html b/engine-intf.html
index 058f147..bc4815f 100644 (file)
--- a/engine-intf.html
+++ b/engine-intf.html
@@ -1139,6 +1139,9 @@ The "lift" command is sent by the GUI when the user 'picks up' (or selects) a pi
 so that the engine can reply with a "highlight" command to mark the squares where that piece can move to.\r
 The "put" command similarly indicates where the user releases that piece;\r
 as the GUI clears the highlights on that event by itself, usually no engine response would be required.\r
+For promotion moves you can get a double "put" command, the first one sent when the piece lands on the square,\r
+without being decided yet what it promotes to, so the engine can send a "choice" command to\r
+specify the promotion choice the GUI should offer when promotion wasn't already implied by the "lift" location.\r
 The "hover" command is sent whenever the mouse pointer enters a square that is currently marked in red,\r
 (reserved for captures)\r
 so that the engine can (optionally) reply with a "highlight" command to mark victims of non-standard capture\r
@@ -1865,6 +1868,16 @@ the corresponding lower-case character can be used for the color.
 For indicating a legal destination square without visibly marking it, T (transparent) can be used.\r
 </dd>\r
 \r
+<dt class="version48">choice PIECESTRING</dt>\r
+<dd class="version48">\r
+This command can be sent to the GUI in response to a 'lift' or 'put' command that implies a promotion move,\r
+to alter the choice offered to the user for the promotion piece from what the GUI would naturally assume,\r
+to the piece IDs mentioned in the PIECESTRING.\r
+The IDs in that string should be given as capitals irrespective of color.\r
+The first piece mentioned will be the default choice.\r
+</dd>\r
+</dl>\r
+\r
 <dt class="version48">click SQUARE</dt>\r
 <dd class="version48">\r
 The GUI will treat this command as if the user had clicked the mentioned SQUARE.\r