X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=xboard.texi;fp=xboard.texi;h=0000000000000000000000000000000000000000;hb=b10966961672512a212cc61192d0b08cf91c4c0c;hp=9c4c125ba8dc8fdc18490f440b93655809aacf7b;hpb=e147dd97d26b46902200491dbe0a8755266555d3;p=xboard.git diff --git a/xboard.texi b/xboard.texi deleted file mode 100644 index 9c4c125..0000000 --- a/xboard.texi +++ /dev/null @@ -1,5038 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename xboard.info -@settitle XBoard -@c %**end of header - -@include version.texi - -@ifinfo -@format -INFO-DIR-SECTION Games -START-INFO-DIR-ENTRY -* xboard: (xboard). An X Window System graphical chessboard. -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@titlepage -@title XBoard - -@page -@vskip 0pt plus 1filll -@include copyright.texi - -@end titlepage -@ifset man -.TH xboard 6 "$Date: " "GNU" -.SH NAME -.PP -xboard @- X graphical user interface for chess -.SH SYNOPSIS -.PP -.B xboard [options] -.br -.B xboard -ics -icshost hostname [options] -.br -.B xboard -ncp [options] -.br -.B |pxboard -.br -.B cmail [options] -@end ifset - -@node Top -@top Introduction -@cindex introduction - -@ifset man -.SH DESCRIPTION -@end ifset - -XBoard is a graphical chessboard that can serve as a -user interface to chess engines (such as GNU Chess), the -Internet Chess Servers, -electronic mail correspondence chess, or your own collection of saved games. - -This manual documents version @value{VERSION} of XBoard. - -@menu -* Major modes:: The main things XBoard can do. -* Basic operation:: Mouse and keyboard functions. -* Menus:: Menus, buttons, and keys. -* Options:: Command options supported by XBoard. -* Chess Servers:: Using XBoard with an Internet Chess Server (ICS). -* Firewalls:: Connecting to a chess server through a firewall. -* Environment:: Environment variables. -* Limitations:: Known limitations and/or bugs. -* Problems:: How and where to report any problems you run into. -* Contributors:: People who have helped developing XBoard. -* CMail:: Using XBoard for electronic correspondence chess. -* Other programs:: Other programs you can use with XBoard. -@ifnottex -* Copyright:: Copyright notice for this manual. -@end ifnottex -* Copying:: The GNU General Public License. - -* Index:: Index of concepts and symbol names. -@end menu - -@node Major modes -@chapter Major modes -@cindex Major modes - -XBoard always runs in one of four major modes. You select the -major mode from the command line when you start up XBoard. - -@table @asis -@item xboard [options] -As an interface to GNU Chess or another chess engine running on your -machine, XBoard lets you play a game against the machine, -set up arbitrary positions, force variations, watch a game between two -chess engines, interactively analyze your stored games or set up and -analyze arbitrary positions. -To run engines that use the UCI standard XBoard will draw upon -the Polyglot adapter fully transparently, but you will need to have -the polyglot package installed for this to work. -@item xboard -ics -icshost hostname [options] -As Internet Chess Server (ICS) interface, XBoard -lets you play against other ICS users, observe games -they are playing, or review games that have recently finished. Most -of the ICS "wild" chess variants are supported, including bughouse. -@item xboard -ncp [options] -XBoard can also be used simply -as an electronic chessboard to play through games. It will read and -write game files and allow you to play through variations -manually. You can use it to browse games off the net or review games -you have saved. These features are also available in the other modes. -@item |pxboard -If you want to pipe games into XBoard, use the supplied shell -script @file{pxboard}. For example, from the news reader @file{xrn}, -find a message with one or more games in it, click the Save button, -and type @samp{|pxboard} as the file name. -@item cmail [options] -As an interface to electronic mail correspondence chess, XBoard -works with the cmail program. See @ref{CMail} below for -instructions. -@end table - -@node Basic operation -@chapter Basic operation -@cindex Basic operation - -To move a piece, you can drag it with the left mouse button, or you -can click the left mouse button once on the piece, then once more on -the destination square. To under-promote a Pawn you can drag it backwards -until it morphs into the piece you want to promote to, after which you -drag that forward to the promotion square. -Or after selecting the pawn with a first click you can then click -the promotion square and move the mouse while keeping the button down -until the piece that you want appears in the promotion square. -To castle you move the King to its destination or, in Chess960, -on top of the Rook you want to castle with. -In crazyhouse, bughouse or shogi you can -drag and drop pieces to the board from the holdings squares -displayed next to the board. - -Old behavior, where right-clicking a square brings up a menu -where you can select what piece to drop on it can still be -selected through the @samp{Drop Menu} option. -Only in Edit Position mode right and middle clicking a square is still used to -put a piece on it, and the piece to drop is selected by sweeping -the mouse vertically with the button held down. - -The default function of the right mouse button in other modes is -to display the position the chess program thinks it will end up in. -While moving the mouse vertically with this button pressed -XBoard will step through the principal variation to show how -this position will be reached. -Lines of play displayed in the engine-output window, -or PGN variations in the comment window can similarly -be played out on the board, by right-clicking on them. -Only in Analysis mode, when you walk along a PV, -releasing the mouse button might forward the game upto that point, -like you entered all previous PV moves. -As the display of the PV in that case starts after the first move -a simple right-click will play the move the engine indicates. - -In Analysis mode you can also make a move by grabbing the piece -with a double-click of the left mouse button -(or while keeping the @kbd{Ctrl} key pressed). -In this case the move you enter will not be played, -but will be excluded from the analysis of the current position. -(Or included if it was already excluded; it is a toggle.) -This only works for engines that support this feature. - -When connected to an ICS, it is possible to call up a graphical -representation of players seeking a game in stead of the chess board, -when the latter is not in use -(i.e. when you are not playing or observing). -Left-clicking the display area will switch between this 'seek graph' -and the chess board. -Hovering the mouse pointer over a dot will show the details of the -seek ad in the message field above the board. -Left-clicking the dot will challenge that player. -Right-clicking a dot will 'push it to the back', -to reveal any dots that were hidden behind it. -Right-clicking off dots will refresh the graph. - -Most other XBoard commands are available from the menu bar. The most -frequently used commands also have shortcut keys or on-screen buttons. -These shortcut keystrokes are mostly non-printable characters. -Typing a letter or digit while the board window has focus -will bring up a type-in box with the typed letter already in it. -You can use that to type a move in situations where it is your -turn to enter a move, -type a move number to call up the position after that move -in the display, -or, in Edit Position mode, type a FEN. -Some rarely used parameters can only be set through options on the -command line used to invoke XBoard. - -XBoard uses a settings file, in which it can remember any changes to -the settings that are made through menus or command-line options, -so they will still apply when you restart XBoard for another session. -The settings can be saved into this file automatically when XBoard exits, -or on explicit request of the user. -Note that the board window can be sized by the user, but that this -will not affect the size of the clocks above it, and won't be remembered -in the settings file. -To persistently change the size of the clocks, use the @code{size} -command-line option when starting XBoard. -The default name for the settings file is /etc/xboard/xboard.conf, -but in a standard install this file is only used as a master settings -file that determines the system-wide default settings, -and defers reading and writing of user settings to a user-specific -file like ~/.xboardrc in the user's home directory. - -When XBoard is iconized, its graphical icon is a white knight if -it is White's turn to move, a black knight if it is Black's turn. - -@node Menus -@chapter Menus, buttons, and keys -@cindex Menus - -@menu -* File Menu:: Accessing external games and positions. -* Edit Menu:: Altering games, positions, PGN tags or comments. -* View Menu:: Controlling XBoard's shape and looks. -* Mode Menu:: Selecting XBoard's mode. -* Action Menu:: Talking to the chess engine or ICS opponents. -* Engine Menu:: Controlling settings and actions of the engine(s). -* Options Menu:: User preferences. -* Help Menu:: Getting help. -* Keys:: Other shortcut keys. -@end menu - -@node File Menu -@section File Menu -@cindex File Menu -@cindex Menu, File -@table @asis -@item New Game -@cindex New Game, Menu Item -Resets XBoard and the chess engine to the beginning of a new chess -game. The @kbd{Ctrl-N} key is a keyboard equivalent. In Internet Chess -Server mode, clears the current state of XBoard, then -resynchronizes with the ICS by sending a refresh command. If you want to -stop playing, observing, or examining an ICS game, use an -appropriate command from the Action menu, not @samp{New Game}. -@xref{Action Menu}. -@item New Shuffle Game -@cindex New Shuffle Game, Menu Item -Similar to @samp{New Game}, but allows you to specify a particular initial position -(according to a standardized numbering system) -in chess variants which use randomized opening positions (e.g. Chess960). -@item shuffle -@cindex shuffle, Menu Item -Ticking @samp{shuffle} will cause the current variant to be played -with shuffled initial position. -Shuffling will preserve the possibility to castle in the way allowed by the variant. -@item Fischer castling -@cindex Fischer castling, menu item -Ticking @samp{Fischer castling} will allow castling with Kings and Rooks -that did not start in their normal place, as in Chess960. -@item Start-position number -@itemx randomize -@itemx pick fixed -@cindex randomize, Menu Item -@cindex pick fixed, Menu Item -@cindex Start-position number, Menu Item -The @samp{Start-position number} selects a particular start position -from all allowed shufflings, which will then be used for every new game. -Setting this to -1 (which can be done by pressing the @samp{randomize} button) -will cause a fresh random position to be picked for every new game. -Pressing the @samp{pick fixed} button causes @samp{Start-position number} -to be set to a random value, to be used for all subsequent games. -@item New Variant -@cindex New variant, Menu Item -Allows you to select a new chess variant in non-ICS mode. -(In ICS play, the ICS is responsible for deciding which variant will be played, -and XBoard adapts automatically.) The shifted @kbd{Alt+V} key is a -keyboard equivalent. If you play with an engine, the engine must -be able to play the selected variant, or the corresponding choice will be disabled. -XBoard supports all major variants, such as xiangqi, shogi, chess, chess960, -makruk, Capablanca Chess, shatranj, crazyhouse, bughouse. - -You can overrule the default board format of the selected variant, -(e.g. to play suicide chess on a 6 x 6 board), -in this dialog, but normally you would not do that, -and leave them at '-1', which means 'default' for the chosen variant. -@item Load Game -@cindex Load Game, Menu Item -Plays a game from a record file. The @kbd{Ctrl-O} key is a keyboard equivalent. -A pop-up dialog prompts you for the file name. If the file contains more -than one game, a second pop-up dialog -displays a list of games (with information drawn from their PGN tags, if -any), and you can select the one you want. Alternatively, you can load the -Nth game in the file directly, by typing the number @kbd{N} after the -file name, separated by a space. - -The game-file parser will accept PGN (portable game notation), -or in fact almost any file that contains moves in algebraic -notation. -Notation of the form @samp{P@@f7} -is accepted for piece-drops in bughouse games; -this is a nonstandard extension to PGN. -If the file includes a PGN position (FEN tag), or an old-style -XBoard position diagram bracketed by @samp{[--} and @samp{--]} -before the first move, the game starts from that position. Text -enclosed in parentheses, square brackets, or curly braces is assumed to -be commentary and is displayed in a pop-up window. Any other -text in the file is ignored. PGN variations (enclosed in -parentheses) also are treated as comments; -however, if you rights-click them in the comment window, -XBoard will shelve the current line, and load the the selected variation, -so you can step through it. -You can later revert to the previous line with the @samp{Revert} command. -This way you can walk quite complex varation trees with XBoard. -The nonstandard PGN tag [Variant "varname"] functions similarly to -the -variant command-line option (see below), allowing games in certain chess -variants to be loaded. -Note that it must appear before any FEN tag for XBoard to recognize -variant FENs appropriately. -There is also a heuristic to -recognize chess variants from the Event tag, by looking for the strings -that the Internet Chess Servers put there when saving variant ("wild") games. -@item Load Position -@cindex Load Position, Menu Item -Sets up a position from a position file. A pop-up dialog prompts -you for the file name. The shifted @kbd{Ctrl-O} key is a keyboard -equivalent. If the file contains more than one saved -position, and you want to load the Nth one, type the number N -after the file name, separated by a space. Position files must -be in FEN (Forsythe-Edwards notation), or in the format that the -Save Position command writes when oldSaveStyle is turned on. -@item Load Next Position -@cindex Load Next Position, Menu Item -Loads the next position from the last position file you loaded. -The shifted @kbd{PgDn} key is a keyboard equivalent. -@item Load Previous Position -@cindex Load Previous Position, Menu Item -Loads the previous position from the last position file you -loaded. The shifted @kbd{PgUp} key is a keyboard equivalent. -Not available if the last position was loaded from a pipe. -@item Save Game -@cindex Save Game, Menu Item -Appends a record of the current game to a file. -The @kbd{Ctrl-S} key is a keyboard equivalent. -A pop-up dialog -prompts you for the file name. If the game did not begin with -the standard starting position, the game file includes the -starting position used. Games are saved in the PGN (portable -game notation) format, unless the oldSaveStyle option is true, -in which case they are saved in an older format that is specific -to XBoard. Both formats are human-readable, and both can be -read back by the @samp{Load Game} command. -Notation of the form @samp{P@@f7} -is accepted for piece-drops in bughouse games; -this is a nonstandard extension to PGN. -@item Save Position -@cindex Save Position, Menu Item -Appends a diagram of the current position to a file. -The shifted @kbd{Ctrl+S} key is a keyboard equivalent. -A pop-up dialog prompts you for the file name. Positions are saved in -FEN (Forsythe-Edwards notation) format unless the @code{oldSaveStyle} -option is true, in which case they are saved in an older, -human-readable format that is specific to XBoard. Both formats -can be read back by the @samp{Load Position} command. -@item Save Selected Games -@cindex Save Selected Games -Will cause all games selected for display in the current Game List -to be appended to a file of the user's choice. -@item Save Games as Book -@cindex Save Games as Book, Menu Item -Creates an opening book from the currently loaded game file, -incorporating only the games currently selected in the Game List. -The book will be saved on the file specified in the @samp{Common Engine} -options dialog. -The value of @samp{Book Depth} specified in that same dialog will -be used to determine how many moves of each game will be added to -the internal book buffer. -This command can take a long time to process, -and the size of the buffer is currently limited. -At the end the buffer will be saved as a Polyglot book, -but the buffer will not be cleared, -so that you can continue adding games from other game files. -@item Mail Move -@itemx Reload CMail Message -@cindex Mail Move, Menu Item -@cindex Reload CMail Message, Menu Item -See @ref{CMail}. -@item Exit -@cindex Exit, Menu Item -Exits from XBoard. The @kbd{Ctrl-Q} key is a keyboard equivalent. -@end table - -@node Edit Menu -@section Edit Menu -@cindex Menu, Edit -@cindex Edit Menu -@table @asis -@item Copy Game -@cindex Copy Game, Menu Item -Copies a record of the current game to an internal clipboard in PGN -format and sets the X selection to the game text. The @kbd{Ctrl-C} -key is a keyboard equivalent. The game can be -pasted to another application (such as a text editor or another copy -of XBoard) using that application's paste command. In many X -applications, such as xterm and emacs, the middle mouse button can be -used for pasting; in XBoard, you must use the Paste Game command. -@item Copy Position -@cindex Copy Position, Menu Item -Copies the current position to an internal clipboard in FEN format and -sets the X selection to the position text. The shifted @kbd{Ctrl-C} key -is a keyboard equivalent. The position can be pasted -to another application (such as a text editor or another copy of -XBoard) using that application's paste command. In many X -applications, such as xterm and emacs, the middle mouse button can be -used for pasting; in XBoard, you must use the Paste Position command. -@item Copy Game List -@cindex Copy Game List, Menu Item -Copies the current game list to the clipboard, -and sets the X selection to this text. -A format of comma-separated double-quoted strings is used, -including all tags, -so it can be easily imported into spread-sheet programs. -@item Paste Game -@cindex Paste Game, Menu Item -Interprets the current X selection as a game record and loads it, as -with Load Game. The @kbd{Ctrl-V} key is a keyboard equivalent. -@item Paste Position -@cindex Paste Position, Menu Item -Interprets the current X selection as a FEN position and loads it, as -with Load Position. The shifted @kbd{Ctrl-V} key is a keyboard equivalent. -@item Edit Game -@cindex Edit Game, Menu Item -Allows you to make moves for both Black and White, and to change -moves after backing up with the @samp{Backward} command. The clocks do -not run. The @kbd{Ctrl-E} key is a keyboard equivalent. - -In chess engine mode, the chess engine continues to check moves for legality -but does not participate in the game. You can bring the chess engine -into the game by selecting @samp{Machine White}, @samp{Machine Black}, -or @samp{Two Machines}. - -In ICS mode, the moves are not sent to the ICS: @samp{Edit Game} takes -XBoard out of ICS Client mode and lets you edit games locally. -If you want to edit games on ICS in a way that other ICS users -can see, use the ICS @kbd{examine} command or start an ICS match -against yourself. -@item Edit Position -@cindex Edit Position, Menu Item -Lets you set up an arbitrary board position. -The shifted @kbd{Ctrl-E} key is a keyboard equivalent. -Use mouse button 1 to drag pieces to new squares, or to delete a piece -by dragging it off the board or dragging an empty square on top of it. -When you do this keeping the @kbd{Ctrl} key pressed, -or start dragging with a double-click, -you will move a copy of the piece, leaving the piece itself where it was. -In variants where pieces can promote (such as Shogi), -left-clicking an already selected piece promotes or demotes it. -To drop a new piece on a square, press mouse button 2 or 3 over the -square. -This puts a white or black pawn in the square, respectively, -but you can change that to any other piece type by dragging the -mouse down before you release the button. -You will then see the piece on the originally clicked square -cycle through the available pieces -(including those of opposite color), -and can release the button when you see the piece you want. -(Note you can swap the function of button 2 and 3 by pressing -the shift key, and that there is an option @code{monoMouse} -to combine al functions in one button, which then acts as -button 3 over an empty square, and as button 1 over a piece.) -To alter the side to move, you can click the clock -(the words White and Black above the board) -of the side you want to give the move to. -To clear the board you can click the clock of the side that -already has the move (which is highlighted in black). -If you repeat this the board will cycle from empty to a -@code{pallette board} containing every piece once to the initial -position to the one before clearing. -The quickest way to set up a position is usually to start -with the pallette board, and move the pieces to were you -want them, duplicating them where necessary by using the -@kbd{Ctrl} key, dragging those you don't want off board, -and use static button 2 or 3 clicks to place the Pawns. -The old behavior with a piece menu can still be configured -with the aid of the @code{pieceMenu} option. -Dragging empty squares off board can create boards with -holes (inaccessible black squares) in them. -Selecting @samp{Edit Position} causes XBoard to discard -all remembered moves in the current game. - -In ICS mode, changes made to the position by @samp{Edit Position} are -not sent to the ICS: @samp{Edit Position} takes XBoard out of -@samp{ICS Client} mode and lets you edit positions locally. If you want to -edit positions on ICS in a way that other ICS users can see, use -the ICS @kbd{examine} command, or start an ICS match against yourself. -(See also the ICS Client topic above.) -@item Edit Tags -@cindex Edit Tags, Menu Item -Lets you edit the PGN (portable game notation) -tags for the current game. After editing, the tags must still conform to -the PGN tag syntax: - -@example - ::= - - ::= [ ] - ::= - ::= -@end example -@noindent -See the PGN Standard for full details. Here is an example: - -@example -[Event "Portoroz Interzonal"] -[Site "Portoroz, Yugoslavia"] -[Date "1958.08.16"] -[Round "8"] -[White "Robert J. Fischer"] -[Black "Bent Larsen"] -[Result "1-0"] -@end example -@noindent -Any characters that do not match this syntax are silently ignored. Note that -the PGN standard requires all games to have at least the seven tags shown -above. Any that you omit will be filled in by XBoard -with @samp{?} (unknown value), or @samp{-} (inapplicable value). -@item Edit Comment -@cindex Edit Comment, Menu Item -Adds or modifies a comment on the current position. Comments are -saved by @samp{Save Game} and are displayed by @samp{Load Game}, -PGN variations will also be printed in this window, -and can be promoted to main line by right-clicking them. -@samp{Forward}, and @samp{Backward}. -@item Edit Book -@cindex Edit Book, Menu Item -Pops up a window listing the moves available in the GUI book -(specified in the @samp{Common Engine Settings} dialog) -from the currently displayed position, -together with their weights and (optionally in braces) learn info. -You can then edit this list, and the new list will be stored -back into the book when you press 'save changes'. -When you press the button 'add next move', and play a move -on the board, that move will be added to the list with weight 1. -Note that the listed percentages are neither used, nor updated when -you change the weights; they are just there as an optical aid. -When you right-click a move in the list it will be played. -@item Revert -@itemx Annotate -@cindex Revert, Menu Item -@cindex Annotate, Menu Item -If you are examining an ICS game and Pause mode is off, -Revert issues the ICS command @samp{revert}. -In local mode, when you were editing or analyzing a game, -and the @code{-variations} command-line option is switched on, -you can start a new variation by holding the Shift key down while -entering a move not at the end of the game. -Variations can also become the currently displayed line by -clicking a PGN variation displayed in the Comment window. -This can be applied recursively, -so that you can analyze variations on variations; -each time you create a new variation by entering an alternative move -with Shift pressed, or select a new one from the Comment window, -the current variation will be shelved. -@samp{Revert} allows you to return to the most recently shelved variation. -The difference between @samp{Revert} and @samp{Annotate} -is that with the latter, -the variation you are now abandoning will be added as a comment -(in PGN variation syntax, i.e. between parentheses) -to the original move where you deviated, for later recalling. -The @kbd{Home} key is a keyboard equivalent to @samp{Revert}. -@item Truncate Game -@cindex Truncate Game, Menu Item -Discards all remembered moves of the game beyond the current -position. Puts XBoard into @samp{Edit Game} mode if it was not there -already. -The @kbd{End} key is a keyboard equivalent. -@item Backward -@itemx < -@cindex Backward, Menu Item -@cindex <, Button -Steps backward through a series of remembered moves. -The @samp{[<]} button and the @kbd{Alt+LeftArrow} key are equivalents, -as is turning the mouse wheel towards you. -In addition, pressing the ??? key steps back one move, and releasing -it steps forward again. - -In most modes, @samp{Backward} only lets you look back at old positions; -it does not retract moves. This is the case if you are playing against -a chess engine, playing or observing a game on an ICS, or loading a game. -If you select @samp{Backward} in any of these situations, you will not -be allowed to make a different move. Use @samp{Retract Move} or -@samp{Edit Game} if you want to change past moves. - -If you are examining an ICS game, the behavior of @samp{Backward} -depends on whether XBoard is in Pause mode. If Pause mode is -off, @samp{Backward} issues the ICS backward command, which backs up -everyone's view of the game and allows you to make a different -move. If Pause mode is on, @samp{Backward} only backs up your local -view. -@item Forward -@itemx > -@cindex Forward, Menu Item -@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{Alt+RightArrow} 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 -off, @samp{Forward} issues the ICS forward command, which moves -everyone's view of the game forward along the current line. If -Pause mode is on, @samp{Forward} only moves your local view forward, -and it will not go past the position that the game was in when -you paused. -@item Back to Start -@itemx << -@cindex Back to Start, Menu Item -@cindex <<, Button -Jumps backward to the first remembered position in the game. -The @samp{[<<]} button and the @kbd{Alt+Home} key are equivalents. - -In most modes, Back to Start only lets you look back at old -positions; it does not retract moves. This is the case if you -are playing against a local chess engine, playing or observing a game on -a chess server, or loading a game. If you select @samp{Back to Start} in any -of these situations, you will not be allowed to make different -moves. Use @samp{Retract Move} or @samp{Edit Game} if you want to change past -moves; or use Reset to start a new game. - -If you are examining an ICS game, the behavior of @samp{Back to -Start} depends on whether XBoard is in Pause mode. If Pause mode -is off, @samp{Back to Start} issues the ICS @samp{backward 999999} -command, which backs up everyone's view of the game to the start and -allows you to make different moves. If Pause mode is on, @samp{Back -to Start} only backs up your local view. -@item Forward to End -@itemx >> -@cindex Forward to End, Menu Item -@cindex >>, Button -Jumps forward to the last remembered position in the game. The -@samp{[>>]} button and the @kbd{Alt+End} key are equivalents. - -If you are examining an ICS game, the behavior of @samp{Forward to -End} depends on whether XBoard is in Pause mode. If Pause mode -is off, @samp{Forward to End} issues the ICS @samp{forward 999999} -command, which moves everyone's view of the game forward to the end of -the current line. If Pause mode is on, @samp{Forward to End} only moves -your local view forward, and it will not go past the position -that the game was in when you paused. -@end table - -@node View Menu -@section View Menu -@cindex Menu, View -@cindex View Menu -@table @asis -@item Flip View -@cindex Flip View, Menu Item -Inverts your view of the chess board for the duration of the -current game. Starting a new game returns the board to normal. -The @kbd{F2} key is a keyboard equivalent. -@item Show Engine Output -@cindex Show Engine Output, Menu Item -Shows or hides a window in which the thinking output of any loaded engines -is displayed. The shifted @kbd{Alt+O} key is a keyboard equivalent. -XBoard will display lines of thinking output of the same depth ordered by score, -(highest score on top), rather than in the order the engine produced them. -Usually this amounts to the same, as a normal engine search will only find new PV -(and emit it as thinking output) -when it searches a move with a higher score than the previous variation. -But when the engine is in multi-variation mode this needs not always be true, -and it is more convenient for someone analyzing games to see the moves sorted by score. -The order in which the engine found them is only of interest to the engine author, -and can still be deduced from the time or node count printed with the line. -Right-clicking a line in this window, and then moving the mouse vertically with the -right button kept down, will make XBoard play through the PV listed there. -The use of the board window as 'variation board' will normally end when -you release the right button, -or when the opponent plays a move. -But beware: in Analysis mode, moves thus played out might be added to the game, -depending on the setting of the option 'Play moves of clicked PV', -when you initiate the click left of the PV in the score area. -The Engine-Output pane for each engine will contain a header displaying the -multi-PV status and a list of excluded moves in Analysis mode, -which are also responsive to right-clicking: -Clicking the words 'fewer' or 'more' will alter the number of variations -shown at each depth, through the engine's MultiPV option, -while clicking in between those and moving the mouse horizontally adjust -the option 'Multi-PV Margin'. (In so far the engines support those.) -@item Show Move History -@cindex Show Move History, Menu Item -Shows or hides a list of moves of the current game. -The shifted @kbd{Alt+H} key is a keyboard equivalent. -This list allows you to move the display to any earlier position in the game -by clicking on the corresponding move. -@item Show Evaluation Graph -@cindex Show Evaluation Graph, Menu Item -Shows or hides a window which displays a graph of how the engine score(s) -evolved as a function of the move number. -The shifted @kbd{Alt+E} key is a keyboard equivalent. -The title bar shows the score (and search depth at which it was obtained) -of the currently displayed position numerically. -Clicking on the graph will bring -the corresponding position in the board display. -A button 3 click will toggle the display mode between plain and differential -(showing the difference in score between successive half moves). -Using the mouse wheel over the window will change the scale of the -low-score region (from -1 to +1). -@item Show Game List -@cindex Show Game List, Menu Item -Shows or hides the list of games generated by the last @samp{Load Game} -command. The shifted @kbd{Alt+G} key is a keyboard equivalent. -The line describing each game is built from a selection of the PGN tags. -Which tags contribute, and in what order, can be changed by the @samp{Game list tags} -menu dialog, which can be popped up through the @samp{Tags} button below the Game List. -Display can be restricted to a sub-set of the games meeting certain criteria. -A text entry below the game list allows you to type a text that the game lines -must contain in order to be displayed. -Games can also be selected based on their Elo PGN tag, -as set in the @samp{Load Game Options} dialog, which can be popped up through the -@samp{Thresholds} button below the Game List. -Finally they can be selected based on containing a position similar to the one -currently displayed in the main window, by pressing the 'Position' button below -the Game List, (which searches the entire list for the position), or the 'Narrow' -button (which only searches the already-selected games). -What counts as similar enough to be selected can also be set in the -@samp{Load Game Options} dialog, and ranges from an exact match to just the -same material. -@item Tags -@cindex Tags, Menu Item -Pops up a window which shows the PGN (portable game notation) -tags for the current game. -For now this is a duplicate of the @samp{Edit Tags} item in the @samp{Edit} menu. -@item Comments -@cindex Comments, Menu Item -Pops up a window which shows any comments to or variations on the current move. -For now this is a duplicate of the @samp{Edit Comment} item in the @samp{Edit} menu. -@item ICS Input Box -@cindex ICS Input Box, Menu Item -If this option is set in ICS mode, -XBoard -creates an extra window that you can use for typing in ICS commands. -The input box is especially useful if you want to type in something long or do -some editing on your input, because output from ICS doesn't get mixed -in with your typing as it would in the main terminal window. -@item ICS/Chat Console -@cindex ICS Chat/Console, Menu Item -This menu item opens a window in which you can interact with the ICS, -so you don't have to use the messy xterm from which you launched XBoard -for that. -The window has a text entry at the bottom where you can type your -commands and messages unhindered by the stream of ICS output. -The latter will be displayed in a large pane above the input field, -the ICS Console. -Up and down arrow keys can be used to recall previous input lines. -Typing an character in the input field transfers focus back -to the board window (so you could operate the menus there -through accelerator keys). -Typing a printable character in the board window transfers focus -back to the input field of the @samp{ICS Chat/Console} window. -@item Chats -@cindex Chats -There is a row of buttons at the top of the @samp{ICS Chat/Console} dialog, -which can be used to navigate between upto 5 'chats' -with other ICS users (or channels). -These will switch the window to 'chat mode', -where the ICS output pane is vertically split to divert messages from -a specific user or ICS channel to the lower half. -Lines typed in the input field will then be interpreted as messages -to be sent to that user or channel, -(automatically prefixed with the apporpriate ICS command and user name) -rather than as commands to the ICS. -Chats will keep collecting ICS output intended for them even when not displayed, -and their buttons will turn orange to alert the user there has been activity. -Typing in the input field will switch to another active chat, -giving priority to those with content you have not seen yet. -@item New Chat -@cindex New Chat, Menu Item -Buttons for chats currently not assigned to a user or channel -will carry the text @samp{New Chat}, and pressing them will -switch to chat mode, enabling you to enter the user name or channel number -you want to use it for. -Typing Ctrl-N in the input field is a keyboard equivalent. -@item Chat partner -@cindex Chat partner, Menu Item -To (re-)assign a chat, write the name of your chat partner, the channel number, -or the words 'shouts', 'whispers', 'cshouts' in the @samp{Chat partner} text entry -(ending with !). -Typing Ctrl-O in the input field at the bottom of the window will -open a chat with the person that last sent you a 'tell' that was printed -in the ICS Console output pane. -The @samp{ICS text menu} can contain a button @samp{Open Chat (name)} -that can be used to open a chat with as partner the word/number you -right-clicked in the output pane to pop up this menu. -@item End Chat -@cindex End Chat, Menu Item -This button, only visible when the chat pane is open, -will clear the @samp{Chat partner} field, so that the chat can be -assigned to a new user or channel. -Typing Ctrl-E in the input field is a keyboard equivalent. -@item Hide -@cindex Hide, Menu Item -This button, only visible when the chat pane is open, -will close the latter, so you can use the input field -to give commands to the ICS again. -Typing Ctrl-H in the input field is a keyboard equivalent. -@item ICS text menu -@cindex ICS text menu, Menu Item -Brings up a menu that is user-configurable through the @code{icsMenu} option. -Buttons in this menu can sent pre-configured commands directly to the ICS, -or can put partial commands in the input field of the @samp{ICS Chat/Console} -window, so that you can complete those with some text of your own before -sending them to the ICS by pressing Enter. -This menu item can also be popped up by right-clicking in the text memos -of the ICS Chat/Console window. -In that case the word that was clicked can be incorporated in the message -sent to the ICS. E.g. to challenge a player whose name you click for a game, -or prepare for sending him a message through a 'tell' commands. -@item Board -@cindex Board, Menu Item -Summons a dialog where you can customize the look of the chess board. -@item White Piece Color -@itemx Black Piece Color -@itemx Light Square Color -@itemx Dark Square Color -@itemx Highlight Color -@itemx Premove Highlight Color -@cindex Piece Color, Menu Item -@cindex Square Color, Menu Item -@cindex Highlight Color, Menu Item -These items set the color of pieces, board squares and move highlights -(borders or arrow). -Square colors are only used when the @samp{Use Board Textures} option is off, -the piece colors only when @samp{Use piece bitmaps with their own colors} is off. -You can type the color as hexadecimally encoded RGB value preceded by '#', -or adjust it through the R, G, B and D buttons to make it redder, greener, bluer -or darker. -A sample of the adjusted color will be displayed behind its text description; -pressing this colored button restores the default value for the color. -@item Flip Pieces Shogi Style -@cindex Flip Pieces Shogi Style, Menu Item -With this option on XBoard will swap white and black pieces, -when you flip the view of the board to make white play downward. -This should be used with piece themes that do not distinguish sides by color, -but by orientation. -@item Mono Mode -@cindex Mono Mode, Menu Item -This option sets XBoard to pure black-and-white display -(no grey scales, and thus no anti-aliasing). -@item Logo Size -@cindex Logo Size, Menu Item -Specifies the width of the engine logos displayed next to the clocks, in pixels. -Setting it to 0 suppresses the display of such logos. -The height of the logo will be half its width. -In the GTK build of XBoard any non-zero value is equivalent, -and the logos are always sized to 1/4 of the board width. -@item Line Gap -@cindex Line Gap, Menu Item -This option specifies the width of the grid lines that separate the squares, -which change color on highlighting the move. -Setting it to 0 suppresses these lines, which in general looks better, -but hides the square-border highlights, -so that you would have to rely on other forms of highlighting. -Setting the value to -1 makes XBoard choose a width by itself, -depending on the square size. -@item Use Board Textures -@itemx Light-Squares Texture File -@itemx Dark-Squares Texture File -@cindex Use Board Texture, Menu Item -@cindex Texture Files, Menu Item -When the option @samp{Use Board Textures} is set, -the squares will not be drawn as evenly colored surfaces, -but will be cut from a texture image, as specified by the -@samp{Texture Files}. -Separate images can be used for light and dark squares. -XBoard will try to cut the squares out of the texture image -with as little overlap as possible, so they all look different. -The name of the texture file can contain a size hint, -e.g. @code{xqboard-9x10.png}, alerting XBoard to the fact that -it contains a whole-board image, out of which squares have to -be cut in register with the nominal sub-division. -@item Use external piece bitmaps with their own color -@cindex Draw pieces with their own colors, Menu Item -When this option is on XBoard will ignore the piece-color settings, -and draw the piece images in their original colors. -The piece-color settings would only work well for evenly colored -pieces, such as the default theme. -@item Directory with Pieces Images -@cindex Piece-Image Directory, Menu Item -When a directory is specified here, XBoard will first look for -piece images (SVG or PNG files) in that directory, -and fall back on the image from the default theme only for -images it cannot find there. -An image file called White/BlackTile in the directory will be prefered -as fall-back for missing pieces over the default image, however. -@item Selectable themes -@itemx New name for current theme -@cindex Board Themes, Menu Item -@cindex Theme name, Menu Item -When a theme name is specified while pressing 'OK', -the combination of settings specified in the dialog -will be stored in XBoard's list of themes, -which will be saved with the other options in the settings file -(as the @code{themeNames} option). -This name will then appear in the selection listbox next time -you open the dialog, -so that you can recall the entire combination of settings -by double-clicking it. - - -Here you can specify the directory from which piece images should be taken, -when you don't want to use the built-in piece images -(see @code{pieceImageDirectory} option), -external images to be used for the board squares -(@code{liteBackTextureFile} and @code{darkBackTextureFile} options), -and square and piece colors for the default pieces. -The current combination of these settings can be assigned a 'theme' name -by typing one in the text entry in the lower-left of the dialog, -and closing the latter with OK. -It will then appear in the themes listbox next time you open the dialog, -where you can recall the complete settings combination with a double-click. -@item Fonts -@cindex Fonts, Menu Item -Pops up a dialog where you can set the fonts used in the main elements of various windows. -Pango font names can be typed for each window type, -and behind each text entry there are buttons to adjust the point size, -and toggle the 'bold' or 'italic' attributes of the font. -@item Game List Tags -@cindex Game List Tags, Menu Item -a duplicate of the Game List dialog in the Options menu. -@end table - -@node Mode Menu -@section Mode Menu -@cindex Menu, Mode -@cindex Mode Menu -@table @asis -@item Machine White -@cindex Machine White, Menu Item -Tells the chess engine to play White. -The @kbd{Ctrl-W} key is a keyboard equivalent. -@item Machine Black -@cindex Machine Black, Menu Item -Tells the chess engine to play Black. -The @kbd{Ctrl-B} key is a keyboard equivalent. -@item Two Machines -@cindex Two Machines, Menu Item -Plays a game between two chess engines. -The @kbd{Ctrl-T} key is a keyboard equivalent. -@item Analysis Mode -@cindex Analysis Mode, Menu Item -@cindex null move -@cindex move exclusion -XBoard tells the chess engine to start analyzing the current game/position -and shows you the analysis as you move pieces around. -The @kbd{Ctrl-A} key is a keyboard equivalent. -Note: Some chess engines do not support Analysis mode. - -To set up a position to analyze, you do the following: - -1. Set up the position by any means. (E.g. using @samp{Edit Position} -mode, pasing a FEN or loading a game and stepping to the position.) - -2. Select Analysis Mode from the Mode Menu to start the analysis. - -You can now play legal moves to create follow-up positions for the -engine to analyze, while the moves will be remembered as a stored game, -and then step backward through this game to take the moves back. -Note that you can also click on the clocks to set the opposite -side to move (adding a so-called @samp{null move} to the game). - -You can also tell the engine to exclude some moves from analysis. -(Engines that do not support the exclude-moves feature will -ignore this, however.) -The general way to do this is to play the move you want to exclude -starting with a double click on the piece. -When you use drag-drop moving, the piece you grab with a double click -will also remain on its square, to show you that you are not really -making the move, but just forbid it from the current position. -Playing a thus excluded move a second time will include it again. -Excluded moves will be listed as text in a header line in the -Engine Output window, and you can also re-include them by -right-clicking them there. -This header line will also contain the words 'best' and 'tail'; -right-clicking those will exclude the currently best move, -or all moves not explicitly listed in the header line. -Once you leave the current position all memory of excluded -moves will be lost when you return there. - - -Selecting this menu item while already in @samp{Analysis Mode} will -toggle the participation of the second engine in the analysis. -The output of this engine will then be shown in the lower pane -of the Engine Output window. -The analysis function can also be used when observing games on an ICS -with an engine loaded (zippy mode); the engine then will analyze -the positions as they occur in the observed game. - -@item Analyze Game -@cindex Analyze Game, Menu Item -This option subjects the currently loaded game to automatic -analysis by the loaded engine. -The @kbd{Ctrl-G} key is a keyboard equivalent. -XBoard will start auto-playing the game from the currently displayed position, -while the engine is analyzing the current position. -The game will be annotated with the results of these analyses. -In particlar, the score and depth will be added as a comment, -and the PV will be added as a variation. - -Normally the analysis would stop after reaching the end of the game. -But when a game is loaded from a multi-game file -while @samp{Analyze Game} was already switched on, -the analysis will continue with the next game in the file -until the end of the file is reached (or you switch to another mode). - -The time the engine spends on analyzing each move can be controlled -through the command-line option @samp{-timeDelay}, -which can also be set from the @samp{Load Game Options} menu dialog. -Note: Some chess engines do not support Analysis mode. -@item Edit Game -Duplicate of the item in the Edit menu. -Note that @samp{Edit Game} is the idle mode of XBoard, and can be used -to get you out of other modes. E.g. to stop analyzing, stop a game -between two engines or stop editing a position. -@item Edit Position -Duplicate of the item in the Edit menu. -@item Training -@cindex Training, Menu Item -Training mode lets you interactively guess the moves of a game for one -of the players. You guess the next move of the game by playing the -move on the board. If the move played matches the next move of the -game, the move is accepted and the opponent's response is auto-played. -If the move played is incorrect, an error message is displayed. You -can select this mode only while loading a game (that is, after -selecting @samp{Load Game} from the File menu). While XBoard is in -@samp{Training} mode, the navigation buttons are disabled. -@item ICS Client -@cindex ICS Client, Menu Item -This is the normal mode when XBoard -is connected to a chess server. If you have moved into -Edit Game or Edit Position mode, you can select this option to get out. - -To use xboard in ICS mode, run it in the foreground with the -ics -option, and use the terminal you started it from to type commands and -receive text responses from the chess server. See -@ref{Chess Servers} below for more information. - -XBoard activates some special position/game editing features when you -use the @kbd{examine} or @kbd{bsetup} commands on ICS and you have -@samp{ICS Client} selected on the Mode menu. First, you can issue the -ICS position-editing commands with the mouse. Move pieces by dragging -with mouse button 1. To drop a new piece on a square, press mouse -button 2 or 3 over the square. This brings up a menu of white pieces -(button 2) or black pieces (button 3). Additional menu choices let -you empty the square or clear the board. Click on the White or Black -clock to set the side to play. You cannot set the side to play or -drag pieces to arbitrary squares while examining on ICC, but you can -do so in @kbd{bsetup} mode on FICS. In addition, the menu commands -@samp{Forward}, @samp{Backward}, @samp{Pause}, and @samp{Stop Examining} -have special functions in this mode; see below. -@item Machine Match -@cindex Machine match, Menu Item -Starts a match between two chess programs, -with a number of games and other parameters set through -the @samp{Tournament Options} menu dialog. -When a match is already running, selecting this item will make -XBoard drop out of match mode after the current game finishes. -@item Pause -@cindex Pause, Menu Item -Pauses updates to the board, and if you are playing against a chess engine, -also pauses your clock. To continue, select @samp{Pause} again, and the -display will automatically update to the latest position. -The @samp{P} button and keyboard @kbd{Pause} key are equivalents. - -If you select Pause when you are playing against a chess engine and -it is not your move, the chess engine's clock -will continue to run and it will eventually make a move, at which point -both clocks will stop. Since board updates are paused, however, -you will not see the move until you exit from Pause mode (or select Forward). -This behavior is meant to simulate adjournment with a sealed move. - -If you select Pause while you are observing or examining a game on a -chess server, you can step backward and forward in the current history -of the examined game without affecting the other observers and -examiners, and without having your display jump forward to the latest -position each time a move is made. Select Pause again to reconnect -yourself to the current state of the game on ICS. - -If you select @samp{Pause} while you are loading a game, the game stops -loading. You can load more moves manually by selecting @samp{Forward}, or -resume automatic loading by selecting @samp{Pause} again. -@end table - -@node Action Menu -@section Action Menu -@cindex Menu, Action -@cindex Action, Menu -@table @asis -@item Accept -@cindex Accept, Menu Item -Accepts a pending match offer. -The @kbd{F3} key is a keyboard equivalent. -If there is more than one offer -pending, you will have to type in a more specific command -instead of using this menu choice. -@item Decline -@cindex Decline, Menu Item -Declines a pending offer (match, draw, adjourn, etc.). -The @kbd{F4} key is a keyboard equivalent. If there -is more than one offer pending, you will have to type in a more -specific command instead of using this menu choice. -@item Call Flag -@cindex Call Flag, Menu Item -Calls your opponent's flag, claiming a win on time, or claiming -a draw if you are both out of time. -The @kbd{F5} key is a keyboard equivalent. -You can also call your -opponent's flag by clicking on his clock. -@item Draw -@cindex Draw, Menu Item -Offers a draw to your opponent, accepts a pending draw offer -from your opponent, or claims a draw by repetition or the 50-move -rule, as appropriate. The @kbd{F6} key is a keyboard equivalent. -@item Adjourn -@cindex Adjourn, Menu Item -Asks your opponent to agree to adjourning the current game, or -agrees to a pending adjournment offer from your opponent. -The @kbd{F7} key is a keyboard equivalent. -@item Abort -@cindex Abort, Menu Item -Asks your opponent to agree to aborting the current game, or -agrees to a pending abort offer from your opponent. -The @kbd{F8} key is a keyboard equivalent. An aborted -game ends immediately without affecting either player's rating. -@item Resign -@cindex Resign, Menu Item -Resigns the game to your opponent. The @kbd{F9} key is a -keyboard equivalent. -@item Stop Observing -@cindex Stop Observing, Menu Item -Ends your participation in observing a game, by issuing the ICS -observe command with no arguments. ICS mode only. -The @kbd{F10} key is a keyboard equivalent. -@item Stop Examining -@cindex Stop Examining, Menu Item -Ends your participation in examining a game, by issuing the ICS -unexamine command. ICS mode only. -The @kbd{F11} key is a keyboard equivalent. -@item Upload to Examine -@cindex Upload to Examine, Menu Item -Create an examined game of the proper variant on the ICS, -and send the game there that is currenty loaded in XBoard -(e.g. through pasting or loading from file). -You must be connected to an ICS for this to work. -@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, respectively. -The PGN file of the game will accompany the result string -by the comment "user adjudication". -@end table - -@node Engine Menu -@section Engine Menu -@cindex Engine Menu -@cindex Menu, Engine -@table @asis -@item Edit Engine List -@cindex Edit Engine List, Menu Item -Opens a window that shows the list of engines registered for use -by XBoard, together with the options that would be used with them -when you would select them from the @samp{Load Engine} dialogs. -You can then edit this list, e.g. for re-ordering the engines, -or adding uncommon options needed by this engine -(e.g. to cure non-compliant behavior). - -By editing you can also organize the engines into collapsible groups. -By sandwiching a number of engine lines between lines "# NAME" and "# end", -the thus enclosed engines will not initially appear in engine listboxes -of other dialogs, but only the single line "# NAME" -(where NAME can be an arbitrary text) will appear in their place. -Selecting that line will then show the enclosed engines in the listbox, -which recursively can contain other groups. -The line with the group name will still present as a header, -and selecting that line will collapse the group again, -and makes the listbox go back to displaying the surrounding group. -@item Load New 1st Engine -@itemx Load New 2nd Engine -@cindex Load New Engine, Menu Item -Pops up a dialog where you can select or specify an engine to be loaded. -You can even replace engines during a game, without disturbing that game. -(Beware that after loading an engine, XBoard will always be in Edit Game mode, -so you will have to tell the new engine what to do before it does anything!) -@table @asis -@item Select engine from list -@cindex Select engine, Menu Item -The listbox shows the engines registered for use with XBoard before. -(This means XBoard has information on the engine type, whether it plays book etc. -in the engine list stored in its settings file.) -Double-clicking an engine here will load it and close the dialog. -The list can also contain groups, indicated by a starting '#' sign. -Double-clicking such a group will 'open' it, -and show the group contents in the listbox instead of the total list, -with the group name as header. -Double-clicking the header will 'close' the group again. -@item Nickname -@itemx Use nickname in PGN player tags of engine-engine games -@cindex Nickname, Menu Item -When a @samp{Nickname} is specified, the engine will appear under this name -in the @samp{Select Engine} listbox. -Otherwise the name there will be a tidied version of the engine command. -The user can specify if the nickname is also to be used in PGN tags; -normally the name engines report theselves would be used there. -@item Engine Command -@cindex Engine Command, Menu Item -The command needed to start the engine from the command line. -For compliantly installed engine this is usually just a single word, -the name of the engine package (e.g. 'crafty' or 'stockfish'). -Some engines need additional parameters on the command line. -For engines that are not in a place where the system would expect them -a full pathname can be specified, and usually the browse button -for this oprion is the easiest way to obtain that. -@item Engine Directory -@cindex Engine Directory, Menu Item -Compliant engines could run from any directory, -and by default this option is proposed as '.', the current directory. -If a (path)name is specified here, XBoard will start the engine -in that directory. -If you make the field empty, it will try to derive the directory -from the engine command (if that was a path name). -@item UCI -@cindex UCI, Menu Item -When the @samp{UCI} checkbox is ticked XBoard will assume -the engine is of UCI type, and will invoke the corresponding adapter -(as specified in the @code{adapterCommand} option stored in its -settings file)to use it. -By default this adapter is Polyglot, -which must be installed from a separate package! -@item USI/UCCI -@cindex USI/UCCI, Menu Item -Ticking this checkbox informs XBoard that the engine is of USI or UCCI type -(as Shogi or Xiangqi engines often are). -This makes XBoard invoke an adapter to run the engines, -as specified by the @code{uxiAdapter} option stored in its settings file. -The UCI2WB program is an adapter that can handle both these engine types, -as well as UCI. -@item WB protocol v1 -@cindex WB protocol v1, Menu Item -Ticking this checkbox informs XBoard the engine is using an old version (1) -of the communication protocol, so that it won't respond to a request -to interrogate its properties. -XBoard then won't even try that, saving you a wait of several seconds -each time the engine is started. -Do not use this on state-of-the-art engines, -as it would prevent XBoard from interrogating its capabilities, -so that many of its features might not work! -@item Must not use GUI book -@cindex Use GUI book, Menu Item -By default XBoard assumes engines are responsible for their own opening book, -but unticking this option makes XBoard consult its own book -(as per @samp{Opening-Book Filename}) on behalf of the engine. -@item Add this engine to the list -@cindex Add engine, Menu Item -By default XBoard would add the engine you specified, -with all the given options to its list of registered engines -(kept in its settings file), when you press 'OK'. -Next time you could then simply select it from the listbox, -or use the command "xboard -fe NICKNAME" to start XBoard with the -engine and accompanying options. -New engines are always added at the end of the existing list, -or, when you have opened a group in the @samp{Select Engine} listbox, -at the end of that group. -But can be re-ordered later with the aid -of the @samp{Edit Engine List} menu item. -When you untick this checkbox before pressing 'OK' -the engine will be loaded, but will not be added to the engine list. -@item Force current variant with this engine -@cindex Force variant with engine, Menu Item -Ticking this option will make XBoard automatically start the engine -in the current variant, even when XBoard was set for a different -variant when you loaded the engine. -Useful when the engine plays multiple variants, -and you specifically want to play one different from its primary one. -@end table - -@item Engine #1 Settings -@itemx Engine #2 Settings -@cindex Engine #N Settings, Menu Item -Pop up a menu dialog to alter the settings specific to the applicable engine. -For each parameter the engine allows to be set, -a control element will appear in this dialog that can be used to alter the value. -Depending on the type of parameter (text string, number, multiple choice, -on/off switch, instantaneous signal) the appropriate control will appear, -with a description next to it. -XBoard has no idea what these values mean; it just passes them on to the engine. -How this dialog looks is completely determined by the engine, -and XBoard just passes it on to the user. -Many engines do not have any parameters that can be set by the user, -and in that case the dialog will be empty (except for the OK and cancel buttons). -UCI engines usually have many parameters. (But these are only visible with -a sufficiently modern version of the Polyglot adapter needed to run UCI engines, -e.g. Polyglot 2.0.1.) For native XBoard engines this is less common. - -@item Common Settings -@cindex Common Settings, Menu Item -Pops up a menu dialog 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. -The shifted @kbd{Alt+U} key is a keyboard equivalent. -Older XBoard/WinBoard engines might not respond to these settings, -but UCI engines always should. -@item Maximum Number of CPUs per Engine -@cindex Max. Number of CPUs, Menu Item -Specifies the number of search threads any engine can maximally use. -Do not set it to a number larger than the number of cores your computer has. -(Or half of it when you want two engines to run simultaneously, -as in a Two-Machines game with @samp{Ponder Next Move} on.) -@item Polyglot Directory -@item Hash-Table Size -@cindex Hash-Table Size -Specifies the maximum amount of memory (RAM) each engine is allowed to use -for storing info on positions it already searched, -so it would not have to search them again. -Do not set it so that it is more than half -(or if you use two engines, more than a quarter) -of the memory your computer has, -or it would slow the engines down by an extreme amount. -@item EGTB Path -@cindex EGTB Path, Menu Item -Sets the value of the @code{egtFormats} option, which specifies -where on your computer the files for End-Game Tables are stored. -It must be a comma-separated list of path names, -the path for each EGT flavor prefixed with the name of the latter -and a colon. E.g. "nalimov:/home/egt/dtm,syzygy:/home/egt/dtz50". -The path names after the colon will be sent to the engines -that say they can use the corresponding EGT flavor. -@item EGTB Cache Size -@cindex EGTB Cache Size, Menu Item -Specifies the amount of memory the engine should use to -buffer end-game information. -Together with the @samp{Hash-Table Size} this determines how -much memory the engine is allowed to use in total. -@item Use GUI Book -@itemx Opening-Book Filename -@cindex Use GUI Book, Menu Item -@cindex Opening-Book Filename, Menu Item -The @samp{Opening-Book Filename} specifies an opening book -in Polyglot format (usually a .bin file), -from which XBoard can play moves on behalf of the engine. -This is also the book file on which the @samp{Edit Book} -and @samp{Save Games as Book} menu items operate. -A checkbox @samp{Use GUI Book} can be used to temporarily -disable the book without losing the setting. -(This does not prevent editing or saving games on it!) -@item Book Depth -@itemx Book Variety -@cindex Book Depth, Menu Item -@cindex Book Variety, Menu Item -The way moves are selected from the book can be controlled by two options. -@samp{Book Depth} controls for how deep into the game the book -will be consulted (measured in full moves). -@samp{Book Variety} controls the likelihood of playing weaker moves. -When the variety is set to 50, moves will be played with the probability -specified in the book. -When set to 0, only the move(s) with the highest probability will be played. -When set to 100, all listed moves will be played with equal pobability. -Other settings interpolate between that. -@item Engine #1 Has Own Book -@itemx Engine #2 Has Own Book -@cindex Engine Has Own Book -These checkboxes control on a per-engine basis -whether XBoard will consult the opening book for them. -If ticked, XBoard will never play moves from its GUI book, -giving the engine the opportunity to use its own. -These options are automatically set whenever you load an engine, -based on the setting of @samp{Must not use GUI book} -when you installed that through the @samp{Load Engine} menu dialog. -@item Hint -@cindex Hint, Menu Item -Displays a move hint from the chess engine. -@item Book -@cindex Book, Menu Item -Displays a list of possible moves from the chess engine's opening -book. The exact format depends on what chess engine you are using. -With GNU Chess 4, the first column gives moves, the second column -gives one possible response for each move, and the third column shows -the number of lines in the book that include the move from the first -column. If you select this option and nothing happens, the chess -engine is out of its book or does not support this feature. -@item Move Now -@cindex Move Now, Menu Item -Forces the chess engine to move immediately. Chess engine mode only. -The @kbd{Ctrl-M} key is a keyboard equivalent. -Many engines won't respond to this. -@item Retract Move -@cindex Retract Move, Menu Item -Retracts your last move. In chess engine mode, you can do this only -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. -The @kbd{Ctrl-X} key is a keyboard equivalent. -@item Recently Used Engines -@cindex Recently Used Engines, In Menu -At the bottom of the engine menu there can be a list of names -of engines that you recently loaded through the Load Engine menu dialog -in previous sessions. -Clicking on such a name will load that engine as first engine, -so you won't have to search for it in your list of installed engines, -if that is very long. -The maximum number of displayed engine names is set by the -@code{recentEngines} command-line option. -@end table - -@node Options Menu -@section Options Menu -@cindex Menu, Options -@cindex Options Menu -@section General Options -@cindex General Options, Menu Item -The following items to set option values appear in the dialog -summoned by the general Options menu item. -@table @asis -@item Absolute Analysis Scores -@cindex Absolute Analysis Scores, Menu Item -Controls if scores on the Engine Output window during analysis -will be printed from the white or the side-to-move point-of-view. -@item Almost Always Queen -@cindex Almost Always Queen, Menu Item -If this option is on, 7th-rank pawns automatically change into -Queens when you pick them up, -and when you drag them to the promotion square and release them there, -they will promote to that. -But when you drag such a pawn backwards first, -its identity will start to cycle through the other available pieces. -This will continue until you start to move it forward; -at which point the identity of the piece will be fixed, -so that you can safely put it down on the promotion square. -If this option is off, what happens depends on the -option @code{alwaysPromoteToQueen}, -which would force promotion to Queen when true. -Otherwise XBoard would bring up a dialog -box whenever you move a pawn to the last rank, asking what piece -you want to promote to. -@item Animate Dragging -@cindex Animate Dragging, Menu Item -If Animate Dragging is on, while you are dragging a piece with the -mouse, an image of the piece follows the mouse cursor. -If Animate Dragging is off, there is no visual feedback while you are -dragging a piece, but if Animate Moving is on, the move will be -animated when it is complete. -@item Animate Moving -@cindex Animate Moving, Menu Item -If Animate Moving is on, all piece moves are animated. An image of the -piece is shown moving from the old square to the new square when the -move is completed (unless the move was already animated by Animate Dragging). -If Animate Moving is off, a moved piece instantly disappears from its -old square and reappears on its new square when the move is complete. -The shifted @kbd{Ctrl-A} key is a keyboard equivalent. -@item Auto Flag -@cindex Auto Flag, Menu Item -If this option is on and one player runs out of time -before the other, -XBoard -will automatically call his flag, claiming a win on time. -The shifted @kbd{Ctrl-F} key is a keyboard equivalent. -In ICS mode, Auto Flag will only call your opponent's flag, not yours, -and the ICS may award you a draw instead of a win if you have -insufficient mating material. In local chess engine mode, -XBoard -may call either player's flag. -@item Auto Flip View -@cindex Auto Flip View, Menu Item -If the Auto Flip View option is on when you start a game, the board -will be automatically oriented so that your pawns move from the bottom -of the window towards the top. - -If you are playing a game on an ICS, the board is always -oriented at the start of the game so that your pawns move from -the bottom of the window towards the top. Otherwise, the starting -orientation is determined by the @code{flipView} command line option; -if it is false (the default), White's pawns move from bottom to top -at the start of each game; if it is true, Black's pawns move from -bottom to top. @xref{User interface options}. -@item Blindfold -@cindex Blindfold, Menu Item -If this option is on, XBoard displays the board as usual but does -not display pieces or move highlights. You can still move in the -usual way (with the mouse or by typing moves in ICS mode), even though -the pieces are invisible. -@item Drop Menu -@cindex Drop Menu, Menu Item -Controls if right-clicking the board in crazyhouse / bughouse -will pop up a menu to drop a piece on the clicked square -(old, deprecated behavior) -or allow you to step through an engine PV -(new, recommended behavior). -@item Enable Variation Trees -@cindex Enable Variation Trees, Menu Item -If this option is on, playing a move in Edit Game or Analyze mode -while keeping the Shift key pressed will start a new variation. -You can then recall the previous line through the @samp{Revert} menu item. -When off, playing a move will truncate the game and append the move -irreversibly. -@item Headers in Engine Output Window -@cindex Headers in Engine Output Window, Menu Item -Controls the presence of column headers above the variations and -associated information printed by the engine, on which you can issue -button 3 clicks to open or close the columns. -Available columns are search depth, score, node count, time used, -tablebase hits, search speed and selective search depth. -@item Hide Thinking -@cindex Hide Thinking, Menu Item -If this option is off, the chess engine's notion of the score and best -line of play from the current position is displayed as it is -thinking. The score indicates how many pawns ahead (or if negative, -behind) the chess engine thinks it is. In matches between two -machines, the score is prefixed by @samp{W} or @samp{B} to indicate -whether it is showing White's thinking or Black's, and only the thinking -of the engine that is on move is shown. -The shifted @kbd{Ctrl-H} key is a keyboard equivalent. -@item Highlight Last Move -@cindex Highlight Last Move, Menu Item -If Highlight Last Move is on, after a move is made, the starting and -ending squares remain highlighted. In addition, after you use Backward -or Back to Start, the starting and ending squares of the last move to -be unmade are highlighted. -@item Highlight with Arrow -@cindex Highlight with Arrow, Menu Item -Causes the highlighting described in Highlight Last Move to be done -by drawing an arrow between the highlighted squares, -so that it is visible even when the width of the grid lines is set to zero. -@item One-Click Moving -@cindex One-Click Moving, Menu Item -If this option is on, XBoard does not wait for you to click both the -from- and the to-square, or drag the piece, but performs a move as soon -as it is uniqely specified. -This applies to clicking an own piece that only has a single legal move, -clicking an empty square or opponent piece where only one of your pieces -can move (or capture) to. -Furthermore, a double-click on a piece that can only make a single capture -will cause that capture to be made. -Promoting a Pawn by clicking its to-square will suppress the promotion -popup or other methods for selecting an under-promotion, -and make it promote to Queen. -@item Periodic Updates -@cindex Periodic Updates, Menu Item -If this option is off (or if -you are using a chess engine that does not support periodic updates), -the analysis window -will only be updated when the analysis changes. If this option is -on, the Analysis Window will be updated every two seconds. -@item Play Move(s) of Clicked PV -@cindex Play Move(s) of Clicked PV, Menu Item -If this option is on, right-clicking on the first move of a PV -or on the data fields left of it in the Engine Output window -during Analyze mode will cause the first move of that PV to be played. -You could also play more than one (or no) PV move by moving the mouse -to engage in the PV walk such a right-click will start, -to seek out another position along the PV where you want to continue -the analysis, before releasing the mouse button. -Clicking on later moves of the PV only temporarily show the moves -for as long you keep the mouse button down, -without adding them to the game. -@item Ponder Next Move -@cindex Ponder Next Move, Menu Item -If this option is off, the chess engine will think only when it is on -move. If the option is on, the engine will also think while waiting -for you to make your move. -The shifted @kbd{Ctrl-P} key is a keyboard equivalent. -@item Popup Exit Message -@cindex Popup Exit Message, Menu Item -If this option is on, when XBoard wants to display a message just -before exiting, it brings up a modal dialog box and waits for you to -click OK before exiting. If the option is off, XBoard prints the -message to standard error (the terminal) and exits immediately. -@item Popup Move Errors -@cindex Popup Move Errors, Menu Item -If this option is off, when you make an error in moving (such as -attempting an illegal move or moving the wrong color piece), the -error message is displayed in the message area. If the option is -on, move errors are displayed in small pop-up windows like other errors. -You can dismiss an error pop-up either by clicking its OK button or by -clicking anywhere on the board, including down-clicking to start a move. -@item Scores in Move List -@cindex Scores in Move List, Menu Item -If this option is on, XBoard will display the depth and score -of engine moves in the Move List, in the format of a PGN comment. -@item Show Coords -@cindex Show Coords, Menu Item -If this option is on, XBoard displays algebraic coordinates -along the board's left and bottom edges. -@item Show Target Squares -@cindex Show Target Squares, Menu Item -If this option is on, all squares a piece that is 'picked up' with the mouse -can legally move to are highighted with a fat colored dot in -yellow (non-captures) or red (captures). -Special moves might have other colors -(e.g. magenta for promotion, cyan for a partial move). -Legality testing must be on for XBoard to know how the piece moves, -but with legality testing off some engines would offer this information. -@item Sticky Windows -@cindex Sticky Windows, Menu Item -Controls whether the auxiliary windows such as Engine Output, Move History -and Evaluation Graph should keep touching XBoard's main window when -you move the latter. -@item Test Legality -@cindex Test Legality, Menu Item -If this option is on, XBoard tests whether the moves you try to make -with the mouse are legal and refuses to let you make an illegal move. -The shifted @kbd{Ctrl-L} key is a keyboard equivalent. -Moves loaded from a file with @samp{Load Game} are also checked. If -the option is off, all moves are accepted, but if a local chess engine -or the ICS is active, they will still reject illegal moves. Turning -off this option is useful if you are playing a chess variant with -rules that XBoard does not understand. (Bughouse, suicide, and wild -variants where the king may castle after starting on the d file are -generally supported with Test Legality on.) -@item Top-Level Dialogs -@cindex Top-Level Dialogs, Menu Item -Controls whether the auxiliary windows will appear as icons in the -task bar and independently controllable, or whether they open and -minimize all together with the main window. -@item Flash Moves -@itemx Flash Rate -@cindex Flash Moves, Menu Item -@cindex Flash Rate, Menu Item -If this option is non-zero, whenever a move is completed, -the moved piece flashes the specified number of times. -The flash-rate setting determines how rapidly this flashing occurs. -@item Animation Speed -@cindex Animation Speed, Menu Item -Determines the duration (in msec) of an animation step, -when @samp{Animate Moving} is swiched on. -@item Zoom factor in Evaluation Graph -@cindex Zoom factor in Evaluation Graph, Menu Item -Sets the value of the @code{evalZoom} option, -indicating the factor by which the score interval (-1,1) should be -blown up on the vertical axis of the Evaluation Graph. -@end table -@section Time Control -@cindex Time Control, Menu Item -Pops up a sub-menu where you can set the time-control parameters interactively. -The shifted @kbd{Alt+T} key is a keyboard equivalent. -@table @asis -@item classical -@cindex classical, Menu Item -Selects classical TC, -where the game is devided into sessions of a certain number of moves, -and after each session the start time is again added to the clocks. -@item incremental -@cindex incremental, Menu Item -Selects a TC mode where the game will start with a base time on the clocks, -and after every move an 'increment' will be added to it. -@item fixed max -@cindex fixed max, Menu Item -Selects a TC mode where you have to make each move within a given time, -and any left-over time is not carried over to the next move. -@item Divide entered times by 60 -@cindex Divide entered times by 60, Menu Item -To allow entering of sub-minute initial time or sub-second increment, -you can tick this checkbox. -The initial time can then be entered in seconds, -and the increment in units of 1/60 second. -@item Moves per session -@cindex Moves per session, Menu Item -Sets the duration of a session for classical time control. -@item Initial time -@cindex Initial time, Menu Item -Time initially on the clock in classical or incremental time controls. -In classical time controls this time will also be added to the clock -at the start of ach new session. -@item Increment or max -@cindex Increment or max, Menu Item -Time to be added to the clock after every move in incremental TC mode. -Fore 'fixed maximum' TC mode, the clock will be set to this time -before every move, irrespective of how much was left on that clock. -@item Time-Odds factors -@cindex Time-Odds factors, Menu Item -When these options are set to 1 the clocks of the players will be set -according to the other specified TC parameters. -Players can be given unequal times by specifying a time-odds factor -for one of them (or a different factor for both of them). -Any time received by that player will then be divided by that factor. -@end table - -@section Adjudications -@cindex Adjudications, Menu Item -Pops up a sub-menu where you can enable or disable various adjudications -that XBoard can perform in engine-engine games. -The shifted @kbd{Alt+J} key is a keyboard equivalent. -@table @asis -@item Detect all Mates -@cindex Detect all Mates, Menu Item -When this option is set -XBoard will terminate the game on checkmate or stalemate, -even if the engines would not do so. -Only works when @samp{Test Legality} is on. -@item Verify Engine Result Claims -@cindex Verify Engine Result Claims, Menu Item -When this option is set -XBoard will verify engine result claims, -(forfeiting engines that make false claims), -rather than naively beleiving the engine. -Only works when @samp{Test Legality} is on. -@item Draw if Insufficient Mating Material -@cindex Draw if Insufficient Mating Material, Menu Item -When this option is set -XBoard will terminate games with a draw result -when so little material is left -that checkmate is not longer possible. -In normal Chess this applies to KK, KNK, KBK -and some positions with multiple Bishops all on the same -square shade. -Only works when @samp{Test Legality} is on. -@item Adjudicate Trivial Draws -@cindex Adjudicate Trivial Draws, Menu Item -When this option is set -XBoard will terminate games with a draw result -in positions that could only be won against an idiot. -In normal Chess this applies to KNNK, KRKR, KBKN, KNKN, -and KBKB with Bishops on different square shades. -KQKQ will also be adjudicated a draw (possibly unjustly so). -Only works when @samp{Test Legality} is on. -@item N-Move Rule -@cindex N-Move Rule, Menu Item -When this option is set to a value differnt from zero -XBoard will terminate games with a draw result -after the specified number of reversible moves -(i.e. without captures or pawn pushes) is made. -@item N-fold Repeats -@cindex N-fold Repeats, Menu Item -When this option is set to a value larger than 1, -XBoard will terminate games with a draw result when -the same position has occurred the specified number of times. -@item Draw after N Moves Total -@cindex Draw after N Moves Total, Menu Item -When this option is set to a value different from zero, -XBoard will terminate games with a draw result -after that many moves have been played. -Useful in automated engine-engine matches, -to prevent one game between stubborn engines will soak up -all your computer time. -@item Win / Loss Threshold -@cindex Win / Loss Threshold, Menu Item -When this option is set to a value different from zero, -XBoard will terminate games as a win when both engines -agree the score is above the specified value -(interpreted as centi-Pawn) -for three successive moves. -@item Negate Score of Engine #1 -@itemx Negate Score of Engine #2 -@cindex Negate Score of Engine, Menu Item -These options should be used with engines -that report scores from the white point of view, -rather than the side-to-move POV as XBoard would otherwise -assume when adjudicating games based on the engine score. -When the engine is installed with the extra option -@code{firstScoreIsAbs} true in the engine list -the option would be automatically set when the engine is -loaded throuhgh the Engine menu, -or with the @code{fe} or @code{se} command-line option. -@end table - -@section ICS Options -@cindex ICS Options, Menu Item -Pops up a menu dialog where options can be set that affect -playing against an Internet Chess Server. -@table @asis -@item Auto-Kibitz -@cindex Auto-Kibitz, Menu Item -Setting this option when playing with or aginst a chess program on an ICS -will cause the last line of thinking output of the engine before its move -to be sent to the ICS in a kibitz command. -In addition, any kibitz message received through the ICS from -an opponent chess program will be diverted to the engine-output window, -(and suppressed in the console), -where you can play through its PV by right-clicking it. -@item Auto-Comment -@cindex Auto-Comment, Menu Item -If this option is on, any remarks made on ICS while you are observing or -playing a game are recorded as a comment on the current move. This includes -remarks made with the ICS commands @kbd{say}, @kbd{tell}, @kbd{whisper}, -and @kbd{kibitz}. -Limitation: remarks that you type yourself are not recognized; -XBoard scans only the output from ICS, not the input you type to it. -@item Auto-Observe -@cindex Auto-Observe, Menu Item -If this option is on and you add a player to your @code{gnotify} -list on ICS, XBoard will automatically observe all of that -player's games, unless you are doing something else (such as -observing or playing a game of your own) when one starts. -The games are displayed -from the point of view of the player on your gnotify list; that is, his -pawns move from the bottom of the window towards the top. -Exceptions: If both players in a game are on your gnotify list, if -your ICS -@code{highlight} -variable is set to 0, or if the ICS you are using does not -properly support observing from Black's point of view, -you will see the game from White's point of view. -@item Auto-Raise Board -@cindex Auto Raise Board, Menu Item -If this option is on, whenever a new game begins, the chessboard window -is deiconized (if necessary) and raised to the top of the stack of windows. -@item Auto Save -@cindex Auto Save, Menu Item -If this option is true, at the end of every game XBoard prompts -you for a file name and appends a record of the game to the file -you specify. -Disabled if the @code{saveGameFile} command-line -option is set, as in that case all games are saved to the specified file. -@xref{Load and Save options}. -@item Background Observe while Playing -@cindex Background Observe while Playing, Menu Item -Setting this option will make XBoard suppress display of any boards -from observed games while you are playing. -Instead the last such board will be remembered, -and shown to you when you right-click the board. -This allows you to peek at your bughouse partner's game when you want, -without disturbing your own game too much. -@item Dual Board for Background-Observed Game -@cindex Dual Board for Background-Observed Game, Menu Item -Setting this option in combination with @samp{Background Observe} -will display boards of observed games while you are playing -on a second board next to that of your own game. -@item Get Move List -@cindex Get Move List, Menu Item -If this option is on, whenever XBoard -receives the first board of a new ICS game (or a different game from -the one it is currently displaying), it -retrieves the list of past moves from the ICS. -You can then review the moves with the @samp{Forward} and @samp{Backward} -commands -or save them with @samp{Save Game}. You might want to -turn off this option if you are observing several blitz games at once, -to keep from wasting time and network bandwidth fetching the move lists over -and over. -When you turn this option on from the menu, XBoard -immediately fetches the move list of the current game (if any). -@item Quiet Play -@cindex Quiet Play, Menu Item -If this option is on, XBoard will automatically issue an ICS -@kbd{set shout 0} -command whenever you start a game and a -@kbd{set shout 1} -command whenever you finish one. Thus, you will not be distracted -by shouts from other ICS users while playing. -@item Seek Graph -@cindex Seek Graph, Menu Item -Setting this option will cause XBoard to display an graph of -currently active seek ads when you left-click the board -while idle and logged on to an ICS. -@item Auto-Refresh Seek Graph -@cindex Auto-Refresh Seek Graph, Menu Item -In combination with the @samp{Seek Graph} option this -will cause automatic update of the seek graph while it is up. -This only works on FICS and ICC, -and requires a lot of bandwidth on a busy server. -@item Auto-InputBox PopUp -@cindex Auto-InputBox PopUp, Menu Item -Controls whether the ICS Input Box will pop up automatically when -you type a printable character to the board window in ICS mode. -@item Quit After Game -@cindex Quit After Game, Menu Item -Controls whether XBoard will automatically disconnect from the ICS -and close when the game currently in progress finishes. -@item Premove -@itemx Premove for White -@itemx Premove for Black -@itemx First White Move -@itemx First Black Move -@cindex Premove, Menu Item -@cindex Premove for White, Menu Item -@cindex Premove for Black, Menu Item -@cindex First White Move, Menu Item -@cindex First Black Move, Menu Item -If the @samp{Premove} option is on while playing a game on an ICS, -you can register your next planned move before it is your turn. -Move the piece with -the mouse in the ordinary way, and the starting and ending squares -will be highlighted with a special color (red by default). When it is -your turn, if your registered move is legal, XBoard will send it to -ICS immediately; if not, it will be ignored and you can make a -different move. If you change your mind about your premove, either -make a different move, or double-click on any piece to cancel the move -entirely. - -You can also enter premoves for the first white and black moves -of the game. -@item Alarm -@itemx Alarm Time -@cindex Alarm, Menu Item -@cindex Alarm Time, Menu Item -When this option is on, an alarm sound is played when your clock -counts down to the @samp{Alarm Time} in an ICS game. -(By default, the time is 5 seconds, but you can specify other values -with the Alarm Time spin control.) -For games with time controls that include an increment, the -alarm will sound each time the clock counts down to the icsAlarmTime. -By default, the alarm sound is the terminal bell, but on some systems -you can change it to a sound file using the soundIcsAlarm option; see -below. -@item Colorize Messages -@cindex Colorize Messages, Menu Item -Ticking this options causes various types of ICS messages do be -displayed with different foreground or background colors in the console. -The colors can be individually selected for each type, -through the accompanying text edits. -@item -icsMenu string -@cindex icsMenu, option -The string defines buttons for the @samp{ICS text menu}. -Each button definition consists of two semi-colon-terminated pieces of text, -the first giving the label to be written on the button, -the second the text that should be sent to the ICS when that button is pressed. -This second part (the 'message') can contain linefeeds, so that you can send -multiple ICS commands with one button. -Some message in the text, all starting with a $-sign, are treated special. -When the message contains '$input', it will not be sent directly to the ICS, -but will be put in the input field of the @samp{ICS Chat/Console}, -with the text cursor at the indicated place, so you can addsome text to -the message before sending it off. -If such a message starts with '$add' it will be placed behind any text -that is already present in the input field, otherwise this field will -be cleared first. -The word '$name' occurring in the message will be replaced by the word -that was clicked (through button 3) in the ICS Chat/Console. -There are two special messages: '$chat' will open a new chat with -the clicked word in the chat-partner field, -while '$copy' will copy the text that is currently-selected -in the ICS Console to the clipboard. -An example of a text menu as it might occur in your settings file -(where you could edit it): - -@example --icsMenu @{copy;$copy; -list players;who; -list games;games; -finger (player);finger $name; -bullet (player);match $name 1 1 r; -blitz (player);match $name 5 1 r; -rapid (player);match $name 30 0 r; -open chat (player);$chat; -tell (player);tell $name $input; -ask pieces;ptell Please give me a $input; -P;$add Pawn $input; -N;$add Knight $input; -B;$add Bishop $input; -R;$add Rook $input; -Q;$add Queen $input; -@} -@end example -@end table - -@section Tournament Options -@cindex Tournament Options, Menu Item -Summons a dialog where you can set options important for playing automatic -matches between two or more chess programs -(e.g. by using the @samp{Machine Match} menu item in the @samp{Mode} menu). -@table @asis -@item Tournament file -@cindex Tournament file, Menu item -To run a tournament, XBoard needs a file to record its progress, -so it can resume the tourney when it is interrupted. -When you want to conduct anything more complex than a simple -two-player match with the currently loaded engines, -(i.e. when you select a list of participants), -you must not leave this field blank. -When you enter the name of an existing tournament file, -XBoard will ignore all other input specified in the dialog, -and will take the corresponding info from that tournament file. -This resumes an interrupted tournament, or adds another XBoard -agent playing games for it to those that are already doing so. -Specifying a not-yet-existing file will cause XBoard to create it, -according to the tournament parameters specified in the rest of the dialog, -before it starts the tournament on ‘OK’. -Provided that you specify participants; -without participants no tournament file will be made, but other entered values -(e.g. for the file with opening positions) will take effect. -Default: configured by the @code{defaultTourneyName} option. -@item Sync after round -@itemx Sync after cycle -@cindex Sync after round, Menu Item -@cindex Sync after cycle, Menu Item -The sync options, when on, will cause WinBoard to refrain from starting games -of the next round or cycle before all games of the previous round or cycle are finished. -This guarantees correct ordering in the games file, -even when multiple XBoard instances are concurrently playing games for the same tourney. -Default: sync after cycle, but not after round. -@item Select Engine -@itemx Tourney participants -@cindex Select Engine, Menu Item -@cindex Tourney participants, Menu Item -From the Select Engine listbox you can pick an engine from your list -of engines registered in the settings file, to be added to the tournament. -The engines selected so far will be listed in the ‘Tourney participants’ memo. -The latter is a normal text edit, so you can use normal text-editing functions -to delete engines you selected accidentally, or change their order. -Typing names here yourself is not recommended, because names that do not exactly match -one of the names from the selection listbox will lead to undefined behavior. -@item Tourney type -@cindex Tourney type, Menu Item -Here you can specify the type of tournament you want. -XBoard’s intrinsic tournament manager support round-robins (type = 0), -where each participant plays every other participant, and (multi-)gauntlets, -where one (or a few) so-called ‘gauntlet engines’ play an independent set of opponents. -In the latter case, you specify the number of gauntlet engines. -E.g. if you specified 10 engines, and tourney type = 2, -the first 2 engines each play the remaining 8. -A value of -1 instructs XBoard to play Swiss; for this to work an external -pairing engine must be specified through the @code{pairingEngine} option. -Each Swiss round will be considered a tourney cycle in that case. -Default:0 -@item Number of tourney cycles -@itemx Default number of Games -@cindex Number of tourney cycles, Menu Item -@cindex Default number of Games, Menu Item -You can specify tourneys where every two opponents play each other multiple times. -Such multiple games can be played in a row, -as specified by the ‘number of games per pairing’, -or by repeating the entire tournament schedule a number of times -(specified by the ‘number of tourney cycles’). -The total number of times two engines meet will be the product of these two. -Default is 1 cycle; -the number of games per pairing is the same as the default number of match games, -stored in your settings file through the @code{defaultMatchGames} option. -@item Save Tourney Games -@cindex Save Tourney Games, Menu Item -File where the tournament games are saved -(duplicate of the item in the @samp{Save Game Options}). -@item Game File with Opening Lines -@itemx File with Start Positions -@itemx Game Number -@itemx Position Number -@itemx Rewind Index after -@cindex Game File with Opening Lines, Menu Item -@cindex File with Start Positions, Menu Item -@cindex Game Number, Menu Item -@cindex Position Number, Menu Item -@cindex Rewind Index after, Menu Item -These items optionally specify the file with move sequences or board positions the tourney -games should start from. -The corresponding numbers specify the number of the game or position in the file. -Here a value -1 means automatic stepping through all games on the file, --2 automatic stepping every two games. -The Rewind-Index parameter causes a stepping index to reset to one after reaching -a specified value. -A setting of -2 for the game number will also be effective in a tournament without -specifying a game file, but playing from the GUI book instead. -In this case the first (odd) games will randomly select from the book, -but the second (even) games will select the same moves from the book as the previous game. -(Note this leads to the same opening only if both engines use the GUI book!) -Default: No game or position file will be used. The default index if such a file is used is 1. -@item Disable own engine books be default -@cindex Disable own engine books be default, Menu Item -Setting this option reverses the default situation for use of the GUI opening book -in tournaments from what it normally is, namely not using it. -So unless the engine is installed with an option to explicitly specify it should -not use the GUI book (i.e. @code{-firstHasOwnBookUCI true}), -it will be made to use the GUI book. -@item Replace Engine -@itemx Upgrade Engine -@cindex Replace Engine, Menu Item -@cindex Upgrade Engine, Menu Item -With these two buttons you can alter the participants of an already running tournament. -After opening the Match Options dialog on an XBoard that is playing for the tourney, -you will see all the tourney parameters in the dialog fields. -You can then replace the name of one engine by that of another -by editing the @samp{participants} field. -(But preserve the order of the others!) -Pressing the button after that will cause the substitution. -With the @samp{Upgrade Engine} button the substitution will only affect future games. -With @samp{Replace Engine} all games the substituted engine has already played will -be invalidated, and they will be replayed with the substitute engine. -In this latter case the engine must not be playing when you do this, -but otherwise there is no need to pause the tournament play -for making a substitution. -@item Clone Tourney -@cindex CloneTourney, Menu Item -Pressing this button after you have specified an existing tournament file -will copy the contents of the latter to the dialog, -and then puts the originally proposed name for the tourney file back. -You can then run a tourney with the same parameters -(possibly after changing the proposed name of the tourney file for the new tourney) -by pressing 'OK'. -@item Continue Later -@cindex Continue Later, Menu Item -Pressing the @samp{Continue Later} button confirms the current value of all -items in the dialog and closes it, -but will not automatically start the tournament. -This allows you to return to the dialog later without losing the settings you -already entered, to adjust paramenters through other menu dialogs. -(The @samp{Common Engine Setting}, @samp{Time Control} and @samp{General Options} -dialogs can be accessed without closing the @samp{Tournament Options} dialog -through the respective buttons at the bottom of the latter.) -@end table - -@section Load Game Options -@cindex Load Game Options, Menu Item -Summons a dialog where you can set options that control loading of games. -@table @asis -@item Auto-Display Tags -@cindex Auto-Display Tags, Menu Item -Setting this option causes a window to pop up on loading a game, -displaying the PGN Tags for that game. -@item Auto-Display Comment -@cindex Auto-Display Comment, Menu Item -Setting this option causes a window to pop up whenever there -is a comment to (or variation on) the currently displayed move. -@item Auto-Play speed of loaded games -@cindex Auto-Play speed, Menu Item -This option sets the number of seconds between moves -when a newly loaded game is auto-playing. -A decimal fraction on the number is understood. -Setting it to -1 disables auto-play, staying in the start position -of the game after the loading completes. -Setting it to 0 will instantly move to the final position of the game. -The @samp{Auto-Play speed} is also used to determine the -analysis time for each move during @samp{Analyze Game}. -Note that auto-playing (including game analysis) can be stopped at any -time through the @samp{P} button above the board. -@item options to use in game-viewer mode -@cindex Game-Viewer options, Menu Item -Specifies the options automatically set when XBoard is invoked -with the option @code{-viewer} on its command line, -as will happen when it is started in response to clicking a PGN game file. -The default setting would start XBoard without engine -(due to the @code{-ncp} option), -but if you want it to automatically start with your favorite engine, -and automatically start analyzing, you could include the necessary -options for that here (e.g. @code{-fe -initialMode analysis}). -@item Thresholds for position filtering in game list -@cindex Thresholds for game selection, Menu Item -The following options can be set to limit the display of games -in the @samp{Game List} window to a sub-set, -meeting the specified criteria. -@item Elo of strongest player at least -@item Elo of weakest player at least -@cindex Elo limits, Menu Item -Games with an Elo tag specifying a lower rating for the mentioned player -will not be diplayed in the @samp{Game List}. -@item No games before year -@cindex Date limit, Menu item -Games with a Date tag before the specified year -will not be diplayed in the @samp{Game List}. -@item Final nr of pieces -@cindex Final number of pieces, Menu Item -A single number or a range (like 8-10) can be entered here, -and will cause only games where the number of men in the final -position is in the given range -will be diplayed in the @samp{Game List}. -@item Minimum nr consecutive positions -@cindex Consecutive positions, Menu Item -Specifies for how many consecutive positions the more fuzzy -position-matching criteria have to be satisfied -in order to count as a match. -@item Search mode -@itemx find position -@cindex Search mode, Menu Item -@cindex find position, Menu Item -XBoard can select games for display in the @samp{Game List} -based on whether (in addition to the conditions on the PGN tags) -they contain a position that matches the -position currently displayed on the board, -by pressing the @samp{find position} -or @samp{narrow} buttons in the @samp{Game List} window. -The @samp{Search mode} setting determines what counts as match. -You can search for an exact match, -a position that has all shown material in the same place, -but might contain additional material, -a position that has all Pawns in the same place, -but can have the shown material anywhere, -a position that can have all shown material anywhere, -or a position that has material between certain limits anywhere. -For the latter you have to place the material that must minimally be present -in the four lowest ranks of the board, -and optional additional material in the four highest ranks of the board. -You can request the optional material to be balanced, -i.e. equal for white and black. -@item narrow -@cindex narrow, Menu Item -The @samp{narrow} button is similar in fuction to the @samp{find position} button, -but only searches in the already selected games, -rather than the complete game file, -and can thus be used to refine a search based on multiple criteria. -@item Also match reversed colors -@itemx Also match left-right flipped position -@cindex Match reversed colors, Menu Item -@cindex Match left-right flipped position, Menu Item -When looking for matching positions rather than by material, -these settings determine whether mirror images -(in case of a vertical flip in combination with color reversal) -will be also considered a match. -The left-right flipping is only useful after all castling rights -have expired (or in Xiangqi). -@end table - -@section Save Game Options -@cindex Save Game Options, Menu Item -Summons a dialog where you can specify whether XBoard should -automatically save files of games when they finish, -and where and how to do that. -@table @asis -@item Auto-Save Games -@cindex Auto-Save Games, Menu Item -When set XBoard will automatically save games on a file as they finish. -(Not when you abort them by pressing @samp{New Game}, though!) -It will either prompt you for a filename, -or use the file specified by the @code{saveGameFile} option. -@item Own Games Only -@cindex Own Games Only, Menu Item -Setting this option will exclude games by others observed on an -Internet Chess Server from automatic saving. -@item Save Games on File -@cindex Save Games on File, Menu Item -Name of the file on which games should be saved automatically. -Games are always appended to the file, -and will never overwrite anything. -@item Save Final Position on File -@cindex Save Final Position on File, Menu Item -When a name is defined, the final position of each game -is appended to the mentioned file. -@item PGN Event Header -@cindex PGN Event Header, Menu Item -Specifies the name of the event used in the PGN event tag -of new games that you create. -@item Old Save Style -@cindex Old Save Style, Menu Item -Saves games in an obsolete and now long forgotten format, -rather than as PGN. Never use this for orthodox Chess! -@item Include Number Tag in tourney PGN -@cindex Include Number Tag in tourney PGN, Menu Item -When on this option will cause the non-standard 'Number' tag -to be written in any game saved in PGN format. -It will contain the unique number of the game in the tourney. -(As opposed to the 'Round' tag, which can be shared by many games.) -@item Save Score/Depth Info in PGN -@cindex Save Score/Depth in PGN, Menu Item -When on this option will cause the score and depth at which it was -calculated by an engine, and (when available) thinking time -to be saved with the move as a comment to the move, -in the format @{score/depth time@}. -Here 'score'is in pawn units from the point of view of the player -that made the move, with two digits behind the decimal Pawn. -'Time' is in seconds, or min:sec. -@item Save Out-of-Book Info in PGN -@cindex Save Out-of-Book Info in PGN, Menu Item -When on this option causes the score of the first move -the engine made after coming out of book in an 'Annotator' PGN tag. -@end table - -@section Game List -@cindex Game List Tags, Menu Item -Pops up a dialog where you can select the PGN tags that should appear -on the lines in the @samp{Game List}, and their order. - -@section Sound Options -@cindex Sound Options, Menu Item -Summons a dialog where you can specify the sounds that should accompany -various events that can occur in XBoard. -Most events are only relevant to ICS play, -but the move sound is an important exception. -For each event listed in the dialog, -you can select a standard sound from a menu. -@table @asis -@item Sound Program -@cindex Sound Program, Menu Item -Specifies the command XBoard should invoke to play sounds. -The specified text will be suffixed by the name of the sound file, -and then run as a command. -@item Sounds Directory -@cindex Sounds Directory, Menu Item -Specifies the directory where XBoard will look for files with -the names of the standard sounds. -@item User WAV File -@cindex User WAV File, Menu Item -When we type a filename here, it can be assigned to the events -by selecting @samp{Above WAV File} from the drop downs. -@item Try-Out Sound -@itemx Play -@cindex Try-Out Sound, Menu Item -The 'event' triggering the Try-Out sound is pressing -of the @samp{Play} button behind it. -This allows you to judge the sounds. -@end table - -@section Save Settings Now -@cindex Save Settings Now, Menu Item -Selecting this menu item causes the current XBoard settings to be -written to the settings file, (.xboardrc in your home directory), -so they will also apply in future sessions. -Note that some settings are 'volatile', and are not saved, -because XBoard considers it too unlikely that you want those to apply -next time. -In particular this applies to the Chess program, and all options -giving information on those Chess programs (such as their directory, -if they have their own opening book, if they are UCI or native XBoard), -or the variant you are playing. -Such options would still be understood when they appear in the settings -file in case they were put there with the aid of a text editor, but they -would disappear from the file as soon as you save the settings. - -Note that XBoard no longer pays attention to options values specified -in the .Xresources file. -(Specifying key bindings there will still work, though.) -To alter the default of volatile options, you can use the following method: -Rename your ~/.xboardrc settings file (to ~/.yboardrc, say), and create -a new file ~/.xboardrc, which only contains the options - -@example --settingsFile ~/.yboardrc --saveSettingsFile ~/.yboardrc -@end example - -@noindent -This will cause your settings to be saved on ~/.yboardrc in the future, -so that ~/.xboardrc is no longer overwritten. -You can then safely specify volatile options in ~/.xboardrc, either -before or after the settingsFile options. -Note that when you specify persistent options after the settingsFile options -in this ~/.xboardrc, you will essentially turn them into volatile options -with the specified value as default, because that value will overrule -the value loaded from the settings file (being read later). - -@section Save Settings on Exit -@cindex Save Settings on Exit, Menu Item -Setting this option has no immediate effect, but causes the settings -to be saved when you quit XBoard. What happens then is otherwise -identical to what happens when you use select "Save Settings Now", -see there. - -@node Help Menu -@section Help Menu -@cindex Menu, Help -@cindex Help Menu -@table @asis -@item Info XBoard -@cindex Info XBoard, Menu Item -Displays the XBoard documentation in info format. For this feature to -work, you must have the GNU info program installed on your system, and -the file @file{xboard.info} must either be present in the current -working directory, or have been installed by the @samp{make install} -command when you built XBoard. -@item Man XBoard -@cindex Man XBoard, Menu Item -Displays the XBoard documentation in man page format. -The @kbd{F1} key is a keyboard equivalent. For this -feature to work, the file @file{xboard.6} must have been installed by -the @samp{make install} command when you built XBoard, and the -directory it was placed in must be on the search path for your -system's @samp{man} command. -@item About XBoard -@cindex About XBoard, Menu Item -Shows the current XBoard version number. -@end table - -@node Keys -@section Other Shortcut Keys -@cindex Keys -@cindex Shortcut keys -@table @asis -@item Show Last Move -@cindex Show Last Move, Shortcut Key -By hitting @kbd{Enter} the last move will be re-animated. -@item Load Next Game -@cindex Load Next Game, Menu Item -Loads the next game from the last game record file you loaded. -The @kbd{Alt+PgDn} key triggers this action. -@item Load Previous Game -@cindex Load Previous Game, Menu Item -Loads the previous game from the last game record file you -loaded. The @kbd{Alt+PgUp} key triggers this action. -Not available if the last game was loaded from a pipe. -@item Reload Same Game -@cindex Reload Same Game, Menu Item -Reloads the last game you loaded. -Not available if the last game was loaded from a pipe. -Currently no keystroke is assigned to this ReloadGameProc. -@item Reload Same Position -@cindex Reload Same Position, Menu Item -Reloads the last position you loaded. -Not available if the last position was loaded from a pipe. -Currently no keystroke is assigned to this ReloadPositionProc. -@end table - -In the Xaw build of XBoard you can add or remove shortcut keys -using the X resources @code{paneA.translations}. -Here is an example of what could go into your -@file{.Xdefaults} file: - -@example -XBoard*paneA.translations: \ - Shift?: MenuItem(Help.About) \n\ - Ctrly: MenuItem(Action.Accept) \n\ - Ctrln: MenuItem(Action.Decline) \n\ - Ctrli: MenuItem(Nothing) -@end example -@noindent -So the key should always be bound to the action 'MenuItem', -with the (hierarchical) name of the menu item as argument. -There are a few actions available for which no menu item exists: -Binding a key to @code{Nothing} makes it do nothing, thus removing -it as a shortcut key. Other such functions that can be bound to keys -are: - -@example -AboutGame, DebugProc (switches the -debug option on or off), -LoadNextGame, LoadPrevGame, ReloadGame, ReloadPosition. -@end example - -@node Options -@chapter Options -@cindex Options -@cindex Options - -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 editing the settings file -(usually ~/.xboardrc) to alter the value of the setting that was -saved there. Some 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. - -Most of the options have both a long name and a short name. To turn a -boolean option on or off from the command line, either give its long -name followed by the value true or false -(@samp{-longOptionName true}), or give just the short name to turn the -option on (@samp{-opt}), or the short name preceded by @samp{x} to -turn the option off (@samp{-xopt}). For options that take strings or -numbers as values, you can use the long or short option names -interchangeably. - -@menu -* Chess engine options:: Controlling the chess engine. -* UCI + WB Engine Settings:: Setting some very common engine parameters -* Tournament options:: Running tournaments and matches between engines. -* ICS options:: Connecting to and using ICS. -* Load and Save options:: Input/output options. -* User interface options:: Look and feel options. -* Adjudication Options:: Control adjudication of engine-engine games. -* Install options:: Maintaining and extending the XBoard install. -* Other options:: Miscellaneous. -@end menu - -@node Chess engine options -@section Chess Engine Options -@cindex options, Chess engine -@cindex Chess engine options -@table @asis -@item -tc or -timeControl minutes[:seconds] -@cindex tc, option -@cindex timeControl, option -Each player begins with his clock set to the @code{timeControl} period. -Default: 5 minutes. -The additional options @code{movesPerSession} and @code{timeIncrement} -are mutually exclusive. -@item -mps or -movesPerSession moves -@cindex mps, option -@cindex movesPerSession, option -When both players have made @code{movesPerSession} moves, a -new @code{timeControl} period is added to both clocks. Default: 40 moves. -@item -inc or -timeIncrement seconds -@cindex inc, option -@cindex timeIncrement, option -If this option is specified, @code{movesPerSession} is ignored. -Instead, after each player's move, @code{timeIncrement} seconds are -added to his clock. -Use @samp{-inc 0} if you want to require the entire -game to be played in one @code{timeControl} period, with no increment. -Default: -1, which specifies @code{movesPerSession} mode. -@item -clock/-xclock or -clockMode true/false -@cindex clock, option -@cindex clockMode, option -Determines whether or not to display the chess clocks. If clockMode is -false, the clocks are not shown, but the side that is to play next -is still highlighted. Also, unless @code{searchTime} -is set, the chess engine still keeps track of the clock time and uses it to -determine how fast to make its moves. -@item -st or -searchTime minutes[:seconds] -@cindex st, option -@cindex searchTime, option -Tells the chess engine to spend at most the given amount of time -searching for each of its moves. Without this option, the chess engine -chooses its search time based on the number of moves and amount -of time remaining until the next time control. -Setting this option also sets clockMode to false. -@item -depth or -searchDepth number -@cindex sd, option -@cindex searchDepth, option -Tells the chess engine to look ahead at most the given number of moves -when searching for a move to make. Without this option, the chess -engine chooses its search depth based on the number of moves and -amount of time remaining until the next time control. With the option, -the engine will cut off its search early if it reaches the specified depth. -@item -firstNPS number -@itemx -secondNPS number -@cindex firstNPS, option -@cindex secondNPS, option -Tells the chess engine to use an internal time standard based on its node count, -rather then wall-clock time, to make its timing decisions. -The time in virtual seconds should be obtained by dividing the node count -through the given number, like the number was a rate in nodes per second. -Xboard will manage the clocks in accordance with this, relying on the number -of nodes reported by the engine in its thinking output. If the given number equals zero, -it can obviously not be used to convert nodes to seconds, and the time reported -by the engine is used to decrement the XBoard clock in stead. The engine is supposed to -report in CPU time it uses, rather than wall-clock time, in this mode. This option -can provide fairer conditions for engine-engine matches on heavily loaded machines, -or with very fast games (where the wall clock is too inaccurate). -@code{showThinking} must be on for this option to work. Default: -1 (off). -Not many engines might support this yet! -@item -firstTimeOdds factor -@itemx -secondTimeOdds factor -@cindex firstTimeOdds, option -@cindex secondTimeOdds, option -Reduces the time given to the mentioned engine by the given factor. -If pondering is off, the effect is indistinguishable from what would happen -if the engine was running on an n-times slower machine. Default: 1. -@item -timeOddsMode mode -@cindex timeOddsMode, option -This option determines how the case is handled where both engines have a time-odds handicap. -If mode=1, the engine that gets the most time will always get the nominal time, -as specified by the time-control options, and its opponent's time is renormalized accordingly. -If mode=0, both play with reduced time. Default: 0. -@item -hideThinkingFromHuman true/false -Controls the Hide Thinking option. @xref{Options Menu}. Default: true. -(Replaces the Show-Thinking option of older xboard versions.) -@item -thinking/-xthinking or -showThinking true/false -@cindex thinking, option -@cindex showThinking, option -Forces the engine to send thinking output to xboard. -Used to be the only way to control if thinking output was displayed -in older xboard versions, -but as the thinking output in xboard 4.3 is also used for several other -purposes (adjudication, storing in PGN file) the display of it is now controlled -by the new option Hide Thinking. @xref{Options Menu}. Default: false. -(But if xboard needs the thinking output for some purpose, -it makes the engine send it despite the setting of this option.) -@item -ponder/-xponder or -ponderNextMove true/false -@cindex ponder, option -@cindex ponderNextMove, option -Sets the Ponder Next Move menu option. @xref{Options Menu}. Default: true. -@item -smpCores number -Specifies the maximum number of CPUs an SMP engine is allowed to use. -Only works for engines that support the XBoard/WinBoard-protocol cores feature. -@item -mg or -matchGames n -@cindex mg, option -@cindex matchGames, option -Automatically runs an n-game match between two chess engines, -with alternating colors. -If the @code{loadGameFile} or @code{loadPositionFile} option is set, -XBoard -starts each game with the given opening moves or the given position; -otherwise, the games start with the standard initial chess position. -If the @code{saveGameFile} option is set, a move record for the -match is appended to the specified file. If the @code{savePositionFile} -option is set, the final position reached in each game of the match is appended -to the specified file. When the match is over, XBoard -displays the match score and exits. Default: 0 (do not run a match). -@item -mm/-xmm or -matchMode true/false -@cindex mm, option -@cindex matchMode, option -Setting @code{matchMode} to true is equivalent to setting -@code{matchGames} to 1. -@item -sameColorGames n -@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, -over which it takes precedence if both are specified. (See there.) -Default: 0 (do not run a match). -@item -epd -@cindex epd, option -This option puts XBoard in a special mode for solving EPD test-suites, -for the entire duration of the session. -In this mode games are aborted after a single move, -and that move will be compared with the best-move or avoid-move -from the EPD position description from which the 'game' was started. -Playing a best move counts as a win, playing an avoid move as a loss, -and playing any other move counts as a draw. -This option should be used in combination with match mode, -and an EPD file of starting positions with an auto-incrementing index. -Color assignment will be such that the first engine plays all moves, -and the second engine will be never involved. -The results for individual positions, -as well as the time used for solving them, -will be reported in the lower pane of the Engine Output window. -@item -fcp or -firstChessProgram program -@itemx -scp or -secondChessProgram program -@cindex fcp, option -@cindex firstChessProgram, option -@cindex scp, option -@cindex secondChessProgram, option -Name of first and second chess engine, respectively. -A second chess engine is started only in Two Machines (match) mode, -or in Analyze mode with two engines. -The second engine is by default the same as the first. -Default for the first engine: @file{fairymax}. -@item -fe or -firstEngine nickname -@itemx -se or -secondEngine nickname -@cindex se, option -@cindex secondEngine, option -@cindex fe, option -@cindex firstEngine, option -This is an alternative to the @code{fcp} and @code{scp} options -for specifying the first and second engine, -for engines that were already registered (using the @samp{Load Engine} dialog) -in XBoard's settings file. -It will not only retrieve the real name of the engine, -but also all options configured with it. -(E.g. if it is UCI, whether it should use book.) -@item -fb/-xfb or -firstPlaysBlack true/false -@cindex fb, option -@cindex firstPlaysBlack, option -In games between two chess engines, firstChessProgram normally plays -white. If this option is true, firstChessProgram plays black. In a -multi-game match, this option affects the colors only for the first -game; they still alternate in subsequent games. -@item -fh or -firstHost host -@itemx -sh or -secondHost host -@cindex fh, option -@cindex firstHost, option -@cindex sh, option -@cindex secondHost, option -Hosts on which the chess engines are to run. The default for -each is @file{localhost}. If you specify another host, XBoard -uses @file{rsh} to run the chess engine there. (You can substitute a -different remote shell program for rsh using the @code{remoteShell} -option described below.) -@item -fd or -firstDirectory dir -@itemx -sd or -secondDirectory dir -@cindex fd, option -@cindex firstDirectory, option -@cindex sd, option -@cindex secondDirectory, option -Working directories in which the chess engines are to be run. -The default is "", which means to run the chess engine -in the same working directory as XBoard -itself. (See the CHESSDIR environment variable.) -This option is effective only when the chess engine is being run -on the local host; it does not work if the engine is run remotely -using the -fh or -sh option. -@item -initString string or -firstInitString -@itemx -secondInitString string -@cindex initString, option -@cindex firstInitString, option -@cindex secondInitString, option -The string that is sent to initialize each chess engine for a new game. -Default: - -@example -new -random -@end example -@noindent -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. -Using the character sequence @samp{\n} in the string should work too, though. - -If you change this option, don't remove the @samp{new} -command; it is required by all chess engines to -start a new game. - -You can remove the @samp{random} command if you like; including it -causes GNU Chess 4 to randomize its move selection slightly so that it -doesn't play the same moves in every game. Even without -@samp{random}, GNU Chess 4 randomizes its choice of moves from its -opening book. Many other chess engines ignore this command entirely -and always (or never) randomize. - -You can also try adding other commands to the initString; see the -documentation of the chess engine you are using for details. -@item -firstComputerString string -@itemx -secondComputerString string -@cindex firstComputerString, option -@cindex secondComputerString, option -The string that is sent to the chess engine if its opponent is another -computer chess engine. The default is @samp{computer\n}. Probably the -only useful alternative is the empty string (@samp{}), which keeps the -engine from knowing that it is playing another computer. -@item -reuse/-xreuse or -reuseFirst true/false -@itemx -reuse2/-xreuse2 or -reuseSecond true/false -@cindex reuse, option -@cindex reuseFirst, option -@cindex reuse2, option -@cindex reuseSecond, option -If the option is false, -XBoard kills off the chess engine after every game and starts -it again for the next game. -If the option is true (the default), -XBoard starts the chess engine only once -and uses it repeatedly to play multiple games. -Some old chess engines may not work properly when -reuse is turned on, but otherwise games will start faster if it is left on. -@item -firstProtocolVersion version-number -@itemx -secondProtocolVersion version-number -@cindex firstProtocolVersion, option -@cindex secondProtocolVersion, option -This option specifies which version of the chess engine communication -protocol to use. By default, version-number is 2. In version 1, the -"protover" command is not sent to the engine; since version 1 is a -subset of version 2, nothing else changes. Other values for -version-number are not supported. -@item -firstScoreAbs true/false -@itemx -secondScoreAbs true/false -@cindex firstScoreAbs, option -@cindex secondScoreAbs, option -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 XBoard (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 an option announced by the engine at startup through the feature commands of the XBoard/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 XBoard would normally omit them -(string = "- -"), or to add variant-specific fields that are not yet supported by XBoard -(e.g. to indicate the number of checks in 3check). -@item -shuffleOpenings -@cindex shuffleOpenings, option -Forces shuffling of the opening setup in variants that normally have a fixed initial position. -Shufflings are symmetric for black and white, and exempt King and Rooks in variants -with normal castling. -Remains in force until a new variant is selected. -@item -fischerCastling -@cindex fischerCastling, option -Specifies Fischer castling (as in Chess960) should be enabled in variants -that normally would not have it. -Remains in force until a new variant is selected. -@end table - -@node UCI + WB Engine Settings -@section UCI + WB Engine Settings -@cindex Engine Settings -@cindex Settings, Engine -@table @asis -@item -fUCI or -firstIsUCI true/false -@itemx -sUCI or -secondIsUCI true/false -@cindex fUCI, option -@cindex sUCI, option -@cindex firstIsUCI, option -@cindex secondIsUCI, option -Indicates if the mentioned engine executable file is a UCI engine, -and should be run with the aid of the Polyglot adapter rather than directly. -Xboard will then pass the other UCI options and engine name to Polyglot -on its command line, according to the option @code{adapterCommand}. -@item -fUCCI -@itemx -sUCCI -@itemx -fUSI -@itemx -sUSI -@cindex fUCCI, option -@cindex sUCCI, option -@cindex fUSI, option -@cindex sUSI, option -Options similar to @code{fUCI} and @code{sUCI}, except that they -use the indicated engine with the protocol adapter specified in -the @samp{uxiAdapter} option. -This can then be configured for running a UCCI or USI adapter, -as the need arises. -@item -adapterCommand string -@cindex adapterCommand, option -The string contains the command that should be issued by XBoard -to start an engine that is accompanied by the @code{fUCI} option. -Any identifier following a percent sign in the command (e.g. %fcp) -will be considered the name of an XBoard option, and be replaced -by the value of that option at the time the engine is started. -For starting the second engine, any leading "f" or "first" in -the option name will first be replaced by "s" or "second", -before finding its value. -Default: 'polyglot -noini -ec "%fcp" -ed "%fd"' -@item -uxiAdapter string -@cindex uxiAdapter, option -Similar to @code{adapterCommand}, but used for engines accompanied -by the @code{fUCCI} or @code{fUSI} option, so you can configure -XBoard to be ready to handle more than one flavor of non-native protocols. -Default: "" -@item -polyglotDir filename -@cindex polyglotDir, option -Gives the name of the directory in which the Polyglot adapter for UCI engines resides. -Default: "". -@item -usePolyglotBook true/false -@cindex usePolyglotBook, option -Specifies if the Polyglot book should be used as GUI book. -@item -polyglotBook filename -@cindex polyglotBook, option -Gives the filename of the opening book. -The book is only used when the @code{usePolyglotBook} option is set to true, -and the option @code{firstHasOwnBookUCI} or @code{secondHasOwnBookUCI} -applying to the engine 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 -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: depends on setting of the option @code{discourageOwnBooks}. -@item -discourageOwnBooks true/false -@cindex discourageOwnBooks, option -When set, newly loaded engines will be assumed to use the GUI book, -unless they explicitly specify differently. -Otherwise they will be assumed to not use the GUI book, -unless the specify differently (e.g. with @code{firstXBook}). -Default: false. -@item -bookDepth n -@cindex bookDepth, option -Limits the use of the GUI book to the first n moves of each side. -Default: 12. -@item -bookVariation n -@cindex bookVariation, option -A value n from 0 to 100 tunes the choice of moves from the GUI books -from totally random to best-only. Default: 50 -@item -mcBookMode -@cindex mcBookMode, option -When this volatile option is specified, the probing algorithm of the -GUI book is altered to always select the move that is most under-represented -based on its performance. -When all moves are played in approximately the right proportion, -a book miss will be reported, to give the engine opportunity to -explore a new move. -In addition score of the moves will be kept track of during the session -in a book buffer. -By playing an match in this mode, a book will be built from scratch. -The only output are the saved games, which can be converted to an -actual book later, with the @samp{Save Games as Book} command. -The latter command can also be used to pre-fill the book buffer -before adding new games based on the probing algorithm. -@item -fn string or -firstPgnName string -@itemx -sn string or -secondPgnName string -@cindex firstPgnName, option -@cindex secondPgnName, option -@cindex fn, option -@cindex sn, option -Indicates the name that should be used for the engine in PGN tags of -engine-engine games. -Intended to allow you to install versions of the same engine with different settings, -and still distinguish them. -Default: "". -@item -defaultHashSize n -@cindex defaultHashSize, option -Sets the size of the hash table to n MegaBytes. Together with the EGTB cache size -this number is also used to calculate the memory setting of XBoard/WinBoard engines, -for those that support the memory feature of the XBoard/WinBoard protocol. Default: 64. -@item -defaultCacheSizeEGTB n -@cindex defaultCacheSizeEGTB, option -Sets the size of the EGTB cache to n MegaBytes. Together with the hash-table size -this number is also used to calculate the memory setting of XBoard/WinBoard engines, -for those that support the memory feature of the XBoard/WinBoard protocol. Default: 4. -@item -defaultPathEGTB filename -@cindex defaultPathEGTB, option -Gives the name of the directory where the end-game tablebases are installed, for UCI engines. -Default: "/usr/local/share/egtb". -@item -egtFormats string -@cindex egtFormats, option -Specifies which end-game tables are installed on the computer, and where. -The argument is a comma-separated list of format specifications, -each specification consisting of a format name, a colon, and a directory path name, -e.g. "nalimov:/usr/local/share/egtb". -If the name part matches that of a format that the engine requests through a feature command, -xboard will relay the path name for this format to the engine through an egtpath command. -One egtpath command for each matching format will be sent. -Popular formats are "nalimov" and "gaviota" DTM tablebases, -syzygy DTZ tablebases and "scorpio" bitbases. -Default: "". -@item -firstChessProgramNames=@{names@} -@cindex firstChessProgramNames, option -This option lets you customize the listbox with chess-engine names -that appears in the @samp{Load Engine} and @samp{Tournament Options} dialog. -It consists of a list of strings, one per line. -When an engine is loaded, the corresponding line is prefixed with "-fcp ", -and processed like it appeared on the command line. -That means that apart from the engine command, -it can contain any number of XBoard options you want to use with this engine. -(Commonly used options here are -fd, -firstXBook, -fUCI, -variant.) - -The value of this option is gradually built as you load new engines -through the @samp{Load Engine} menu dialog, with @samp{Add to list} ticked. -To change it in other ways, (e.g. deleting engines), -use the menu item @samp{Edit Engine List} in the @samp{Engine} menu. -@end table - -@node Tournament options -@section Tournament options -@cindex Tournament Options -@cindex Options, Tournament -@table @asis -@item -defaultMatchGames n -@cindex defaultMatchGames, option -Sets the number of games that will be used for a match between two engines -started from the menu to n. Also used as games per pairing in other tournament -formats. Default: 10. -@item -matchPause n -@cindex matchPause, option -Specifies the duration of the pause between two games of a match or tournament -between engines as n milliseconds. -Especially engines that do not support ping need this option, -to prevent that the move they are thinking on when an opponent unexpectedly -resigns will be counted for the next game, (leading to illegal moves there). -Default: 10000. -@item -tf filename or -tourneyFile filename -@cindex tf, option -@cindex tourneyFile, option -Specifies the name of the tournament file used in match mode -to conduct a multi-player tournament. -This file is a special settings file, -which stores the description of the tournament (including progress info), -through normal options (e.g. for time control, load and save files), -and through some special-purpose options listed below. -@item -tt number or -tourneyType number -@cindex tt, option -@cindex tourneyType, option -Specifies the type of tourney: 0 = round-robin, -N>0 = (multi-)gauntlet with N gauntlet engines, --1 = Swiss through external pairing engine. -Volatile option, but stored in tourney file. -@item -cy number or -tourneyCycles number -@cindex cy, option -@cindex tourneyCycles, option -Specifies the number of cycles in a tourney. -Volatile option, but stored in tourney file. -@item -participants list -@cindex participants, option -The list is a multi-line text string that specifies engines -occurring in the @code{firstChesProgramNames} list -in the settings file by their (implied or explicitly given) nicknames, -one engine per line. -The mentioned engines will play in the tourney. -Volatile option, but stored in tourney file. -@item -results string -@cindex results, option -The string of +=- characters lists the result of all played games in a tourney. -Games currently playing are listed as *, -while a space indicates a game that is not yet played. -Volatile option, but stored in tourney file. -@item -defaultTourneyName string -@cindex defaultTourneyName, option -Specifies the name of the tournament file XBoard should propose -when the @samp{Match Options} dialog is opened. -Any %y, %M, %d, %h, %m, %s in the string are replaced by the current -year, month, day of the month, hours, minutes, seconds of the current time, -respectively, as two-digit number. -A %Y would be replaced by the year as 4-digit number. Default: empty string. -@item -pairingEngine filename -@cindex pairingEngine, option -Specifies the external program to be used to pair the participants in Swiss tourneys. -XBoard communicates with this engine in the same way as it communicates with Chess engines. -The only commands sent to the pairing engine are “results N string”, -(where N is the number of participants, -and string the results so far in the format of the results option), -and “pairing N”, (where N is the number of the tourney game). -To the latter the pairing engine should answer with “A-B”, -where A and B are participant numbers (in the range 1-N). -(There should be no reply to the results command.) Default: empty string. -@item -afterGame string -@itemx -afterTourney string -@cindex afterGame, option -@cindex afterTourney, option -When non-empty, the given string will be executed as a system command -after each tournament game, or after the tourney completes, respectively. -This can be used, for example, to autmatically run a cross-table generator -on the PGN file where games are saved, to update the tourney standings. -Default: "" -@item -syncAfterRound true/false -@itemx -syncAfterCycle true/false -@cindex syncAfterRound, option -@cindex syncAfterCycle, option -Controls whether different instances of XBoard concurrently running the -same tournament will wait for each other. -Defaults: sync after cycle, but not after round. -@item -seedBase number -@cindex seedBase, option -Used to store the seed of the pseudo-random-number generator in the -tourneyFile, so that separate instances of XBoard working on the same -tourney can take coherent 'random' decisions, such as picking an -opening for a given game number. -@end table - -@node ICS options -@section ICS options -@cindex ICS options -@cindex Options, ICS -@table @asis -@item -ics/-xics or -internetChessServerMode true/false -@cindex ics, option -@cindex internetChessServerMode, option -Connect with an Internet Chess Server to play chess against its -other users, observe games they are playing, or review games -that have recently finished. Default: false. -@item -icshost or -internetChessServerHost host -@cindex icshost, option -@cindex internetChessServerHost, option -The Internet host name or address of the chess server to connect -to when in ICS mode. Default: @code{chessclub.com}. -Another popular chess server to try is @code{freechess.org}. -If your site doesn't have a working Internet name server, try -specifying the host address in numeric form. -You may also need -to specify the numeric address when using the icshelper option -with timestamp or timeseal (see below). -@item -icsport or -internetChessServerPort port-number -@cindex icsport, option -@cindex internetChessServerPort, option -The port number to use when connecting to a chess server in ICS -mode. Default: 5000. -@item -icshelper or -internetChessServerHelper prog-name -@cindex icshelper, option -@cindex internetChessServerHelper, option -An external helper program used to communicate with the chess server. -You would set it to "timestamp" for ICC (chessclub.com) or -"timeseal" for FICS (freechess.org), after -obtaining the correct version of timestamp or timeseal for your -computer. See "help timestamp" on ICC and "help timeseal" on FICS. -This option is shorthand for @code{-useTelnet -telnetProgram program}. -@item -telnet/-xtelnet or -useTelnet true/false -@cindex telnet, option -@cindex useTelnet, option -This option is poorly named; it should be called useHelper. -If set to true, it instructs XBoard to run an external -program to communicate with the Internet Chess Server. -The program to use is given by the telnetProgram option. -If the option is -false (the default), XBoard opens a TCP socket and uses its own -internal implementation of the telnet protocol to communicate with the -ICS. @xref{Firewalls}. -@item -telnetProgram prog-name -@cindex telnetProgram, option -This option is poorly named; it should be called helperProgram. -It gives the name of the telnet program to be used with -the @code{gateway} and @code{useTelnet} options. The default is -@file{telnet}. The telnet program is invoked with the value of -@code{internetChessServerHost} as its first argument and the value -of @code{internetChessServerPort} as its second argument. -@xref{Firewalls}. -@item -gateway host-name -@cindex gateway, option -If this option is set to a host name, XBoard communicates with the -Internet Chess Server by using @file{rsh} to run -the @code{telnetProgram} on the given host, -instead of using its own internal implementation -of the telnet protocol. You can substitute a different remote shell -program for @file{rsh} using the @code{remoteShell} option described below. -@xref{Firewalls}. -@item -internetChessServerCommPort or -icscomm dev-name -@cindex internetChessServerCommPort, option -@cindex icscomm, option -If this option is set, XBoard communicates with the ICS through -the given character I/O device instead of opening a TCP connection. -Use this option if your system does not have any kind of -Internet connection itself (not even a SLIP or PPP connection), -but you do have dial-up access (or a hardwired terminal line) to -an Internet service provider from which you can telnet to the ICS. - -The support for this option in XBoard is minimal. You need to -set all communication parameters and tty modes before you enter -XBoard. - -Use a script something like this: - -@example -stty raw -echo 9600 > /dev/tty00 -xboard -ics -icscomm /dev/tty00 -@end example - -Here replace @samp{/dev/tty00} with the name of the device that your -modem is connected to. You might have to add several more -options to these stty commands. See the man pages for @file{stty} -and @code{tty} if you run into problems. Also, on many systems stty -works on its standard input instead of standard output, so you -have to use @samp{<} instead of @samp{>}. - -If you are using linux, try starting with the script below. -Change it as necessary for your installation. - -@example -#!/bin/sh -f -# configure modem and fire up XBoard - -# configure modem -( - stty 2400 ; stty raw ; stty hupcl ; stty -clocal - stty ignbrk ; stty ignpar ; stty ixon ; stty ixoff - stty -iexten ; stty -echo -) < /dev/modem -xboard -ics -icscomm /dev/modem -@end example -@noindent -After you start XBoard in this way, type whatever commands are -necessary to dial out to your Internet provider and log in. -Then telnet to ICS, using a command like -@kbd{telnet chessclub.com 5000}. -Important: See the paragraph below about extra echoes, -in @ref{Limitations}. -@item -icslogon or -internetChessServerLogonScript file-name -@cindex icslogon, option -@cindex internetChessServerLogonScript, option -@cindex .icsrc -Whenever XBoard connects to the Internet Chess Server, -if it finds a file with the name given in this option, it feeds the -file's contents to the ICS as commands. The default file name -is @file{.icsrc}. -Usually the first two lines of the file should be -your ICS user name and password. -The file can be either in $CHESSDIR, in XBoard's working -directory if CHESSDIR is not set, or in your home directory. -@item -msLoginDelay delay -@cindex msLoginDelay, option -If you experience trouble logging on to an ICS when using the -@code{-icslogon} option, inserting some delay between characters -of the logon script may help. This option adds @code{delay} -milliseconds of delay between characters. Good values to try -are 100 and 250. -@item -icsinput/-xicsinput or -internetChessServerInputBox true/false -@cindex icsinput, option -@cindex internetChessServerInputBox, option -Sets the ICS Input Box menu option. @xref{Mode Menu}. Default: false. -@item -autocomm/-xautocomm or -autoComment true/false -@cindex autocomm, option -@cindex autoComment, option -Sets the Auto Comment menu option. @xref{Options Menu}. Default: false. -@item -autoflag/-xautoflag or -autoCallFlag true/false -@cindex autoflag, option -@cindex autoCallFlag, option -Sets the Auto Flag menu option. @xref{Options Menu}. Default: false. -@item -autobs/-xautobs or -autoObserve true/false -@cindex autobs, option -@cindex autoObserve, option -Sets the Auto Observe menu option. @xref{Options Menu}. Default: false. -@item -autoKibitz -@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 -seekGraph true/false or -sg -@cindex seekGraph, option -@cindex sg, option -Enables displaying of the seek graph by left-clicking the board when -you are logged on to an ICS and currently idle. -The seek graph show all players currently seeking games on the ICS, -plotted according to their rating and the time control of the game they seek, -in three different colors (for rated, unrated and wild games). -Computer ads are displayed as squares, human ads are dots. -Default: false. -@item -autoRefresh true/false -@cindex autoRefresh, option -Enables automatic updating of the seek graph, -by having the ICS send a running update of all newly placed -and removed seek ads. -This consumes a substantial amount of communication bandwidth, -and is only supported for FICS and ICC. -Default: false. -@item -backgroundObserve true/false -@cindex backgroundObserve, option -When true, boards sent to you by the ICS from other games while you are playing -(e.g. because you are observing them) -will not be automatically displayed. -Only a summary of time left and material of both players will appear -in the message field above the board. -XBoard will remember the last board it has received this way, -and will display it instead of the position in your own game -when you press the right mouse button. -No other information is stored on such games observed in the background; -you cannot save such a game later, or step through its moves. -This feature is provided solely for the benefit of bughouse players, -to enable them to peek at their partner's game without the need -to logon twice. -Default: false. -@item -dualBoard true/false -@cindex dualBoard, option -In combination with -backgroundObserve true, this option will display -the board of the background game side by side with that of your own game, -so you can have it in view permanently. -Any board or holdings info coming in will be displayed on the secondary -board immediately. -This feature is still experimental and largely unfinished. -There is no animation or highlighting of moves on the secondary board. -Default: false. -@item -disguisePromotedPieces true/false -@cindex disguisePromotedPieces, option -When set promoted Pawns in crazyhouse/bughouse are displayed identical -to primordial pieces of the same type, rather than distinguishable. -Default: true. -@item -moves/-xmoves or -getMoveList true/false -@cindex moves, option -@cindex getMoveList, option -Sets the Get Move List menu option. @xref{Options Menu}. Default: true. -@item -alarm/-xalarm or -icsAlarm true/false -@cindex alarm, option -@cindex icsAlarm, option -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. -@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 -Sets the Premove menu option. @xref{Options Menu}. Default: true. -@item -prewhite/-xprewhite or -premoveWhite -@itemx -preblack/-xpreblack or -premoveBlack -@itemx -premoveWhiteText string -@itemx -premoveBlackText string -@cindex prewhite, option -@cindex premoveWhite, option -@cindex preblack, option -@cindex premoveBlack, option -@cindex premoveWhiteText, option -@cindex premoveBlackText, option -Set the menu options for specifying the first move for either color. -@xref{Options Menu}. Defaults: false and empty strings, so no pre-moves. -@item -quiet/-xquiet or -quietPlay true/false -@cindex quiet, option -@cindex quietPlay, option -Sets the Quiet Play menu option. @xref{Options Menu}. Default: false. -@item -colorizeMessages or -colorize/-xcolorize -@cindex Colors -@cindex colorize, option -@cindex colorizeMessages, option -Setting colorizeMessages -to true tells XBoard to colorize the messages received from -the ICS. Colorization works only if your xterm -supports ISO 6429 escape sequences for changing text colors. -Default: true. -@item -colorShout foreground,background,bold -@itemx -colorSShout foreground,background,bold -@itemx -colorCShout foreground,background,bold -@itemx -colorChannel1 foreground,background,bold -@itemx -colorChannel foreground,background,bold -@itemx -colorKibitz foreground,background,bold -@itemx -colorTell foreground,background,bold -@itemx -colorChallege foreground,background,bold -@itemx -colorRequest foreground,background,bold -@itemx -colorSeek foreground,background,bold -@itemx -colorNormal foreground,background,bold -@cindex Colors -@cindex colorShout, option -@cindex colorSShout, option -@cindex colorCShout, option -@cindex colorChannel1, option -@cindex colorChannel, option -@cindex colorKibitz, option -@cindex colorTell, option -@cindex colorChallenge, option -@cindex colorRequest, option -@cindex colorSeek, option -@cindex colorNormal, option -These options set the colors used when colorizing ICS messages. -All ICS messages are grouped into one of these categories: -shout, sshout, channel 1, other channel, kibitz, tell, challenge, -request (including abort, adjourn, draw, pause, and takeback), or -normal (all other messages). - -Each foreground or background argument can be one of the following: -black, red, green, yellow, blue, magenta, cyan, white, or default. -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. - -@item -soundProgram progname -@cindex soundProgram, option -@cindex Sounds -If this option is set to a sound-playing program that is installed and -working on your system, XBoard can play sound files when certain -events occur, listed below. The default program name is "play". If -any of the sound options is set to "$", the event rings the terminal -bell by sending a ^G character to standard output, instead of playing -a sound file. If an option is set to the empty string "", no sound is -played for that event. -@item -soundDirectory directoryname -@cindex soundDirectory, option -@cindex Sounds -This option specifies where XBoard will look for sound files, -when these are not given as an absolute path name. -@item -soundShout filename -@itemx -soundSShout filename -@itemx -soundCShout filename -@itemx -soundChannel filename -@itemx -soundChannel1 filename -@itemx -soundKibitz filename -@itemx -soundTell filename -@itemx -soundChallenge filename -@itemx -soundRequest filename -@itemx -soundSeek filename -@cindex soundShout, option -@cindex soundSShout, option -@cindex soundCShout, option -@cindex soundChannel, option -@cindex soundChannel1, option -@cindex soundKibitz, option -@cindex soundTell, option -@cindex soundChallenge, option -@cindex soundRequest, option -@cindex soundSeek, option -These sounds are triggered in the same way as the colorization events -described above. They all default to "", no sound. They are played -only if the colorizeMessages is on. -CShout is synonymous with SShout. -@item -soundMove filename -@cindex soundMove, option -This sound is played when a player other than yourself makes a move. -Default: "$". -@item -soundRoar filename -@cindex soundRoar, option -This sound is played when a Lion makes a hit-and-run or double capture/ -Default: "" (no sound). -@item -soundIcsAlarm filename -@cindex soundIcsAlarm, option -This sound is used by the ICS Alarm menu option. Default: "$". -@item -soundIcsWin filename -@cindex soundIcsWin, option -This sound is played when you win an ICS game. Default: "" (no sound). -@item -soundIcsLoss filename -@cindex soundIcsLoss, option -This sound is played when you lose an ICS game. Default: "" (no sound). -@item -soundIcsDraw filename -@cindex soundIcsDraw, option -This sound is played when you draw an ICS game. Default: "" (no sound). -@item -soundIcsUnfinished filename -@cindex soundIcsUnfinished, option -This sound is played when an ICS game that you are participating in is -aborted, adjourned, or otherwise ends inconclusively. Default: "" (no -sound). -@end table - -@node Load and Save options -@section Load and Save options -@cindex Options, Load and Save -@cindex Load and Save options -@table @asis -@item -lgf or -loadGameFile file -@itemx -lgi or -loadGameIndex index -@cindex lgf, option -@cindex loadGameFile, option -@cindex lgi, option -@cindex loadGameIndex, option -If the @code{loadGameFile} option is set, XBoard loads the specified -game file at startup. The file name @file{-} specifies the standard -input. If there is more than one game in the file, XBoard -pops up a menu of the available games, with entries based on their PGN -(Portable Game Notation) tags. -If the @code{loadGameIndex} option is set to @samp{N}, the menu is suppressed -and the N th game found in the file is loaded immediately. -The menu is also suppressed if @code{matchMode} is enabled or if the game file -is a pipe; in these cases the first game in the file is loaded immediately. -Use the @file{pxboard} shell script provided with XBoard if you -want to pipe in files containing multiple games and still see the menu. -If the loadGameIndex specifies an index -1, this triggers auto-increment -of the index in @code{matchMode}, which means that after every game the -index is incremented by one, causing each game of the match to be played -from the next game in the file. Similarly, specifying an index value of -2 -causes the index to be incremented every two games, so that each game -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 -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}. -default: 0 (no rewind). -@item -td or -timeDelay seconds -@cindex td, option -@cindex timeDelay, option -Time delay between moves during @samp{Load Game} or @samp{Analyze File}. -Fractional seconds are allowed; try @samp{-td 0.4}. -A time delay value of -1 tells -XBoard not to step through game files automatically. Default: 1 second. -@item -sgf or -saveGameFile file -@cindex sgf, option -@cindex saveGameFile, option -If this option is set, XBoard appends a record of every game -played to the specified file. The file name @file{-} specifies the -standard output. -@item -autosave/-xautosave or -autoSaveGames true/false -@cindex autosave, option -@cindex autoSaveGames, option -Sets the Auto Save menu option. @xref{Options Menu}. Default: false. -Ignored if @code{saveGameFile} is set. -@item -onlyOwnGames true/false -@cindex onlyOwnGames, option -Suppresses auto-saving of ICS observed games. Default: false. -@item -lpf or -loadPositionFile file -@itemx -lpi or -loadPositionIndex index -@cindex lpf, option -@cindex loadPositionFile, option -@cindex lpi, option -@cindex loadPositionIndex, option -If the @code{loadPositionFile} option is set, XBoard loads the -specified position file at startup. The file name @file{-} specifies the -standard input. If the @code{loadPositionIndex} option is set to N, -the Nth position found in the file is loaded; otherwise the -first position is loaded. -If the loadPositionIndex specifies an index -1, this triggers auto-increment -of the index in @code{matchMode}, which means that after every game the -index is incremented by one, causing each game of the match to be played -from the next position in the file. Similarly, specifying an index value of -2 -causes the index to be incremented every two games, so that each position -in the file is used twice (with the engines playing opposite colors). -The @code{rewindIndex} option causes the index to be reset to the -first position of the file when it has reached a specified value. -@item -spf or -savePositionFile file -@cindex spf, option -@cindex savePositionFile, option -If this option is set, XBoard appends the final position reached -in every game played to the specified file. The file name @file{-} -specifies the standard output. -@item -positionDir directory -@cindex positionDir, option -Specifies the directory where file browsing should start when using -the @samp{Load Position} menu item. -@item -pgnExtendedInfo true/false -@cindex pgnExtendedInfo, option -If this option is set, XBoard saves depth, score and time used for each -move that the engine found as a comment in the PGN file. -Default: false. -@item -pgnEventHeader string -@cindex pgnEventHeader, option -Sets the name used in the PGN event tag to string. -Default: "Computer Chess Game". -@item -pgnNumberTag true/false -@cindex pgnNumberTag, option -Include the (unique) sequence number of a tournament game into the saved -PGN file as a 'number' tag. -Default: false. -@item -saveOutOfBookInfo true/false -@cindex saveOutOfBookInfo, option -Include the information on how the engine(s) game out of its opening book -in a special 'annotator' tag with the PGN file. -Default: true. -@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, c=result comment. -Default: "eprd" -@item -ini or -settingsFile filename -@itemx -saveSettingsFile filename -@itemx @@filename -@cindex saveSettingsFile, option -@cindex SettingsFile, option -@cindex init, option -@cindex at sign, option -When XBoard encounters an option -settingsFile (or -ini for short), -or @@filename, it tries to read the mentioned file, -and substitutes the contents of it (presumaby more command-line options) -in place of the option. -In the case of -ini or -settingsFile, the name of a successfully read -settings file is also remembered as the file to use for saving settings -(automatically on exit, or on user command). -An option of the form @@filename does not affect saving. -The option -saveSettingsFile does specify a name of the file to use -for saving, without reading any options from it, and is thus also effective -when the file did not exist yet. -So the settings will be saved to the file specified in the last --saveSettingsFile or succesfull -settingsFile / -ini command, -if any, and in /etc/xboard/xboard.conf otherwise. -Usualy the latter is only accessible for the system administrator, though, -and will be used to contain system-wide default settings, amongst which -a -saveSettingsFile and -settingsFile options to specify a settings file -accessible to the individual user, such as ~/.xboardrc in the user's -home directory. -@item -saveSettingsOnExit true/false -@cindex saveSettingsOnExit, option -Controls saving of options on the settings file. @xref{Options Menu}. -Default: true. -@end table - -@node User interface options -@section User interface options -@cindex User interface options -@cindex Options, User interface -@table @asis -@item -noGUI -@cindex noGUI, option -Suppresses all GUI functions of XBoard -(to speed up automated ultra-fast engine-engine games, which you don't 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 -logoSize N -@cindex logoSize, option -This option controls the drawing of player logos next to the clocks. -The integer N specifies the width of the logo in pixels; -the logo height will always be half the width. -When N = 0, no logos will be diplayed. -Default: 0. -@item -firstLogo imagefile -@itemx -secondLogo imagefile -@cindex firstLogo, option -@cindex secondLogo, option -Specify the images to be used as player logos when @code{logoSize} -is non-zero, next to the white and black clocks, respectively. -@item -autoLogo true/false -@itemx -logoDir filename -@cindex autoLogo, option -@cindex logoDir, option -When @code{autoLogo} is set, XBoard will search for a PNG image file -with the name of the engine or ICS in the directory specified -by @code{logoDir}. -For a human player it will look for a file .png in this -directory, but only when ~/.logo.png does not provide one. -@item -recentEngines number -@itemx -recentEngineList list -@cindex recentEngines, option -@cindex recentEngineList, option -When the number is larger than zero, it determines how many recently -used engines will be appended at the bottom of the @samp{Engines} menu. -The engines will be saved in your settings file as the option -@code{recentEngineList}, by their nicknames, -and the most recently used one will always be sorted to the top. -If the list after that is longer than the specified number, -the last one is discarded. -Changes in the list will only become visible the next session, -provided you saved the settings. -Default: 6. -@item -oneClickMove true/false -@cindex oneClickMove, option -When set, this option allows you to enter moves by only clicking the to- -or from-square, when only a single legal move to or from that square -is possible. -Double-clicking a piece (or clicking an already selected piece) -will instruct that piece to make the only capture it can legally do. -Default: false. -@item -monoMouse true/false -@cindex monoMouse, option -When set button 1 clicks on empty squares in Edit Position mode -will be interpreted as button 3 clicks, so they place a piece. -Default: false. -@item -movesound/-xmovesound or -ringBellAfterMoves true/false -@cindex movesound, option -@cindex bell, option -@cindex ringBellAfterMoves, option -Sets the Move Sound menu option. @xref{Options Menu}. Default: false. -For compatibility with old XBoard versions, -bell/-xbell are also -accepted as abbreviations for this option. -@item -analysisBell N -@cindex analysisBell, option -When N is non-zero, the Move Sound will be played whenever a new -PV arrives in analysis mode after more than N seconds of analysis. -Default: 0. -@item -exit/-xexit or -popupExitMessage true/false -@cindex exit, option -@cindex popupExitMessage, option -Sets the Popup Exit Message menu option. @xref{Options Menu}. Default: true. -@item -popup/-xpopup or -popupMoveErrors true/false -@cindex popup, option -@cindex popupMoveErrors, option -Sets the Popup Move Errors menu option. @xref{Options Menu}. Default: false. -@item -queen/-xqueen or -alwaysPromoteToQueen true/false -@cindex queen, option -@cindex alwaysPromoteToQueen, option -Sets the Always Queen menu option. @xref{Options Menu}. Default: false. -@item -sweepPromotions true/false -@cindex sweepPromotion, option -Sets the @samp{Almost Always Promote to Queen} menu option. -@xref{Options Menu}. Default: false. -@item -legal/-xlegal or -testLegality true/false -@cindex legal, option -@cindex testLegality, option -Sets the Test Legality menu option. @xref{Options Menu}. Default: true. -@item -size or -boardSize (sizeName | n1,n2,n3,n4,n5,n6,n7) -@cindex size, option -@cindex boardSize, option -@cindex board size -Determines how large the board will be, by selecting the pixel size -of the pieces and setting a few related parameters. -The sizeName can be one of: Titanic, giving 129x129 pixel pieces, -Colossal 116x116, Giant 108x108, Huge 95x95, Big 87x87, Large 80x80, Bulky 72x72, -Medium 64x64, Moderate 58x58, Average 54x54, Middling 49x49, Mediocre -45x45, Small 40x40, Slim 37x37, Petite 33x33, Dinky 29x29, Teeny 25x25, -or Tiny 21x21. -Xboard installs with a set of scalable (svg) piece images, -which it scales to any of the requested sizes. -The square size can further be continuously scaled by sizing the board window, -but this only adapts the size of the pieces, -and has no effect on the width of the grid lines or the font choice -(both of which would depend on he selected boardSize). -The default depends on the size of your screen; it is approximately the -largest size that will fit without clipping. - -You can select other sizes or vary other layout parameters by providing -a list of comma-separated values (with no spaces) as the argument. -You do not need to provide all the values; for any you omit from the -end of the list, defaults are taken from the nearest built-in size. -The value @code{n1} gives the piece size, @code{n2} the width of the -black border -between squares, @code{n3} the desired size for the -clockFont, @code{n4} the desired size for the coordFont, -@code{n5} the desired size for the messageFont, -@code{n6} the smallLayout flag (0 or 1), -and @code{n7} the tinyLayout flag (0 or 1). -All dimensions are in pixels. -If the border between squares is eliminated (0 width), the various -highlight options will not work, as there is nowhere to draw the highlight. -If smallLayout is 1 and @code{titleInWindow} is true, -the window layout is rearranged to make more room for the title. -If tinyLayout is 1, the labels on the menu bar are abbreviated -to one character each and the buttons in the button bar are made narrower. -@item -overrideLineGap n -@cindex overrideLineGap, option -When n >= 0, this forces the width of the black border between squares -to n pixels for any board size. Mostly used to suppress the grid -entirely by setting n = 0, e.g. in xiangqi or just getting a prettier -picture. When n < 0 this the size-dependent width of the grid lines -is used. Default: -1. -@item -coords/-xcoords or -showCoords true/false -@cindex coords, option -@cindex showCoords, option -Sets the Show Coords menu option. @xref{Options Menu}. Default: false. -The @code{coordFont} option specifies what font to use. -@item -autoraise/-xautoraise or -autoRaiseBoard true/false -@cindex autoraise, option -@cindex autoRaiseBoard, option -Sets the Auto Raise Board menu option. @xref{Options Menu}. Default: true. -@item -autoflip/-xautoflip or -autoFlipView true/false -@cindex autoflip, option -@cindex autoFlipView, option -Sets the Auto Flip View menu option. @xref{Options Menu}. Default: true. -@item -flip/-xflip or -flipView true/false -@cindex flip, option -@cindex flipView, option -If Auto Flip View is not set, or if you are observing but not participating -in a game, then the positioning of the board at the start of each game -depends on the flipView option. If flipView is false (the default), -the board is positioned so that the white pawns move from the bottom to the -top; if true, the black pawns move from the bottom to the top. -In any case, the Flip menu option (see @ref{Options Menu}) -can be used to flip the board after -the game starts. -@item -title/-xtitle or -titleInWindow true/false -@cindex title, option -@cindex titleInWindow, option -If this option is true, XBoard displays player names (for ICS -games) and game file names (for @samp{Load Game}) inside its main -window. If the option is false (the default), this information is -displayed only in the window banner. You probably won't want to -set this option unless the information is not showing up in the -banner, as happens with a few X window managers. -@item -buttons/-xbuttons or -showButtonBar True/False -@cindex buttons, option -@cindex showButtonBar, option -If this option is False, xboard omits the [<<] [<] [P] [>] [>>] button -bar from the window, allowing the message line to be wider. You can -still get the functions of these buttons using the menus or their keyboard -shortcuts. Default: true. -@item -evalZoom factor -@cindex evalZoom, option -The score interval (-1,1) is blown up on the vertical axis of -the Evaluation Graph by the given factor. -Default: 1 -@item -evalThreshold n -@cindex evalThreshold, option -Score below n (centiPawn) are plotted as 0 in the Evaluation Graph. -Default: 25 -@item -mono/-xmono or -monoMode true/false -@cindex mono, option -@cindex monoMode, option -Determines whether XBoard displays its pieces and squares with -two colors (true) or four (false). You shouldn't have to -specify @code{monoMode}; XBoard will determine if it is necessary. -@item -showTargetSquares true/false -@cindex showTargetSquares, option -Determines whether XBoard can highlight the squares a piece has -legal moves to, when you grab that piece with the mouse. -Default: false. -@item -flashCount count -@itemx -flashRate rate -@itemx -flash/-xflash -@cindex flashCount, option -@cindex flashRate, option -@cindex flash, option -@cindex xflash, option -These options enable flashing of pieces when they -land on their destination square. -@code{flashCount} -tells XBoard how many times to flash a piece after it -lands on its destination square. -@code{flashRate} -controls the rate of flashing (flashes/sec). -Abbreviations: -@code{flash} -sets flashCount to 3. -@code{xflash} -sets flashCount to 0. -Defaults: flashCount=0 (no flashing), flashRate=5. -@item -highlight/-xhighlight or -highlightLastMove true/false -@cindex highlight, option -@cindex highlightLastMove, option -Sets the Highlight Last Move menu option. @xref{Options Menu}. Default: false. -@item -highlightMoveWithArrow true/false -@cindex highlight Arrow, option -@cindex highlightMoveWithArrow, option -Sets the Highlight with Arrow menu option. @xref{Options Menu}. Default: false. -@item -blind/-xblind or -blindfold true/false -@cindex blind, option -@cindex blindfold, option -Sets the Blindfold menu option. @xref{Options Menu}. Default: false. -@item -periodic/-xperiodic or -periodicUpdates true/false -@cindex periodic, option -@cindex periodicUpdates, option -Controls updating of current move andnode counts in analysis mode. Default: true. -@item -fSAN -@itemx -sSAN -@cindex fSAN, option -@cindex sSAN, option -Causes the PV in thinking output of the mentioned engine to be converted -to SAN before it is further processed. -Warning: this might lose engine output not understood by the parser, -and uses a lot of CPU power. -Default: the PV is displayed exactly as the engine produced it. -@item -showEvalInMoveHistory true/false -@cindex showEvalInMoveHistory, option -Controls whether the evaluation scores and search depth of engine moves -are displayed with the move in the move-history window. -Default: true. -@item -clockFont font -@cindex clockFont, option -@cindex Font, clock -The font used for the clocks. If the option value is a pattern -that does not specify the font size, XBoard tries to choose an -appropriate font for the board size being used. -Default Xaw: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*. -Default GTK: Sans Bold %d. -@item -coordFont font -@cindex coordFont, option -@cindex Font, coordinates -The font used for rank and file coordinate labels if @code{showCoords} -is true. If the option value is a pattern that does not specify -the font size, XBoard tries to choose an appropriate font for -the board size being used. -Default Xaw: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*. -Default GTK: Sans Bold %d. -@item -messageFont font -@cindex messageFont, option -@cindex Font, message -The font used for popup dialogs, menus, etc. -If the option value is a pattern that does not specify -the font size, XBoard tries to choose an appropriate font for -the board size being used. -Default Xaw: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*. -Default GTK: Sans Bold %d -@item -tagsFont font -@cindex tagsFont, option -@cindex Font, tags -The font used in the Edit Tags dialog. -If the option value contains %d, XBoard will replace it by -an appropriate font for the board size being used. -(Only used in GTK build.) -Default: Sans Normal %d. -@item -commentFont font -@cindex commentFont, option -@cindex Font, comment -The font used in the Edit Comment dialog. -If the option value contains %d, XBoard will replace it by -an appropriate font for the board size being used. -(Only used in GTK build.) -Default: Sans Normal %d. -@item -icsFont font -@cindex icsFont, option -@cindex Font, ics -The font used to display ICS output in the ICS Chat window. -As ICS output often contains tables aligned by spaces, -a mono-space font is recommended here. -If the option value contains %d, XBoard will replace it by -an appropriate font for the board size being used. -(Only used in GTK build.) -Default: Monospace Normal %d. -@item -moveHistoryFont font -@cindex moveHistoryFont, option -@cindex Font, moveHistory -The font used in Move History and Engine Output windows. -As these windows display mainly moves, -one could use a figurine font here. -If the option value contains %d, XBoard will replace it by -an appropriate font for the board size being used. -(Only used in GTK build.) -Default: Sans Normal %d. -@item -gameListFont font -@cindex gameListFont, option -@cindex Font, gameList -The font used in the listbox of the Game List window. -If the option value contains %d, XBoard will replace it by -an appropriate font for the board size being used. -(Only used in GTK build.) -Default: Sans Bold %d. -@item -fontSizeTolerance tol -@cindex fontSizeTolerance, option -In the font selection algorithm, a nonscalable font will be preferred -over a scalable font if the nonscalable font's size differs -by @code{tol} pixels -or less from the desired size. A value of -1 will force -a scalable font to always be used if available; a value of 0 will -use a nonscalable font only if it is exactly the right size; -a large value (say 1000) will force a nonscalable font to always be -used if available. Default: 4. -@item -pid or -pieceImageDirectory dir -@cindex pid, option -@cindex pieceImageDirectory, option -This options control what piece images xboard uses. -XBoard will look in the specified directory for an image in png -or svg format for every piece type, with names like BlackQueen.svg, -WhiteKnight.svg etc. -When neither of these is found (or no valid directory is specified) -XBoard will first ty to use an image White/BlackTile.svg in that same -directory, and if that is not present either -use the svg piece that was installed with it -(from the source-tree directory @samp{svg}). -Both svg and png images will be scaled by XBoard to the required size, -but the png pieces lose much in quality when scaled too much. -Default: "". -@item -inscriptions utf8string -@cindex inscriptions, option -The positions in the utf8string correspond to XBoard's piece types, -and for each type a glyph can be defined. -This glyph will then be rendered on top of the image for the piece. -This is useful in combination with the White/BlackTile.svg images, -which could be the image of a blank Shogi tile, for writing the -kanji piece name on top of it on the fly. -Default: "". - -@item -whitePieceColor color -@itemx -blackPieceColor color -@itemx -lightSquareColor color -@itemx -darkSquareColor color -@itemx -highlightSquareColor color -@itemx -preoveHighlightColor color -@itemx -lowTimeWarningColor color -@cindex Colors -@cindex whitePieceColor, option -@cindex blackPieceColor, option -@cindex lightSquareColor, option -@cindex darkSquareColor, option -@cindex highlightSquareColor, option -@cindex premoveHighlightColor, option -@cindex lowTimeWarningColor, option -Colors to use for the pieces, squares, and square highlights. -Defaults: - -@example --whitePieceColor #FFFFCC --blackPieceColor #202020 --lightSquareColor #C8C365 --darkSquareColor #77A26D --highlightSquareColor #FFFF00 --premoveHighlightColor #FF0000 --lowTimeWarningColor #FF0000 -@end example - -On a grayscale monitor you might prefer: - -@example --whitePieceColor gray100 --blackPieceColor gray0 --lightSquareColor gray80 --darkSquareColor gray60 --highlightSquareColor gray100 --premoveHighlightColor gray70 --lowTimeWarningColor gray70 -@end example - -The PieceColor options only work properly if the image files -defining the pieces were pure black & white -(possibly anti-aliased to produce gray scales -and semi-transparancy), -like the pieces images that come with the install. -Their effect on colored pieces is undefined. -The SquareColor option only have an effect -when no board textures are used. -@item -trueColors true/false -@cindex trueColors, option -When set, this option suppresses the effect of the -PieceColor options mentioned above. -This is recommended for images that are already colored. -@item -useBoardTexture true/false -@itemx -liteBackTextureFile filename -@itemx -darkBackTextureFile filename -@cindex useBoardTexture, option -@cindex liteBackTextureFile, option -@cindex darkBackTextureFile, option -Indicate the png image files to be used for drawing the board squares, -and if they should be used rather than using simple colors. -The algorithm for cutting squares out of a given bitmap is such that -the picture is perfectly reproduced when a bitmap the size of -the complete board is given. -If the filename ends in "-NxM.png", with integer N and M, -it is assumed to contain a bitmap of a complete board of N files -and M ranks, and XBoard will scale it to exactly match the -current square size. -If N=M=0 it scales the entire bitmap to the size of the board, -irrespective of the number of files and ranks of the latter. -Without any -NxM suffix textures are only blown up by an integer -factor when they are smaller than the square size, or, -when the name starts with "xq", too small to cover the -complete Xiangqi board. -Default: false and "" -@item -drag/-xdrag or -animateDragging true/false -@cindex drag, option -@cindex animateDragging, option -Sets the Animate Dragging menu option. @xref{Options Menu}. Default: true. -@item -animate/-xanimate or -animateMoving true/false -@cindex animate, option -@cindex animateMoving, option -Sets the Animate Moving menu option. @xref{Options Menu}. Default: true. -@item -animateSpeed n -@cindex -animateSpeed, option -Number of milliseconds delay between each animation frame when Animate -Moves is on. -@item -autoDisplayComment true/false -@itemx -autoDisplayTags true/false -@cindex -autoDisplayComment, option -@cindex -autoDisplayTags, option -If set to true, these options cause the window with the move comments, -and the window with PGN tags, respectively, to pop up automatically when -such tags or comments are encountered during the replaying a stored or -loaded game. Default: true. -@item -pasteSelection true/false -@cindex -pasteSelection, option -If this option is set to true, the Paste Position and Paste Game -options paste from the currently selected text. If false, they paste -from the clipboard. Default: false. -@item -autoCopyPV true|false -@cindex autoCopyPV, option -When this option is set, the position displayed on the board when -you terminate a PV walk -(initiated by a right-click on board or engine-output window) -will be automatically put on the clipboard as FEN. -Default: false. -@item -dropMenu true|false -@cindex dropMenu, option -This option allows you to emulate old behavior, -where the right mouse button brings up the (now deprecated) drop menu -rather than displaying the position at the end of the principal variation. -Default: False. -@item -pieceMenu true|false -@cindex pieceMenu, option -This option allows you to emulate old behavior, -where the right mouse button brings up the (now deprecated) piece menu -in Edit Position mode. -From this menu you can select the piece to put on the square you -clicked to bring up the menu, -or select items such as @kbd{clear board}. -You can also @kbd{promote} or @kbd{demote} a clicked piece to convert -it into an unorthodox piece that is not directly in the menu, -or give the move to @kbd{black} or @kbd{white}. -@item -variations true|false -@cindex variations, option -When this option is on, you can start new variations in Edit Game or -Analyze mode by holding the Shift key down while entering a move. -When it is off, the Shift key will be ignored. -Default: False. -@item -appendPV true|false -@cindex appendPV, option -When this option is on, a button 3 click left of a PV in the Engine -Output window will play the first move of that PV in Analyze mode, -or as many moves as you walk through it by moving the mouse. -Default: False. -@item -absoluteAnalysisScores true|false -@cindex absoluteAnalysisScores, option -When true, scores on the Engine Output window during analysis -will be printed from the white point-of-view, rather than the -side-to-move point-of-view. -Default: False. -@item -scoreWhite true|false -@cindex scoreWhite, option -When true, scores will always be printed from the white point-of-view, -rather than the side-to-move point-of-view. -Default: False. -@item -memoHeaders true|false -@cindex memoHeaders, option -When true, column headers will be displayed in the Engine Output window -for the depth, score, time and nodes data. -A button 3 click on these headers will hide or show the corresponding data. -(Not intended for dynamic use, as already printed data of the current search -will not be affected!) -Defaul: False. -@end table - -@node Adjudication Options -@section Adjudication Options -@cindex Options, adjudication -@table @asis -@item -adjudicateLossThreshold n -@cindex adjudicateLossThreshold, option -If the given value is non-zero, XBoard adjudicates the game as a loss -if both engines agree for a duration of 6 consecutive ply that the score -is below the given score threshold for that engine. Make sure the score -is interpreted properly by XBoard, -using @code{-firstScoreAbs} and @code{-secondScoreAbs} if needed. -Default: 0 (no adjudication) -@item -adjudicateDrawMoves n -@cindex adjudicateDrawMoves, option -If the given value is non-zero, XBoard adjudicates the game as a draw -if after the given number of moves it was not yet decided. Default: 0 (no adjudication) -@item -checkMates true/false -@cindex checkMates, option -If this option is set, XBoard detects all checkmates and stalemates, -and ends the game as soon as they occur. -Legality-testing must be switched on for this option to work. -Default: true -@item -testClaims true/false -@cindex testClaims, option -If this option is set, XBoard verifies all result claims made by engines, -and those who send false claims will forfeit the game because of it. -Legality-testing must be switched on for this option to work. Default: true -@item -materialDraws true/false -@cindex materialDraws, option -If this option is set, XBoard adjudicates games as draws when there is -no sufficient material left to inflict a checkmate. -This applies to KBKB with like bishops (any number, actually), and to KBK, KNK and KK. -Legality-testing must be switched on for this option to work. Default: true -@item -trivialDraws true/false -@cindex trivialDraws, option -If this option is set, XBoard adjudicates games as draws that cannot be -usually won without opponent cooperation. This applies to KBKB with unlike bishops, -and to KBKN, KNKN, KNNK, KRKR and KQKQ. The draw is called after 6 ply into these end-games, -to allow quick mates that can occur in some exceptional positions to be found by the engines. -KQKQ does not really belong in this category, and might be taken out in the future. -(When bitbase-based adjudications are implemented.) -Legality-testing must be on for this option to work. Default: false -@item -ruleMoves n -@cindex ruleMoves, option -If the given value is non-zero, XBoard adjudicates the game as a draw after the given -number of consecutive reversible moves. Engine draw claims are always accepted after 50 moves, -irrespective of the given value of n. -@item -repeatsToDraw n -If the given value is non-zero, xboard adjudicates the game as a draw if a position -is repeated the given number of times. Engines draw claims are always accepted after 3 repeats, -(on the 3rd occurrence, actually), irrespective of the value of n. -Beware that positions that have different castling or en-passant rights do not count -as repeats, XBoard is fully e.p. and castling aware! -@end table - -@node Install options -@section Install options -@cindex Options, install -@table @asis -@item --show-config parameter -@cindex show-config, option -When called with this option, XBoard will close immediately after printing the -value of the indicated configuration parameter, or, when no parameter was given, -after printing a list of all such parameters. -Currently the only valid values for parameter are Datadir and Sysconfdir. -This option can be used by install scripts for board themes -to figure out where the currently active XBoard stores its data. -@item -date timestamp -@itemx -saveDate timestamp -@cindex date, option -@cindex saveDate, option -These options specify an epoch as an integer number. -The @code{saveDate} option is written by XBoard in the settings file every time the -settings are saved, with the current time, so that later runs of XBoard can know this. -The @code{date} option can be included in settings files to indicate when lines -following it were added to those files. -Some options will be ignored if the epoch specified by the latest @code{date} option -predates the -saveDate setting (implying they must have been seen before). -@item -autoInstall list -@cindex autoInstall, option -When the list is set to a non-empty string, XBoard will scan the -operating system's plugin directory for engines supporting UCI -and XBoard protocol at startup. -When it finds an engine that was installed after it last saved -its settings, a line to launch that engine (as per specs in -the plugin file) is appended to the -firstChessProgramNames -list of installed engines. -In the future it will be possible to use the autoInstall list to limit -this automatic adding of engines based on the chess variant they play. -@item -addMasterOption string -@cindex addMasterOption, option -Adds the mentioned string as an additional line of XBoard's master settings file, -after adding a line with a @code{date} option to timestamp it. -Intended to add options of the 'install' type (see below) to the master file, -which will then be processed by any XBoard that has not seen them since -it last saved its settings. -@item -autoClose -@cindex autoClose, option -The presence of this option cause XBoard to close immediately after processing -all its options (from settings file and command line). -Typically used from install scripts together with options that change XBoard's -settings files, so that XBoard can be run in batch mode rather than interactively. -@item -installEngine string -@cindex installEngine, option -Adds the given string as an additional line to the value of the -@code{firstChessProgramNames} option when the -saveDate setting preceeds the -date setting. -Intended for adding to the master settings file with the aid of -addMasterOption -in the install script of engines, as a method for broadcasting the presence -of a new engine to all users, -which would then see it automatically registered with XBoard. -Made obsolete by the advent of the plugin standard (see the @code{autoInstall} option), -which broadcasts such presence in a non-XBoard-specific way -by dropping *.eng files in a certain system directory. -@item -installTheme string -@cindex installTheme, option -Adds the given string as an additional line to the value of the --themeNames option when the -saveDate setting preceeds the -date setting. -Intended for adding to the master settings file with the aid of -addMasterOption -in the install script of board graphics themes, -as a method for broadcasting the availability of a new theme to all users, -who would then see the theme appear automatically in the listbox in the -View Board menu dialog next time they run XBoard. -@end table - -@node Other options -@section Other options -@cindex Options, miscellaneous -@table @asis -@item -ncp/-xncp or -noChessProgram true/false -@cindex ncp, option -@cindex noChessProgram, option -If this option is true, XBoard acts as a passive chessboard; it -does not start a chess engine at all. Turning on this option -also turns off clockMode. Default: false. -@item -viewer -@itemx -viewerOptions string -@cindex viewer, option -@cindex viewerOptions, option -Presence of the volatile option @code{viewer} on the command line -will cause the value of the persistent option @code{viewerOptions} -as stored in the settings file to be appended to the command line. -The @code{view} option will be used by desktop associations with -game or position file types, so that @code{viewerOptions} can be -used to configure the exact mode XBoard will start in when it -should act on such a file (e.g. in -ncp mode, or analyzing -with your favorite engine). The options are also automatically -appended when Board is invoked with a single argument not being -an option name, which is then assumed to be the name of a -@code{loadGameFile} or (when the name ends in .fen) a -@code{loadPositionFile}. -Default: "-ncp -engineOutputUp false -saveSettingsOnExit false". -@item -tourneyOptions string -@cindex tourneyOptions, option -When XBoard is invoked with a single argument that is a file -with .trn extension, it will assume this argument to be the value -of a @code{tourneyFile} option, -and append the value of the persistent option @code{tourneyOptions} -as stored in the settings file to the command line. -Thus the value of @code{tourneyOptions} can be -used to configure XBoard to automatically start running a -tournament when it should act on such a file. -Default: "-ncp -mm -saveSettingsOnExit false". -@item -mode or -initialMode modename -@cindex mode, option -@cindex initalMode, option -If this option is given, XBoard selects the given modename -from the Mode menu after starting and (if applicable) processing the -loadGameFile or loadPositionFile option. Default: "" (no selection). -Other supported values are -MachineWhite, MachineBlack, TwoMachines, Analysis, -AnalyzeFile, EditGame, EditPosition, and Training. -@item -variant varname -@cindex variant, option -Activates (sometimes partial) support for playing chess variants -against a local engine or editing variant games. This flag is not -needed in ICS mode. Recognized variant names are: - -@example -normal Normal chess -wildcastle Shuffle chess, king can castle from d file -nocastle Shuffle chess, no castling allowed -fischerandom Fischer Random shuffle chess -bughouse Bughouse, ICC/FICS rules -crazyhouse Crazyhouse, ICC/FICS rules -losers Lose all pieces or get mated (ICC wild 17) -suicide Lose all pieces including king (FICS) -giveaway Try to have no legal moves (ICC wild 26) -twokings Weird ICC wild 9 -kriegspiel Opponent's pieces are invisible -atomic Capturing piece explodes (ICC wild 27) -3check Win by giving check 3 times (ICC wild 25) -shatranj An ancient precursor of chess (ICC wild 28) -xiangqi Chinese Chess (on a 9x10 board) -shogi Japanese Chess (on a 9x9 board & piece drops) -capablanca Capablanca Chess (10x8 board, with Archbishop - and Chancellor pieces) -gothic similar, with a better initial position -caparandom An FRC-like version of Capablanca Chess (10x8) -janus A game with two Archbishops (10x8 board) -courier Medieval intermediate between shatranj and - modern Chess (on 12x8 board) -falcon Patented 10x8 variant with two Falcon pieces -berolina Pawns capture straight ahead, and move diagonally -cylinder Pieces wrap around the board edge -knightmate King moves as Knight, and vice versa -super Superchess (shuffle variant with 4 exo-pieces) -makruk Thai Chess (shatranj-like, P promotes on 6th rank) -asean ASEAN Chess (a modernized version of Makruk) -spartan Spartan Chess (black has unorthodox pieces) -great Great Shatranj, a 10x8 variant without sliders -grand Grand Chess, on 10x10 with Capablanca pieces -lion Mighty-Lion Chess, with a multi-capturing Lion -elven Eleven Chess, with Lion and crowned sliders on 10x10 -chu Chu Shogi, historic 12x12 variant with 2x46 pieces -fairy A catchall variant in which all piece types - known to XBoard can participate (8x8) -unknown Catchall for other unknown variants -@end example - -In the shuffle variants, XBoard does shuffle the pieces, although -you can still do it by hand using Edit Position. Some variants are -supported only in ICS mode, including bughouse, and -kriegspiel. -Berolina and cylinder chess are only partially supported, -and can only be played with legality testing off. - -Apart from these standard variants, engines can define variants -of arbitrary names, briefing XBoard transparently on the rules -for piece movement, board size and initial setup, -so that they work nearly as well as fully-supported standard variants. -(But obviously only while using that engine.) -The user might have to alter the adjudication settings for some -variants, however. E.g. it makes no sense to adjudicate a draw -after 50 reversible moves in variants that have a 64-move rule, -or no similar rule at all. - -Default: "normal". Except when the first engine gave an explicit list -of variants it supports, and 'normal' is not amongst those. -In that case the first variant the engine mentioned it did play will -be chosen. -@item -boardHeight N -@cindex boardHeight, option -Allows you to set a non-standard number of board ranks in any variant. -If the height is given as -1, the default height for the variant is used. -Default: -1 -@item -boardWidth N -@cindex boardWidth, option -Allows you to set a non-standard number of board files in any variant. -If the width is given as -1, the default width for the variant is used. -With a non-standard width, the initial position will always be an empty board, -as the usual opening array will not fit. -Default: -1 -@item -holdingsSize N -@cindex holdingsSize, option -Allows you to set a non-standard size for the holdings in any variant. -If the size is given as -1, the default holdings size for the variant is used. -The first N piece types will go into the holdings on capture, and you will be -able to drop them on the board in stead of making a normal move. If size equals 0, -there will be no holdings. -Default: -1 -@item -defaultFrcPosition N -@cindex defaultFrcPosition, option -Specifies the number of the opening position in shuffle games like Chess960. -A value of -1 means the position is randomly generated by XBoard -at the beginning of every game. -Default: -1 -@item -pieceToCharTable string -@cindex pieceToCharTable, option -The characters that are used to represent the piece types XBoard knows in FEN -diagrams and SAN moves. -You should not have to use this option often: each variant has its own default -setting for the piece representation in FEN, which should be sufficient in normal use. -The string argument has to specify an even number of pieces -(or it will be ignored), as white and black pieces have to be given separately -(in that order). The last letter for each color will be the King. -The letters before that will be PNBRQ and then a whole host of fairy pieces -in an order that has not fully crystallized yet (currently FEACWMOHIJGDVLSU, -F=Ferz, Elephant, A=Archbishop, C=Chancellor, W=Wazir, M=Commoner, O=Cannon, -H=Nightrider). You should list at least all pieces that occur in the variant -you are playing. If you have fewer characters in the string than XBoard has -pieces, the pieces not mentioned will get assigned a period, -and will not be usable in the variant. -You can also explicitly assign pieces a period, in which case they -will not be counted in deciding which captured pieces can go into the holdings. -A tilde '~' as a piece name does mean this piece is used to represent a promoted -Pawn in crazyhouse-like games, i.e. on capture it turns back to a Pawn. -A '+' similarly indicates the piece is a shogi-style promoted piece, that should -revert to its non-promoted version on capture (rather than to a Pawn). -By default the second 11 pieces known to XBoard are the promoted forms of the first 11. -A piece specified by the character combination ^ plus letter will be assumed -to be the promoted form of the piece indicated by that letter, -and get a '+' assigned. -To get around the limitation of the alphabet, -piece IDs can also be 'dressed letters', i.e. a single letter -(upper case for white, lower case for black) -followed by a single quote or an exclamation point. -Default: "" (meaning the default for the variant is used). -@item -pieceNickNames string -@cindex pieceNickNames, option -The characters in the string are interpreted the same way as in the -@code{pieceToCharTable} option. But on input, piece-ID letters are -first looked up in the nicknames, and only if not defined there, -in the normal pieceToCharTable. This allows you to have two letters -designate the same piece, (e.g. N as an alternative to H for Horse -in Xiangqi), to make reading of non-compliant notations easier. -Default: "" -@item -colorNickNames string -@cindex colorNickNames, option -The side-to-move field in a FEN will be first matched against the letters -in the string (first character for white, second for black), -before it is matched to the regular 'w' and 'b'. -This makes it easier to read non-compliant FENs, -which, say, use 'r' for white. -Default: "" -@item -debug/-xdebug or -debugMode true/false -@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 XBoard saves debug information -(including all communication to and from the engines). -A @kbd{%d} in the given file name (e.g. game%d.debug) will be replaced -by the unique sequence number of a tournament game, -so that the debug output of each game will be written on a separate file. -@item -engineDebugOutput number -@cindex engineDebugOutput, option -Specifies how XBoard 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, XBoard 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 '#' 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 -Name of the command used to run programs remotely. The default -is @file{rsh} or @file{remsh}, determined when XBoard is -configured and compiled. -@item -ruser or -remoteUser user-name -@cindex ruser, option -@cindex remoteUser, option -User name on the remote system when running programs with the -@code{remoteShell}. The default is your local user name. -@item -userName username -@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 order pauses before and after sending the "quit" command to an engine that must be terminated. -The pause between quit and the previous command is specified in milliseconds. -The pause after quit is used to schedule a kill signal to be sent to the engine process after the -number of specified seconds plus one. -This signal is a different one as the terminiation signal described in the protocol specs -which engines can suppress or ignore, and which is sent directly after the "quit" command. -Setting @code{delayAfterQuit} to -1 will suppress sending of the kill signal. -Default: 0 -@item -searchMode n -@cindex searchMode, option -The integer n encodes the mode for the @samp{find position} function. -Default: 1 (= Exact position match) -@item -eloThresholdBoth elo -@itemx -eloThresholdAny elo -@cindex eloThresholdBoth, option -@cindex eloThresholdAny, option -Defines a lower limit for the Elo rating, which has to be surpassed -before a game will be considered when searching for a board position. -Default: 0 -@item -dateThreshold year -@cindex dateThreshold, option -Only games not played before the given year will be considered when -searching for a board position - - -@end table - -@node Chess Servers -@chapter Chess Servers -@cindex ICS -@cindex ICS, addresses -@cindex Internet Chess Server -An @dfn{Internet Chess Server}, or @dfn{ICS}, is a place on the -Internet where people can get together to play chess, watch other -people's games, or just chat. You can use either @code{telnet} or a -client program like XBoard to connect to the server. There are -thousands of registered users on the different ICS hosts, and it is -not unusual to meet 200 on both chessclub.com and freechess.org. - -Most people can just type @kbd{xboard -ics} to start XBoard as an ICS -client. Invoking XBoard in this way connects you to the Internet -Chess Club (ICC), a commercial ICS. You can log in there as a guest -even if you do not have a paid account. To connect to the largest -Free ICS (FICS), use the command @kbd{xboard -ics -icshost freechess.org} -instead, or substitute a different host name to connect to your -favorite ICS. -For a full description of command-line options that control -the connection to ICS and change the default values of ICS options, see -@ref{ICS options}. - -While you are running XBoard as an ICS client, -you use the terminal window that you started XBoard from -as a place to type in commands and read information that is -not available on the chessboard. - -The first time you need to use the terminal is to enter your login name -and password, if you are a registered player. (You don't need to do -this manually; the @code{icsLogon} option can do it for you. -@pxref{ICS options}.) If you are not registered, -enter @kbd{g} as your name, and the server will pick a -unique guest name for you. - -Some useful ICS commands -include -@table @kbd -@item help -@cindex help, ICS command -to get help on the given . To get a list of possible topics type -@dfn{help} without topic. Try the help command before you ask other -people on the server for help. - -For example @kbd{help register} tells you how to become a registered -ICS player. -@item who -@cindex who, ICS command -to see a list of people who are logged on. Administrators -(people you should talk to if you have a problem) are marked -with the character @samp{*}, an asterisk. The allow you to -display only selected players: For example, @kbd{who of} shows a -list of players who are interested in playing but do not have -an opponent. -@item games -@cindex games, ICS command -to see what games are being played -@item match [] [] -to challenge another player to a game. Both opponents get minutes -for the game, and seconds will be added after each move. -If another player challenges you, the server asks if you want to -accept the challenge; use the @kbd{accept} or @kbd{decline} commands -to answer. -@item accept -@itemx decline -@cindex accept, ICS command -@cindex decline, ICS command -to accept or decline another player's offer. -The offer may be to start a new game, or to agree to a -@kbd{draw}, @kbd{adjourn} or @kbd{abort} the current game. @xref{Action Menu}. - -If you have more than one pending offer (for example, if more than one player -is challenging you, or if your opponent offers both a draw and to adjourn the -game), you have to supply additional information, by typing something -like @kbd{accept }, @kbd{accept draw}, or @kbd{draw}. -@item draw -@itemx adjourn -@itemx abort -@cindex draw, ICS command -@cindex adjourn, ICS command -@cindex abort, ICS command -asks your opponent to terminate a game by mutual agreement. Adjourned -games can be continued later. -Your opponent can either @kbd{decline} your offer or accept it (by typing the -same command or typing @kbd{accept}). In some cases these commands work -immediately, without asking your opponent to agree. For example, you can -abort the game unilaterally if your opponent is out of time, and you can claim -a draw by repetition or the 50-move rule if available simply by typing -@kbd{draw}. -@item finger -@cindex finger, ICS command -to get information about the given . (Default: yourself.) -@item vars -@cindex vars, ICS command -to get a list of personal settings -@item set -@cindex set, ICS command -to modify these settings -@item observe -@cindex observe, ICS command -to observe an ongoing game of the given . -@item examine -@itemx oldmoves -@cindex examine, ICS command -@cindex oldmoves, ICS command -to review a recently completed game -@end table - -Some special XBoard features are activated when you are -in examine mode on ICS. See the descriptions of the menu commands -@samp{Forward}, @samp{Backward}, @samp{Pause}, @samp{ICS Client}, -and @samp{Stop Examining} on the @ref{Edit Menu}, @ref{Mode Menu}, and -@ref{Action Menu}. - -@node Firewalls -@chapter Firewalls -By default, XBoard communicates with an Internet Chess Server -by opening a TCP socket directly from the machine it is running on -to the ICS. If there is a firewall between your machine and the ICS, -this won't work. Here are some recipes for getting around common -kinds of firewalls using special options to XBoard. -Important: See the paragraph in the below about extra echoes, in -@ref{Limitations}. - -Suppose that you can't telnet directly to ICS, but you can telnet -to a firewall host, log in, and then telnet from there to ICS. -Let's say the firewall is called @samp{firewall.example.com}. Set -command-line options as follows: - -@example -xboard -ics -icshost firewall.example.com -icsport 23 -@end example -@noindent -Then when you run XBoard in ICS mode, you will be prompted -to log in to the firewall host. This works because port 23 is the -standard telnet login service. Do so, then telnet to ICS, using a -command like @samp{telnet chessclub.com 5000}, or whatever command -the firewall provides for telnetting to port 5000. - -If your firewall lets you telnet (or rlogin) to remote hosts but -doesn't let you telnet to port 5000, you may be able to connect to the -chess server on port 23 instead, which is the port the telnet program -uses by default. Some chess servers support this (including -chessclub.com and freechess.org), while some do not. - -If your chess server does not allow connections on port 23 and your -firewall does not allow you to connect to other ports, you may be able -to connect by hopping through another host outside the firewall that -you have an account on. For instance, suppose you have a shell -account at @samp{foo.edu}. Follow the recipe above, but instead of -typing @samp{telnet chessclub.com 5000} to the firewall, type -@samp{telnet foo.edu} (or @samp{rlogin foo.edu}), log in there, and -then type @samp{telnet chessclub.com 5000}. - -Suppose that you can't telnet directly to ICS, but you can use rsh -to run programs on a firewall host, and that host can telnet to ICS. -Let's say the firewall is called @samp{rsh.example.com}. Set -command-line options as follows: - -@example -xboard -ics -gateway rsh.example.com -icshost chessclub.com -@end example - -@noindent -Then when you run XBoard in ICS mode, it will connect to -the ICS by using @file{rsh} to run the command -@samp{telnet chessclub.com 5000} on host @samp{rsh.example.com}. - -Suppose that you can telnet anywhere you want, but you have to -run a special program called @file{ptelnet} to do so. - -First, we'll consider the easy case, in which -@samp{ptelnet chessclub.com 5000} gets you to the chess server. -In this case set command line options as follows: - -@example -xboard -ics -telnet -telnetProgram ptelnet -@end example - -@noindent -Then when you run XBoard in ICS mode, it will issue the -command @samp{ptelnet chessclub.com 5000} to connect to the ICS. - -Next, suppose that @samp{ptelnet chessclub.com 5000} doesn't work; -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. -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 -command line options as follows: - -@example -xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport "" -@end example - -@noindent -Then when you run XBoard in ICS mode, it will issue the -command @samp{ptelnet foo.edu} to connect to your account at -@samp{foo.edu}. Log in there, then type @samp{telnet chessclub.com 5000}. - -ICC timestamp and FICS timeseal do not work through some -firewalls. You can use them only if your firewall gives a clean TCP -connection with a full 8-bit wide path. If your firewall allows you -to get out only by running a special telnet program, you can't use -timestamp or timeseal across it. But if you have access to a -computer just outside your firewall, and you have much lower netlag -when talking to that computer than to the ICS, it might be worthwhile -running timestamp there. Follow the instructions above for hopping -through a host outside the firewall (foo.edu in the example), -but run timestamp or timeseal on that host instead of telnet. - -Suppose that you have a SOCKS firewall that will give you a clean -8-bit wide TCP connection to the chess server, but only after you -authenticate yourself via the SOCKS protocol. In that case, you could -make a socksified version of XBoard and run that. If you are using -timestamp or timeseal, you will to socksify it, not XBoard; this may -be difficult seeing that ICC and FICS do not provide source code for -these programs. Socksification is beyond the scope of this document, -but see the SOCKS Web site at http://www.socks.permeo.com/. -If you are missing SOCKS, try http://www.funbureau.com/. - -@node Environment -@chapter Environment variables -@cindex Environment variables -@cindex CHESSDIR -Game and position files are found in a directory named by the -@code{CHESSDIR} environment variable. If this variable is not set, the -current working directory is used. If @code{CHESSDIR} is set, -XBoard actually changes its working directory to -@code{$CHESSDIR}, so any files written by the chess engine -will be placed there too. - -@node Limitations -@chapter Limitations and known bugs -@cindex Limitations -@cindex Bugs -There is no way for two people running copies of XBoard to play -each other without going through an Internet Chess Server. - -Under some circumstances, your ICS password may be echoed when you log on. - -If you are connecting to the ICS by running telnet on an Internet -provider or firewall host, you may find that each line you type is -echoed back an extra time after you hit @key{Enter}. If your Internet -provider is a Unix system, you can probably turn its echo off by -typing @kbd{stty -echo} after you log in, and/or typing -@key{^E}@key{Enter} (Ctrl+E followed by the Enter key) to the telnet -program after you have logged into ICS. It is a good idea to do this -if you can, because the extra echo can occasionally confuse XBoard's -parsing routines. - -The game parser recognizes only algebraic notation. - -Many of the following points used to be limitations in XBoard 4.2.7 and earlier, -but are now fixed: -The internal move legality tester in XBoard 4.3.xx does look at the game history, -and is fully aware of castling or en-passant-capture rights. It permits castling with -the king on the d file because this is possible in some "wild 1" games on ICS. -The piece-drop menu does not check piece drops in bughouse to see if you actually hold -the piece you are trying to drop. But this way of dropping pieces should be considered -an obsolete feature, now that pieces can be dropped by dragging them from the holdings -to the board. Anyway, if you would attempt an illegal move when using a chess engine or the ICS, -XBoard will accept the error message that comes back, undo the move, and let you try another. -FEN positions saved by XBoard do include correct information about whether castling or -en passant are legal, and also handle the 50-move counter. -The mate detector does not understand that non-contact mate is not really mate in bughouse. -The only problem this causes while playing is minor: a "#" (mate indicator) character will -show up after a non-contact mating move in the move list. XBoard will not assume the game -is over at that point, not even when the option Detect Mates is on. -Edit Game mode always uses the rules of the selected variant, -which can be a variant that uses piece drops. -You can load and edit games that contain piece drops. -The (obsolete) piece menus are not active, -but you can perform piece drops by dragging pieces from the holdings. -Fischer Random castling is fully understood. -You can enter castlings by dragging the King on top of your Rook. -You can probably also play Fischer Random successfully on ICS by typing -castling moves into the ICS Interaction window. - -The menus may not work if your keyboard is in Caps Lock or Num Lock mode. -This seems to be a problem with the Athena menu widget, -not an XBoard bug. - -Also see the ToDo file included with the distribution for many other -possible bugs, limitations, and ideas for improvement that have been -suggested. -@node Problems -@chapter Reporting problems -@cindex Bugs -@cindex Bug reports -@cindex Reporting bugs -@cindex Problems -@cindex Reporting problems - -You can report bugs and problems with XBoard using -the bug tracker at @code{https://savannah.gnu.org/projects/xboard/} -or by sending mail to @code{}. It can also -be useful to report or discuss bugs in the WinBoard Forum at -@code{http://www.open-aurec.com/wbforum/}, -WinBoard development section. - -Please use the @file{script} program to start a typescript, run -XBoard with the @samp{-debug} option, and include the typescript -output in your message. -Also tell us what kind of machine and what operating system version -you are using. The command @samp{uname -a} will often tell you this. - -If you improve XBoard, please send a message about your changes, -and we will get in touch with you about merging them in -to the main line of development. - -@node Contributors -@chapter Authors and contributors -@cindex Authors -@cindex Contributors - -Chris Sears and Dan Sears wrote the original XBoard. They were -responsible for versions 1.0 through 1.2. The color scheme was taken -from Wayne Christopher's @code{XChess} program. - -Tim Mann was primarily responsible for XBoard versions 1.3 through -4.2.7, and for WinBoard (a port of XBoard to Microsoft Win32) from its -inception through version 4.2.7. - -John Chanak contributed the initial implementation of ICS mode. Evan -Welsh wrote @code{CMail}, and Patrick Surry helped in designing, -testing, and documenting it. Elmar Bartel contributed the new piece -bitmaps introduced in version 3.2. Jochen Wiedmann converted the -documentation to texinfo. Frank McIngvale added click/click moving, -the Analysis modes, piece flashing, ZIICS import, and ICS text -colorization to XBoard. Hugh Fisher added animated piece movement to -XBoard, and Henrik Gram added it to WinBoard. Mark Williams -contributed the initial (WinBoard-only) implementation of many new -features added to both XBoard and WinBoard in version 4.1.0, including -copy/paste, premove, icsAlarm, autoFlipView, training mode, auto -raise, and blindfold. Ben Nye contributed X copy/paste code for -XBoard. - -In a fork from version 4.2.7, Alessandro Scotti added many elements to -the user interface of WinBoard, including the board textures and -font-based rendering, the evaluation-graph, move-history and -engine-output window. He was also responsible for adding the UCI -support. - -H. G. Muller continued this fork of the project, producing version -4.3. He made WinBoard castling- and e.p.-aware, added variant support -with adjustable board sizes, the crazyhouse holdings, and the fairy -pieces. In addition he added most of the adjudication options, made -WinBoard more robust in dealing with buggy and crashing engines, and -extended time control with a time-odds and node-count-based modes. -Most of the options that initially were WinBoard only have now been -back-ported to XBoard. - -Michel van den Bergh provided the code for reading Polyglot opening books. - -Meanwhile, some work continued on the GNU XBoard project maintained at -savannah.gnu.org, but version 4.2.8 was never released. Daniel -Mehrmann was responsible for much of this work. - -Most recently, Arun Persaud worked with H. G. Muller to merge all -the features of the never-released XBoard/WinBoard 4.2.8 of the GNU -XBoard project and the never-released 4.3.16 from H. G.'s fork into a -unified XBoard/WinBoard 4.4, which is now available both from the -savannah.gnu.org web site and the WinBoard forum. - -@node CMail -@chapter CMail -@cindex cmail -The @file{cmail} program can help you play chess by email with opponents of -your choice using XBoard as an interface. - -You will usually run @file{cmail} without giving any options. - -@menu -* CMail options:: Invoking CMail. -* CMail game:: Starting a CMail game. -* CMail answer:: Answering a move. -* CMail multi:: Multiple games in one message. -* CMail completion:: Completing a game. -* CMail trouble:: Known CMail problems. -@end menu - -@node CMail options -@section CMail options -@table @asis -@item -h -Displays @file{cmail} usage information. -@item -c -Shows the conditions of the GNU General Public License. -@xref{Copying}. -@item -w -Shows the warranty notice of the GNU General Public License. -@xref{Copying}. -@item -v -@itemx -xv -Provides or inhibits verbose output from @file{cmail} and XBoard, -useful for debugging. The -@code{-xv} -form also inhibits the cmail introduction message. -@item -mail -@itemx -xmail -Invokes or inhibits the sending of a mail message containing the move. -@item -xboard -@itemx -xxboard -Invokes or inhibits the running of XBoard on the game file. -@item -reuse -@itemx -xreuse -Invokes or inhibits the reuse of an existing XBoard to display the -current game. -@item -remail -Resends the last mail message for that game. This inhibits running -XBoard. -@item -game -The name of the game to be processed. -@item -wgames -@itemx -bgames -@itemx -games -Number of games to start as White, as Black or in total. Default is 1 as -white and none as black. If only one color is specified then none of the -other color is assumed. If no color is specified then equal numbers of -White and Black games are started, with the extra game being as White if an -odd number of total games is specified. -@item -me -@itemx -opp -A one-word alias for yourself or your opponent. -@item -wname -@itemx -bname -@itemx -myname -@itemx -oppname -The full name of White, Black, yourself or your opponent. -@item -wna -@itemx -bna -@itemx -na -@itemx -oppna -The email address of White, Black, yourself or your opponent. -@item -dir -The directory in which @file{cmail} keeps its files. This defaults to the -environment variable @code{$CMAIL_DIR} or failing that, @code{$CHESSDIR}, -@file{$HOME/Chess} or @file{~/Chess}. It will be created if it does not exist. -@item -arcdir -The directory in which @file{cmail} archives completed games. Defaults to -the environment variable @code{$CMAIL_ARCDIR} or, in its absence, the same -directory as cmail keeps its working files (above). -@item -mailprog -The program used by cmail to send email messages. This defaults to the -environment variable @code{$CMAIL_MAILPROG} or failing that -@file{/usr/ucb/Mail}, @file{/usr/ucb/mail} or @file{Mail}. You will need -to set this variable if none of the above paths fit your system. -@item -logFile -A file in which to dump verbose debugging messages that are invoked with -the @samp{-v} -option. -@item -event -The PGN Event tag (default @samp{Email correspondence game}). -@item -site -The PGN Site tag (default @samp{NET}). -@item -round -The PGN Round tag (default @samp{-}, not applicable). -@item -mode -The PGN Mode tag (default @samp{EM}, Electronic Mail). -@item Other options -Any option flags not listed above are passed through to XBoard. -Invoking XBoard through CMail changes the default values of two XBoard -options: The default value for @samp{-noChessProgram} is changed to -true; that is, by default no chess engine is started. The default -value for @samp{-timeDelay} is changed to 0; that is, by default -XBoard immediately goes to the end of the game as played so far, -rather than stepping through the moves one by one. You can still set -these options to whatever values you prefer by supplying them on -CMail's command line. @xref{Options}. -@end table - -@node CMail game -@section Starting a CMail Game -Type @file{cmail} from a shell to start a game as white. After an opening -message, you will be prompted for a game name, which is optional---if you -simply press @key{Enter}, the game name will take the form -@samp{you-VS-opponent}. You will next be prompted for the short name -of your opponent. If you haven't played this person before, you will also -be prompted for his/her email address. @file{cmail} will then invoke -XBoard in the background. Make your first move and select -@samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. If all is well, -@file{cmail} will mail a copy of the move to your opponent. If you select -@samp{Exit} without having selected @samp{Mail Move} then no move will be -made. - -@node CMail answer -@section Answering a Move -When you receive a message from an opponent containing a move in one of -your games, simply pipe the message through @file{cmail}. In some mailers -this is as simple as typing @kbd{| cmail} when viewing the message, while in -others you may have to save the message to a file and do @kbd{cmail < file} -at the command line. In either case @file{cmail} will display the game using -XBoard. If you didn't exit XBoard when you made your first move -then @file{cmail} will do its best to use the existing XBoard instead -of starting a new one. As before, simply make a move and select -@samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. @file{cmail} -will try to use the -XBoard that was most recently used to display the current game. This -means that many games can be in progress simultaneously, each with its own -active XBoard. - -If you want to look at the history or explore a variation, go ahead, but -you must return to the current position before XBoard will allow you -to mail a move. If you edit the game's history you must select -@samp{Reload Same Game} from the @samp{File} menu to get back to the original -position, then make the move you want and select @samp{Mail Move}. -As before, if you decide you aren't ready to make a move just yet you can -either select @samp{Exit} without sending a move or just leave -XBoard running until you are ready. - -@node CMail multi -@section Multi-Game Messages - -It is possible to have a @file{cmail} message carry more than one game. -This feature was implemented to handle IECG (International Email Chess -Group) matches, where a match consists of one game as white and one as black, -with moves transmitted simultaneously. In case there are more general uses, -@file{cmail} itself places no limit on the number of black/white games -contained in a message; however, XBoard does. - -@node CMail completion -@section Completing a Game -Because XBoard can detect checkmate and stalemate, @file{cmail} -handles game termination sensibly. As well as resignation, the -@samp{Action} menu allows draws to be offered and accepted for -@file{cmail} games. - -For multi-game messages, only unfinished and just-finished games will be -included in email messages. When all the games are finished, they are -archived in the user's archive directory, and similarly in the opponent's -when he or she pipes the final message through @file{cmail}. The archive -file name includes the date the game was started. - -@node CMail trouble -@section Known CMail Problems -It's possible that a strange conjunction of conditions may occasionally -mean that @file{cmail} has trouble reactivating an existing -XBoard. If this should happen, simply trying it again should work. -If not, remove the file that stores the XBoard's PID -(@file{game.pid}) or use the @samp{-xreuse} option to force -@file{cmail} to start a new XBoard. - -Versions of @file{cmail} after 2.16 no longer understand the old file format -that XBoard used to use and so cannot be used to correspond with -anyone using an older version. - -Versions of @file{cmail} older than 2.11 do not handle multi-game messages, -so multi-game correspondence is not possible with opponents using an older -version. - -@node Other programs -@chapter Other programs you can use with XBoard -@cindex Other programs - -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. -@end menu - -@node GNU Chess -@section GNU Chess - -The GNU Chess engine is available from: - -ftp://ftp.gnu.org/gnu/gnuchess/ - -You can use XBoard to play a game against GNU Chess, or to -interface GNU Chess to an ICS. - -@node Fairy-Max -@section Fairy-Max - -Fairy-Max is a derivative from the once World's smallest Chess program micro-Max, -which measures only about 100 lines of source code. -The main difference with micro-Max is that Fairy-Max loads its move-generator -tables from a file, so that the rules for piece movement can be easily configured -to implement unorthodox pieces. -Fairy-Max can therefore play a large number of variants, normal Chess being one of those. -In addition it plays Knightmate, Capablanca and Gothic Chess, Shatranj, Courier Chess, -Cylinder chess, Berolina Chess, while the user can easily define new variants. -It can be obtained from: - -http://home.hccnet.nl/h.g.muller/dwnldpage.html - -@node HoiChess -@section HoiChess - -HoiChess is a not-so-very-strong Chess engine, which comes with a derivative HoiXiangqi, -able to play Chinese Chess. It can be obtained from the standard Linux repositories -through: - -sudo apt-get install hoichess - -@node Crafty -@section Crafty - -Crafty is a chess engine written by Bob Hyatt. -You can use XBoard to play a game against Crafty, hook Crafty up -to an ICS, or use Crafty to interactively analyze games and positions -for you. - -Crafty is a strong, rapidly evolving chess program. This rapid -pace of development is good, because it means Crafty is always -getting better. This can sometimes cause problems with -backwards compatibility, but usually the latest version of Crafty -will work well with the latest version of XBoard. -Crafty can be obtained from its author's FTP site: -ftp://ftp.cis.uab.edu/hyatt/. - -To use Crafty with XBoard, give the -fcp and -fd options as follows, where - is the directory in which you installed Crafty -and placed its book and other support files. - -@ifnottex -@node Copyright -@unnumbered Copyright -@include copyright.texi -@end ifnottex - -@node Copying -@unnumbered GNU GENERAL PUBLIC LICENSE -@include gpl.texinfo - -@c noman -@node Index -@unnumbered Index - -@printindex cp -@contents -@c end noman - -@bye