X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=engine-intf.html;h=b8b09fb01f59fdcef7ad43e960080d68489f8b6d;hb=9d4c9573bfe66d04681f0bc4553ec379e7ac1fc4;hp=058f14755665abffa4c473dd43720876e274f409;hpb=0d88a109c226fc27d24f0e28cd3f4c7da1b59367;p=xboard.git

diff --git a/engine-intf.html b/engine-intf.html
index 058f147..b8b09fb 100644
--- 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.
 The "put" command similarly indicates where the user releases that piece;
 as the GUI clears the highlights on that event by itself, usually no engine response would be required.
+For promotion moves you can get a double "put" command, the first one sent when the piece lands on the square,
+without being decided yet what it promotes to, so the engine can send a "choice" command to
+specify the promotion choice the GUI should offer when promotion wasn't already implied by the "lift" location.
 The "hover" command is sent whenever the mouse pointer enters a square that is currently marked in red,
 (reserved for captures)
 so that the engine can (optionally) reply with a "highlight" command to mark victims of non-standard capture
@@ -1850,8 +1853,9 @@ Some colors have special meaning to the GUI:
 <table>
 <tr><th>color</th><th>used for</th><th>effect</th><tr>
 <tr><td>red</td><td>capture</td><td>hovering over the square makes the GUI send a "hover" command</td><tr>
-<tr><td>magenta</td><td>promotion</td><td>moving to the square will be treated by the GUI as a promotion</td><tr>
-<tr><td>cyan</td><td>multi-move</td><td>moving to the square will not complete the move entry</td><tr>
+<tr><td>magenta</td><td>promotion choice</td><td>moving to the square will be treated by the GUI as a promotion</td><tr>
+<tr><td>blue</td><td>forced promotion</td><td>moving to the square will automatically promote the piece as specified in a 'choice' command</td><tr>
+<tr><td>cyan</td><td>multi-leg moving</td><td>moving to the square will not complete the move entry</td><tr>
 <tr><td>green</td><td>victims</td><td>no real effect, but used by convention to indicate capture victims on "hover"</td><tr>
 </table>
 The GUI will use the markers for legality checking,
@@ -1865,6 +1869,21 @@ 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.
 </dd>
 
+<dt class="version48">choice PIECESTRING</dt>
+<dd class="version48">
+This command can be sent to the GUI in response to a 'lift' or 'put' command that implies a promotion move,
+to alter the choice offered to the user for the promotion piece from what the GUI would naturally assume,
+to the piece IDs mentioned in the PIECESTRING.
+The IDs in that string should be given as capitals irrespective of color.
+The first piece mentioned will be the default choice.
+An engine <i>must</i> send this command on receiving a 'put' on a square that it highlighted in blue,
+or the move will not be completed;
+the GUI must wait for the 'choice' command in this case,
+to complete the move with the specified promotion suffix,
+which will then always be the first piece mentioned in the PIECESTRING.
+</dd>
+</dl>
+
 <dt class="version48">click SQUARE</dt>
 <dd class="version48">
 The GUI will treat this command as if the user had clicked the mentioned SQUARE.