fixed some characters in xboard.texi
[xboard.git] / xboard.texi
index 0e0c270..f31500e 100644 (file)
@@ -1,4 +1,10 @@
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
 @setfilename xboard.info
+@settitle XBoard
+@c %**end of header
+
+@include version.texi
 
 @ifinfo
 @format
@@ -326,6 +332,10 @@ bring up the white and black piece menus.
 clock to tell XBoard which side moves first.
 
 4. Select Analysis Mode from the Mode Menu to start the analysis.
+
+The analysis function can also be used when observing games on an ICS
+with an engine loaded (zippy mode); the engine then will analyse
+the positions as they occur in the observed game.
 @item Analyze File
 @cindex Analyze File, Menu Item
 This option lets you load a game from a file (PGN, XBoard format, etc.)
@@ -545,7 +555,8 @@ unexamine command. ICS mode only.
 @cindex Backward, Menu Item
 @cindex <, Button
 Steps backward through a series of remembered moves.
-The @samp{[<]} button and the @kbd{b} key are equivalents.
+The @samp{[<]} button and the @kbd{b} key are equivalents,
+as is turning the mouse wheel towards you.
 In addition, pressing the Control key steps back one move, and releasing
 it steps forward again.
 
@@ -567,7 +578,8 @@ view.
 @cindex >, Button
 Steps forward through a series of remembered moves (undoing the
 effect of @samp{Backward}) or forward through a game file. The
-@samp{[>]} button and the @kbd{f} key are equivalents.
+@samp{[>]} button and the @kbd{f} key are equivalents,
+as is turning the mouse wheel away from you.
 
 If you are examining an ICS game, the behavior of Forward
 depends on whether XBoard is in Pause mode. If Pause mode is
@@ -628,6 +640,16 @@ after the chess engine has replied to your move; if the chess engine is still
 thinking, use @samp{Move Now} first. In ICS mode, @samp{Retract Move}
 issues the command @samp{takeback 1} or @samp{takeback 2}
 depending on whether it is your opponent's move or yours.
+@item Adjudicate to White
+@itemx Adjudicate to Black
+@itemx Adjudicate Draw
+@cindex Adjudicate to White, Menu Item
+@cindex Adjudicate to Black, Menu Item
+@cindex Adjudicate Draw, Menu Item
+Terminate an ongoing game in Two-Machines mode (including match mode),
+with as result a win for white, for black, or a draw, repsectively.
+The PGN file of the game will accompany the result string
+by the comment "user adjudication".
 @end table
 
 @node Options Menu
@@ -662,7 +684,6 @@ For the latter adjudication to work, XBoard should be able to properly understan
 the engine's scores. To faclitate the latter, you can inform xboard here if
 the engines report scores from the viewpoint of white, or from that of their own color.
 @item Engine Settings
-@citem Engine Settings, Menu Item
 Pops up a sub-menu where you can set some engine parameters common to most engines,
 such as hash-table size, tablebase cache size, maximum number of processors
 that SMP engines can use, and where to find the Polyglot adapter needed
@@ -950,7 +971,7 @@ instructions on how to report this problem.
 
 You can add or remove shortcut keys using the X resources
 @code{form.translations}. Here is an example of what would go in your
-@file{.Xdefaults} file:
+@file{.Xresources} file:
 
 @example
 XBoard*form.translations: \
@@ -996,7 +1017,7 @@ ToStartProc, TrainingProc, TruncateGameProc, and TwoMachinesProc.
 This section documents the command-line options to XBoard.  You can
 set these options in two ways: by typing them on the shell command
 line you use to start XBoard, or by setting them as X resources
-(typically in your @file{.Xdefaults} file).  Many of the options
+(typically in your @file{.Xresources} file).  Many of the options
 cannot be changed while XBoard is running; others set the initial
 state of items that can be changed with the @ref{Options} menu.
 
@@ -1010,7 +1031,7 @@ numbers as values, you can use the long or short option names
 interchangeably.
 
 Each option corresponds to an X resource with the same name, so
-if you like, you can set options in your @file{.Xdefaults} file
+if you like, you can set options in your @file{.Xresources} file
 or in a file named @file{XBoard} in your home directory.
 For options that have two names, the longer one is the name of
 the corresponding X resource; the short name is not recognized.
@@ -1020,11 +1041,11 @@ true or false (@samp{XBoard*longOptionName: true}).
 
 @menu
 * Chess engine options::        Controlling the chess engine.
-* WB + UCI Engine Settings::    Setting some very common engine parameters
+* UCI + WB Engine Settings::    Setting some very common engine parameters
 * ICS options::                 Connecting to and using ICS.
 * Load and Save options::       Input/output options.
 * User interface options::      Look and feel options.
-* Adjudication options::        Control adjudcation of engine-engine games.
+* Adjudication Options::        Control adjudcation of engine-engine games.
 * Other options::               Miscellaneous.
 @end menu
 
@@ -1127,7 +1148,6 @@ it makes the engine send it despite the setting of this option.)
 @cindex ponderNextMove, option
 Sets the Ponder Next Move menu option. @xref{Options Menu}. Default: true.
 @item -smpCores number
-@citem smpCores, option
 Specifies the maxmum nmber of CPUs an SMP engine is allowed to use.
 Only works for engines that support the WinBoard-protocol cores feature.
 @item -mg or -matchGames n
@@ -1150,7 +1170,7 @@ displays the match score and exits. Default: 0 (do not run a match).
 Setting @code{matchMode} to true is equivalent to setting
 @code{matchGames} to 1.
 @item -sameColorGames n
-@cinex sameColorGames, option
+@cindex sameColorGames, option
 Automatically runs an n-game match between two chess engines,
 without alternating colors.
 Otherwise the same applies as for the @samp{-matchGames} option,
@@ -1214,7 +1234,7 @@ Setting this option from the command line is tricky, because you must
 type in real newline characters, including one at the very end.
 In most shells you can do this by
 entering a @samp{\} character followed by a newline. It is easier to set
-the option from your @file{.Xdefaults} file; in that case you can
+the option from your @file{.Xresources} file; in that case you can
 include the character sequence @samp{\n} in the string, and it will
 be converted to a newline.
 
@@ -1269,11 +1289,41 @@ version-number are not supported.
 If this option is set, the score reported by the engine is taken to be 
 that in favor of white, even when the engine plays black. 
 Important when XBoard uses the score for adjudications, or in PGN reporting. 
+@item -niceEngines priority
+@cindex niceEngines, option
+This option allows you to lower the priority of the engine processes, 
+so that the generally insatiable hunger for CPU time of chess engines does not interfere so much 
+with smooth operation of WinBoard (or the rest of your system). 
+Negative values could increase the engine priority, which is not recommended.
+@item -firstOptions string
+@itemx -secondOptions string
+@cindex firstOptions, option
+@cindex secondOptions, option
+The given string is a comma-separated list of (option name=option value) pairs, 
+like the following example: "style=Karpov,blunder rate=0". 
+If the options announced by the engine at startup through the feature commands of WinBoard protocol 
+matches one of the option names (i.e. "style" or "blunder rate"), 
+it would be set to the given value (i.e. "Karpov" or 0) 
+through a corresponding option command to the engine. 
+This provided that the type of the value (text or numeric) matches as well.
+@item -firstNeedsNoncompliantFEN string
+@itemx -secondNeedsNoncompliantFEN string
+@cindex firstNeedsNoncompliantFEN, option
+@cindex secondNeedsNoncompliantFEN, option
+The castling rights and e.p. fields of the FEN sent to the mentioned engine 
+with the setboard command will be replaced by the given string. This can for 
+instance be used to run engines that do not understand Chess960 FENs in 
+variant fischerandom, to make them at least understand the opening position, 
+through setting the string to "KQkq -". (Note you also have to give the e.p. field!) 
+Other possible applications are to provide work-arounds for engines that want to see 
+castling and e.p. fields in variants that do not have castling or e.p. 
+(shatranj, courier, xiangqi, shogi) so that WinBoard would normally omit them 
+(string = "- -"), or to add variant-specific fields that are not yet supported by WinBoard 
+(e.g. to indicate the number of checks in 3check).
 @end table
 
-
-
 @node UCI + WB Engine Settings
+@section UCI + WB Engine Settings
 @cindex Engine Settings
 @cindex Settings, Engine
 @table @asis
@@ -1303,12 +1353,14 @@ and the option @code{firstHasOwnBookUCI} or @code{secondHasOwnBookUCI} applying
 is set to false.
 The engine will be kept in force mode as long as the current position is in book, 
 and XBoard will select the book moves for it. Default "".
-@item -fNoOwnBookUCI or -firstHasOwnBookUCI true/false
-@itemx -sNoOwnBookUCI or -secondHasOwnBookUCI true/false
+@item -fNoOwnBookUCI or -firstXBook or -firstHasOwnBookUCI true/false
+@itemx -sNoOwnBookUCI or -secondXBook or -secondHasOwnBookUCI true/false
 @cindex fNoOwnBookUCI, option
 @cindex sNoOwnBookUCI, option
 @cindex firstHasOwnBookUCI, option
 @cindex secondHasOwnBookUCI, option
+@cindex firstXBook, option
+@cindex secondXBook, option
 Indicates if the mentioned engine has its own opening book it should play from,
 rather than using the external book through XBoard. Default: false.
 @item -defaultHashSize n
@@ -1339,7 +1391,7 @@ Default: "".
 @end table
 
 @node ICS options
-@section Internet Chess Server Options
+@section ICS options
 @cindex ICS options
 @cindex Options, ICS
 @table @asis
@@ -1489,11 +1541,13 @@ Sets the Auto Flag menu option.  @xref{Options Menu}. Default: false.
 @cindex autoObserve, option
 Sets the Auto Observe menu option.  @xref{Options Menu}. Default: false.
 @item -autoKibitz
-@cindex autoKibitz, option`
+@cindex autoKibitz, option
 Enables kibitzing of the engines last thinking output (depth, score, time, speed, PV) 
 before it moved
 to the ICS, in zippy mode. The option @code{showThinking} must be switched on for 
 this option to work.
+Also diverts similar kibitz information of an opponent engine that is playing you 
+through the ICS to the engine-output window, as if the engine was playing locally.
 @item -moves/-xmoves or -getMoveList true/false
 @cindex moves, option
 @cindex getMoveList, option
@@ -1504,8 +1558,12 @@ Sets the Get Move List menu option.  @xref{Options Menu}.  Default: true.
 Sets the ICS Alarm menu option.  @xref{Options Menu}. Default: true.
 @item -icsAlarmTime ms
 @cindex icsAlarmTime, option
-Sets the time in milliseconds for the ICS Alarm menu option. 
+Sets the time in milliseconds for the ICS Alarm menu option.
 @xref{Options Menu}. Default: 5000.
+@item lowTimeWarning true/false
+@cindex lowTimeWarning, option
+Controls a color change of the board as a warning your time is running out.
+@xref{Options Menu}. Default: false.
 @item -pre/-xpre \fRor\fB -premove true/false
 @cindex pre, option
 @cindex premove, option
@@ -1554,7 +1612,7 @@ Here ``default'' means the default foreground or background color of
 your xterm.  Bold can be 1 or 0.  If background is omitted, ``default''
 is assumed; if bold is omitted, 0 is assumed.
 
-Here is an example of how to set the colors in your @file{.Xdefaults} file.
+Here is an example of how to set the colors in your @file{.Xresources} file.
 The colors shown here are the default values; you will get
 them if you turn @code{-colorize} on without specifying your own colors.
 
@@ -1621,7 +1679,7 @@ This sound is played when an ICS game that you are participating in is
 aborted, adjourned, or otherwise ends inconclusively.  Default: "" (no
 sound).
 
-Here is an example of how to set the sounds in your .Xdefaults file:
+Here is an example of how to set the sounds in your @file{.Xresources} file:
 
 @example
 xboard*soundShout: shout.wav
@@ -1643,7 +1701,7 @@ xboard*soundIcsAlarm: alarm.wav
 @end table
 
 @node Load and Save options
-@section Load and Save Options
+@section Load and Save options
 @cindex Options, Load and Save
 @cindex Load and Save options
 @table @asis
@@ -1673,7 +1731,6 @@ in the file is used twice (with reversed colors).
 The @code{rewindIndex} option causes the index to be reset to the
 first game of the file when it has reached a specified value.
 @item -rewindIndex n
-@citem rewindIndex, option
 Causes a position file or game file to be rewound to its beginning after n
 positions or games in auto-increment @code{matchMode}. 
 See @code{loadPositionIndex} and @code{loadGameIndex}.
@@ -1732,14 +1789,22 @@ Sets the name used in the PGN event tag to string.
 Default: "Computer Chess Game".
 @item -saveOutOfBookInfo true/false
 @cindex saveOutOfBookInfo, option`
-Include the information on how the engine(s) game out of its opening book in a special \91annotator\92 tag with the PGN file.@item -oldsave/-xoldsave or -oldSaveStyle true/false
+Include the information on how the engine(s) game out of its opening book in a special 'annotator' tag with the PGN file.
+@item -oldsave/-xoldsave or -oldSaveStyle true/false
 @cindex oldsave, option
 @cindex oldSaveStyle, option
 Sets the Old Save Style menu option.  @xref{Options Menu}.  Default: false.
+@item -gameListTags string
+@cindex gameListTags, option
+The character string lists the PGN tags that should be printed in the
+Game List, and their order. The meaning of the codes is e=event,
+s=site, d=date, o=round, p=players, r=result, w=white Elo, b=black Elo,
+t=time control, v=variant, a=out-of-book info.
+Default: "eprd"
 @end table
 
 @node User interface options
-@section User Interface Options
+@section User interface options
 @cindex User interface options
 @cindex Options, User interface
 @table @asis
@@ -1750,6 +1815,12 @@ Sets the Old Save Style menu option.  @xref{Options Menu}.  Default: false.
 @cindex geometry, option
 @cindex iconic, option
 These and most other standard Xt options are accepted.
+@item -noGUI
+@cindex noGUI, option
+Suppresses all GUI functions of XBoard 
+(to speed up automated ultra-fast engine-engine games, which you don\92t want to watch). 
+There will be no board or clock updates, no printing of moves, 
+and no update of the icon on the task bar in this mode.
 @item -movesound/-xmovesound or -ringBellAfterMoves true/false
 @cindex movesound, option
 @cindex bell, option
@@ -1970,12 +2041,14 @@ sets, see @ref{zic2xpm} below.
 @itemx -lightSquareColor color
 @itemx -darkSquareColor color
 @itemx -highlightSquareColor color
+@itemx -lowTimeWarningColor color
 @cindex Colors
 @cindex whitePieceColor, option
 @cindex blackPieceColor, option
 @cindex lightSquareColor, option
 @cindex darkSquareColor, option
 @cindex highlightSquareColor, option
+@cindex lowTimeWarningColor, option
 Colors to use for the pieces, squares, and square highlights.
 Defaults:
 
@@ -1986,6 +2059,7 @@ Defaults:
 -darkSquareColor       #77A26D
 -highlightSquareColor  #FFFF00
 -premoveHighlightColor #FF0000
+-lowTimeWarningColor   #FF0000
 @end example
 
 On a grayscale monitor you might prefer:
@@ -1997,6 +2071,7 @@ On a grayscale monitor you might prefer:
 -darkSquareColor       gray60
 -highlightSquareColor  gray100
 -premoveHighlightColor gray70
+-lowTimeWarningColor   gray70
 @end example
 @item -drag/-xdrag or -animateDragging true/false
 @cindex drag, option
@@ -2068,7 +2143,7 @@ as repeats, XBoard is fully e.p. and castling aware!
 @end table
 
 @node Other options
-@section Other Options
+@section Other options
 @cindex Options, miscellaneous
 @table @asis
 @item -ncp/-xncp or -noChessProgram true/false
@@ -2188,6 +2263,23 @@ Default: ""
 @cindex debug, option
 @cindex debugMode, option
 Turns on debugging printout.
+@item -debugFile filename or -nameOfDebugFile filename
+@cindex debugFile, option
+@cindex nameOfDebugFile, option
+Sets the name of the file to which WinBoard saves debug information 
+(including all communication to and from the engines).
+@item -engineDebugOutput number
+@cindex engineDebugOutput, option
+Specifies how WinBoard should handle unsolicited output from the engine, 
+with respect to saving it in the debug file. 
+The output is further (hopefully) ignored. 
+If number=0, WinBoard refrains from writing such spurious output to the debug file. 
+If number=1, all engine output is written faithfully to the debug file. 
+If number=2, any protocol-violating line is prefixed with a \91#\92 character, 
+as the engine itself should have done if it wanted to submit info for inclusion in the debug file.
+This option is provided for the benefit of applications that use the debug file 
+as a source of information, such as the broadcaster of live games TLCV / TLCS. 
+Such applications can be protected from spurious engine output that might otherwise confuse them.
 @item -rsh or -remoteShell shell-name
 @cindex rsh, option
 @cindex remoteShell, option
@@ -2203,6 +2295,12 @@ User name on the remote system when running programs with the
 @cindex userName, option
 Name under which the Human player will be listed in the PGN file. 
 Default is the login name on your local computer.
+@item -delayBeforeQuit number
+@itemx -delayAfterQuit number
+@cindex delayBeforeQuit, option
+@cindex delayAfterQuit, option
+These options specify how long WinBoard has to wait before sending a termination signal to rogue engine processes, that do not want to react to the \91quit\92 command. The second one determines the pause after killing the engine, to make sure it dies.
+
 @end table
 
 @node Chess Servers
@@ -2338,7 +2436,7 @@ command-line options as follows:
 xboard -ics -icshost firewall.example.com -icsport 23
 @end example
 @noindent
-Or in your @file{.Xdefaults} file:
+Or in your @file{.Xresources} file:
 
 @example
 XBoard*internetChessServerHost: firewall.example.com
@@ -2376,7 +2474,7 @@ xboard -ics -gateway rsh.example.com -icshost chessclub.com
 @end example
 
 @noindent
-Or in your @file{.Xdefaults} file:
+Or in your @file{.Xresources} file:
 
 @example
 XBoard*gateway: rsh.example.com
@@ -2399,7 +2497,7 @@ xboard -ics -telnet -telnetProgram ptelnet
 @end example
 
 @noindent
-Or in your @file{.Xdefaults} file:
+Or in your @file{.Xresources} file:
 
 @example
 XBoard*useTelnet: true
@@ -2415,7 +2513,7 @@ that is, your @file{ptelnet} program doesn't let you connect to
 alternative ports. As noted above, your chess server may allow you to
 connect on port 23 instead.  In that case, just add the option
 @samp{-icsport ""} to the above command, or add
-@samp{XBoard*internetChessServerPort:} to your @file{.Xdefaults} file.
+@samp{XBoard*internetChessServerPort:} to your @file{.Xresources} file.
 But if your chess server doesn't let you connect on port 23, you will have
 to find some other host outside the firewall and hop through it. For
 instance, suppose you have a shell account at @samp{foo.edu}. Set
@@ -2426,7 +2524,7 @@ xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport ""
 @end example
 
 @noindent
-Or in your @file{.Xdefaults} file:
+Or in your @file{.Xresources} file:
 
 @example
 XBoard*useTelnet: true
@@ -2618,6 +2716,10 @@ Most of the options that initially wre WinBoard only have now been back-ported t
 
 Michel van den Bergh provided the code for reading Polyglot opening books.
 
+Arun Persaud worked with H.G. Muller to combine all the features of the never-released WinBoard 4.2.8 
+of the Savannah project (mainly by Daniel Mehrmann), 
+and the never-released 4.3.16 into a unified WinBoard 4.4, 
+which is now available both from the Savannah web site and the WinBoard forum.
 @node CMail
 @chapter CMail
 @cindex cmail
@@ -2822,6 +2924,8 @@ Here are some other programs you can use with XBoard
 
 @menu
 * GNU Chess::        The GNU Chess engine.
+* Fairy-Max::        The Fairy-Max chess engine.
+* HoiChess::         The HoiChess chess engine.
 * Crafty::           The Crafty chess engine.
 * zic2xpm::          The program used to import chess sets from ZIICS.
 @end menu
@@ -2912,7 +3016,7 @@ zic2xpm ~/ziics/fritz4.*
 xboard -pixmap ~/fritz4
 @end example
 
-Alternatively, you can add this line to your .Xdefaults file:
+Alternatively, you can add this line to your @file{.Xresources} file:
 
 @example
 xboard*pixmapDirectory: ~/fritz4
@@ -2942,3 +3046,5 @@ the original creator(s) of the pieces.
 @printindex cp
 @contents
 @c end noman
+
+@bye