1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename xboard.info 4@settitle XBoard 5@c %**end of header 6 7@include version.texi 8 9@ifinfo 10@format 11INFO-DIR-SECTION Games 12START-INFO-DIR-ENTRY 13* xboard: (xboard). An X Window System graphical chessboard. 14END-INFO-DIR-ENTRY 15@end format 16@end ifinfo 17 18@titlepage 19@title XBoard 20 21@page 22@vskip 0pt plus 1filll 23@include copyright.texi 24 25@end titlepage 26@ifset man 27.TH xboard 6 "$Date: " "GNU" 28.SH NAME 29.PP 30xboard @- X graphical user interface for chess 31.SH SYNOPSIS 32.PP 33.B xboard [options] 34.br 35.B xboard -ics -icshost hostname [options] 36.br 37.B xboard -ncp [options] 38.br 39.B |pxboard 40.br 41.B cmail [options] 42@end ifset 43 44@node Top 45@top Introduction 46@cindex introduction 47 48@ifset man 49.SH DESCRIPTION 50@end ifset 51 52XBoard is a graphical chessboard that can serve as a 53user interface to chess engines (such as GNU Chess), the 54Internet Chess Servers, 55electronic mail correspondence chess, or your own collection of saved games. 56 57This manual documents version @value{VERSION} of XBoard. 58 59@menu 60* Major modes:: The main things XBoard can do. 61* Basic operation:: Mouse and keyboard functions. 62* Menus:: Menus, buttons, and keys. 63* Options:: Command options supported by XBoard. 64* Chess Servers:: Using XBoard with an Internet Chess Server (ICS). 65* Firewalls:: Connecting to a chess server through a firewall. 66* Environment:: Environment variables. 67* Limitations:: Known limitations and/or bugs. 68* Problems:: How and where to report any problems you run into. 69* Contributors:: People who have helped developing XBoard. 70* CMail:: Using XBoard for electronic correspondence chess. 71* Other programs:: Other programs you can use with XBoard. 72@ifnottex 73* Copyright:: Copyright notice for this manual. 74@end ifnottex 75* Copying:: The GNU General Public License. 76 77* Index:: Index of concepts and symbol names. 78@end menu 79 80@node Major modes 81@chapter Major modes 82@cindex Major modes 83 84XBoard always runs in one of four major modes. You select the 85major mode from the command line when you start up XBoard. 86 87@table @asis 88@item xboard [options] 89As an interface to GNU Chess or another chess engine running on your 90machine, XBoard lets you play a game against the machine, 91set up arbitrary positions, force variations, watch a game between two 92chess engines, interactively analyze your stored games or set up and 93analyze arbitrary positions. 94To run engines that use the UCI standard XBoard will draw upon 95the Polyglot adapter fully transparently, but you will need to have 96the polyglot package installed for this to work. 97@item xboard -ics -icshost hostname [options] 98As Internet Chess Server (ICS) interface, XBoard 99lets you play against other ICS users, observe games 100they are playing, or review games that have recently finished. Most 101of the ICS "wild" chess variants are supported, including bughouse. 102@item xboard -ncp [options] 103XBoard can also be used simply 104as an electronic chessboard to play through games. It will read and 105write game files and allow you to play through variations 106manually. You can use it to browse games off the net or review games 107you have saved. These features are also available in the other modes. 108@item |pxboard 109If you want to pipe games into XBoard, use the supplied shell 110script @file{pxboard}. For example, from the news reader @file{xrn}, 111find a message with one or more games in it, click the Save button, 112and type @samp{|pxboard} as the file name. 113@item cmail [options] 114As an interface to electronic mail correspondence chess, XBoard 115works with the cmail program. See @ref{CMail} below for 116instructions. 117@end table 118 119@node Basic operation 120@chapter Basic operation 121@cindex Basic operation 122 123To move a piece, you can drag it with the left mouse button, or you 124can click the left mouse button once on the piece, then once more on 125the destination square. To under-promote a Pawn you can drag it backwards 126until it morphs into the piece you want to promote to, after which you 127drag that forward to the promotion square. 128Or after selecting the pawn with a first click you can then click 129the promotion square and move the mouse while keeping the button down 130until the piece that you want appears in the promotion square. 131To castle you move the King to its destination or, in Chess960, 132on top of the Rook you want to castle with. 133In crazyhouse, bughouse or shogi you can 134drag and drop pieces to the board from the holdings squares 135displayed next to the board. 136 137Old behavior, where right-clicking a square brings up a menu 138where you can select what piece to drop on it can still be 139selected through the @samp{Drop Menu} option. 140Only in Edit Position mode right and middle clicking a square is still used to 141put a piece on it, and the piece to drop is selected by sweeping 142the mouse vertically with the button held down. 143 144The default function of the right mouse button in other modes is 145to display the position the chess program thinks it will end up in. 146While moving the mouse vertically with this button pressed 147XBoard will step through the principal variation to show how 148this position will be reached. 149Lines of play displayed in the engine-output window, 150or PGN variations in the comment window can similarly 151be played out on the board, by right-clicking on them. 152Only in Analysis mode, when you walk along a PV, 153releasing the mouse button might forward the game upto that point, 154like you entered all previous PV moves. 155As the display of the PV in that case starts after the first move 156a simple right-click will play the move the engine indicates. 157 158In Analysis mode you can also make a move by grabbing the piece 159with a double-click of the left mouse button 160(or while keeping the @kbd{Ctrl} key pressed). 161In this case the move you enter will not be played, 162but will be excluded from the analysis of the current position. 163(Or included if it was already excluded; it is a toggle.) 164This only works for engines that support this feature. 165 166When connected to an ICS, it is possible to call up a graphical 167representation of players seeking a game in stead of the chess board, 168when the latter is not in use 169(i.e. when you are not playing or observing). 170Left-clicking the display area will switch between this 'seek graph' 171and the chess board. 172Hovering the mouse pointer over a dot will show the details of the 173seek ad in the message field above the board. 174Left-clicking the dot will challenge that player. 175Right-clicking a dot will 'push it to the back', 176to reveal any dots that were hidden behind it. 177Right-clicking off dots will refresh the graph. 178 179Most other XBoard commands are available from the menu bar. The most 180frequently used commands also have shortcut keys or on-screen buttons. 181These shortcut keystrokes are mostly non-printable characters. 182Typing a letter or digit while the board window has focus 183will bring up a type-in box with the typed letter already in it. 184You can use that to type a move in situations where it is your 185turn to enter a move, 186type a move number to call up the position after that move 187in the display, 188or, in Edit Position mode, type a FEN. 189Some rarely used parameters can only be set through options on the 190command line used to invoke XBoard. 191 192XBoard uses a settings file, in which it can remember any changes to 193the settings that are made through menus or command-line options, 194so they will still apply when you restart XBoard for another session. 195The settings can be saved into this file automatically when XBoard exits, 196or on explicit request of the user. 197Note that the board window can be sized by the user, but that this 198will not affect the size of the clocks above it, and won't be remembered 199in the settings file. 200To persistently change the size of the clocks, use the @code{size} 201command-line option when starting XBoard. 202The default name for the settings file is /etc/xboard/xboard.conf, 203but in a standard install this file is only used as a master settings 204file that determines the system-wide default settings, 205and defers reading and writing of user settings to a user-specific 206file like ~/.xboardrc in the user's home directory. 207 208When XBoard is iconized, its graphical icon is a white knight if 209it is White's turn to move, a black knight if it is Black's turn. 210 211@node Menus 212@chapter Menus, buttons, and keys 213@cindex Menus 214 215@menu 216* File Menu:: Accessing external games and positions. 217* Edit Menu:: Altering games, positions, PGN tags or comments. 218* View Menu:: Controlling XBoard's shape and looks. 219* Mode Menu:: Selecting XBoard's mode. 220* Action Menu:: Talking to the chess engine or ICS opponents. 221* Engine Menu:: Controlling settings and actions of the engine(s). 222* Options Menu:: User preferences. 223* Help Menu:: Getting help. 224* Keys:: Other shortcut keys. 225@end menu 226 227@node File Menu 228@section File Menu 229@cindex File Menu 230@cindex Menu, File 231@table @asis 232@item New Game 233@cindex New Game, Menu Item 234Resets XBoard and the chess engine to the beginning of a new chess 235game. The @kbd{Ctrl-N} key is a keyboard equivalent. In Internet Chess 236Server mode, clears the current state of XBoard, then 237resynchronizes with the ICS by sending a refresh command. If you want to 238stop playing, observing, or examining an ICS game, use an 239appropriate command from the Action menu, not @samp{New Game}. 240@xref{Action Menu}. 241@item New Shuffle Game 242@cindex New Shuffle Game, Menu Item 243Similar to @samp{New Game}, but allows you to specify a particular initial position 244(according to a standardized numbering system) 245in chess variants which use randomized opening positions (e.g. Chess960). 246@item shuffle 247@cindex shuffle, Menu Item 248Ticking @samp{shuffle} will cause the current variant to be played 249with shuffled initial position. 250Shuffling will preserve the possibility to castle in the way allowed by the variant. 251@item Fischer castling 252@cindex Fischer castling, menu item 253Ticking @samp{Fischer castling} will allow castling with Kings and Rooks 254that did not start in their normal place, as in Chess960. 255@item Start-position number 256@itemx randomize 257@itemx pick fixed 258@cindex randomize, Menu Item 259@cindex pick fixed, Menu Item 260@cindex Start-position number, Menu Item 261The @samp{Start-position number} selects a particular start position 262from all allowed shufflings, which will then be used for every new game. 263Setting this to -1 (which can be done by pressing the @samp{randomize} button) 264will cause a fresh random position to be picked for every new game. 265Pressing the @samp{pick fixed} button causes @samp{Start-position number} 266to be set to a random value, to be used for all subsequent games. 267@item New Variant 268@cindex New variant, Menu Item 269Allows you to select a new chess variant in non-ICS mode. 270(In ICS play, the ICS is responsible for deciding which variant will be played, 271and XBoard adapts automatically.) The shifted @kbd{Alt+V} key is a 272keyboard equivalent. If you play with an engine, the engine must 273be able to play the selected variant, or the corresponding choice will be disabled. 274XBoard supports all major variants, such as xiangqi, shogi, chess, chess960, 275makruk, Capablanca Chess, shatranj, crazyhouse, bughouse. 276 277You can overrule the default board format of the selected variant, 278(e.g. to play suicide chess on a 6 x 6 board), 279in this dialog, but normally you would not do that, 280and leave them at '-1', which means 'default' for the chosen variant. 281@item Load Game 282@cindex Load Game, Menu Item 283Plays a game from a record file. The @kbd{Ctrl-O} key is a keyboard equivalent. 284A pop-up dialog prompts you for the file name. If the file contains more 285than one game, a second pop-up dialog 286displays a list of games (with information drawn from their PGN tags, if 287any), and you can select the one you want. Alternatively, you can load the 288Nth game in the file directly, by typing the number @kbd{N} after the 289file name, separated by a space. 290 291The game-file parser will accept PGN (portable game notation), 292or in fact almost any file that contains moves in algebraic 293notation. 294Notation of the form @samp{P@@f7} 295is accepted for piece-drops in bughouse games; 296this is a nonstandard extension to PGN. 297If the file includes a PGN position (FEN tag), or an old-style 298XBoard position diagram bracketed by @samp{[--} and @samp{--]} 299before the first move, the game starts from that position. Text 300enclosed in parentheses, square brackets, or curly braces is assumed to 301be commentary and is displayed in a pop-up window. Any other 302text in the file is ignored. PGN variations (enclosed in 303parentheses) also are treated as comments; 304however, if you rights-click them in the comment window, 305XBoard will shelve the current line, and load the the selected variation, 306so you can step through it. 307You can later revert to the previous line with the @samp{Revert} command. 308This way you can walk quite complex varation trees with XBoard. 309The nonstandard PGN tag [Variant "varname"] functions similarly to 310the -variant command-line option (see below), allowing games in certain chess 311variants to be loaded. 312Note that it must appear before any FEN tag for XBoard to recognize 313variant FENs appropriately. 314There is also a heuristic to 315recognize chess variants from the Event tag, by looking for the strings 316that the Internet Chess Servers put there when saving variant ("wild") games. 317@item Load Position 318@cindex Load Position, Menu Item 319Sets up a position from a position file. A pop-up dialog prompts 320you for the file name. The shifted @kbd{Ctrl-O} key is a keyboard 321equivalent. If the file contains more than one saved 322position, and you want to load the Nth one, type the number N 323after the file name, separated by a space. Position files must 324be in FEN (Forsythe-Edwards notation), or in the format that the 325Save Position command writes when oldSaveStyle is turned on. 326@item Load Next Position 327@cindex Load Next Position, Menu Item 328Loads the next position from the last position file you loaded. 329The shifted @kbd{PgDn} key is a keyboard equivalent. 330@item Load Previous Position 331@cindex Load Previous Position, Menu Item 332Loads the previous position from the last position file you 333loaded. The shifted @kbd{PgUp} key is a keyboard equivalent. 334Not available if the last position was loaded from a pipe. 335@item Save Game 336@cindex Save Game, Menu Item 337Appends a record of the current game to a file. 338The @kbd{Ctrl-S} key is a keyboard equivalent. 339A pop-up dialog 340prompts you for the file name. If the game did not begin with 341the standard starting position, the game file includes the 342starting position used. Games are saved in the PGN (portable 343game notation) format, unless the oldSaveStyle option is true, 344in which case they are saved in an older format that is specific 345to XBoard. Both formats are human-readable, and both can be 346read back by the @samp{Load Game} command. 347Notation of the form @samp{P@@f7} 348is accepted for piece-drops in bughouse games; 349this is a nonstandard extension to PGN. 350@item Save Position 351@cindex Save Position, Menu Item 352Appends a diagram of the current position to a file. 353The shifted @kbd{Ctrl+S} key is a keyboard equivalent. 354A pop-up dialog prompts you for the file name. Positions are saved in 355FEN (Forsythe-Edwards notation) format unless the @code{oldSaveStyle} 356option is true, in which case they are saved in an older, 357human-readable format that is specific to XBoard. Both formats 358can be read back by the @samp{Load Position} command. 359@item Save Selected Games 360@cindex Save Selected Games 361Will cause all games selected for display in the current Game List 362to be appended to a file of the user's choice. 363@item Save Games as Book 364@cindex Save Games as Book, Menu Item 365Creates an opening book from the currently loaded game file, 366incorporating only the games currently selected in the Game List. 367The book will be saved on the file specified in the @samp{Common Engine} 368options dialog. 369The value of @samp{Book Depth} specified in that same dialog will 370be used to determine how many moves of each game will be added to 371the internal book buffer. 372This command can take a long time to process, 373and the size of the buffer is currently limited. 374At the end the buffer will be saved as a Polyglot book, 375but the buffer will not be cleared, 376so that you can continue adding games from other game files. 377@item Mail Move 378@itemx Reload CMail Message 379@cindex Mail Move, Menu Item 380@cindex Reload CMail Message, Menu Item 381See @ref{CMail}. 382@item Exit 383@cindex Exit, Menu Item 384Exits from XBoard. The @kbd{Ctrl-Q} key is a keyboard equivalent. 385@end table 386 387@node Edit Menu 388@section Edit Menu 389@cindex Menu, Edit 390@cindex Edit Menu 391@table @asis 392@item Copy Game 393@cindex Copy Game, Menu Item 394Copies a record of the current game to an internal clipboard in PGN 395format and sets the X selection to the game text. The @kbd{Ctrl-C} 396key is a keyboard equivalent. The game can be 397pasted to another application (such as a text editor or another copy 398of XBoard) using that application's paste command. In many X 399applications, such as xterm and emacs, the middle mouse button can be 400used for pasting; in XBoard, you must use the Paste Game command. 401@item Copy Position 402@cindex Copy Position, Menu Item 403Copies the current position to an internal clipboard in FEN format and 404sets the X selection to the position text. The shifted @kbd{Ctrl-C} key 405is a keyboard equivalent. The position can be pasted 406to another application (such as a text editor or another copy of 407XBoard) using that application's paste command. In many X 408applications, such as xterm and emacs, the middle mouse button can be 409used for pasting; in XBoard, you must use the Paste Position command. 410@item Copy Game List 411@cindex Copy Game List, Menu Item 412Copies the current game list to the clipboard, 413and sets the X selection to this text. 414A format of comma-separated double-quoted strings is used, 415including all tags, 416so it can be easily imported into spread-sheet programs. 417@item Paste Game 418@cindex Paste Game, Menu Item 419Interprets the current X selection as a game record and loads it, as 420with Load Game. The @kbd{Ctrl-V} key is a keyboard equivalent. 421@item Paste Position 422@cindex Paste Position, Menu Item 423Interprets the current X selection as a FEN position and loads it, as 424with Load Position. The shifted @kbd{Ctrl-V} key is a keyboard equivalent. 425@item Edit Game 426@cindex Edit Game, Menu Item 427Allows you to make moves for both Black and White, and to change 428moves after backing up with the @samp{Backward} command. The clocks do 429not run. The @kbd{Ctrl-E} key is a keyboard equivalent. 430 431In chess engine mode, the chess engine continues to check moves for legality 432but does not participate in the game. You can bring the chess engine 433into the game by selecting @samp{Machine White}, @samp{Machine Black}, 434or @samp{Two Machines}. 435 436In ICS mode, the moves are not sent to the ICS: @samp{Edit Game} takes 437XBoard out of ICS Client mode and lets you edit games locally. 438If you want to edit games on ICS in a way that other ICS users 439can see, use the ICS @kbd{examine} command or start an ICS match 440against yourself. 441@item Edit Position 442@cindex Edit Position, Menu Item 443Lets you set up an arbitrary board position. 444The shifted @kbd{Ctrl-E} key is a keyboard equivalent. 445Use mouse button 1 to drag pieces to new squares, or to delete a piece 446by dragging it off the board or dragging an empty square on top of it. 447When you do this keeping the @kbd{Ctrl} key pressed, 448or start dragging with a double-click, 449you will move a copy of the piece, leaving the piece itself where it was. 450In variants where pieces can promote (such as Shogi), 451left-clicking an already selected piece promotes or demotes it. 452To drop a new piece on a square, press mouse button 2 or 3 over the 453square. 454This puts a white or black pawn in the square, respectively, 455but you can change that to any other piece type by dragging the 456mouse down before you release the button. 457You will then see the piece on the originally clicked square 458cycle through the available pieces 459(including those of opposite color), 460and can release the button when you see the piece you want. 461(Note you can swap the function of button 2 and 3 by pressing 462the shift key, and that there is an option @code{monoMouse} 463to combine al functions in one button, which then acts as 464button 3 over an empty square, and as button 1 over a piece.) 465To alter the side to move, you can click the clock 466(the words White and Black above the board) 467of the side you want to give the move to. 468To clear the board you can click the clock of the side that 469already has the move (which is highlighted in black). 470If you repeat this the board will cycle from empty to a 471@code{pallette board} containing every piece once to the initial 472position to the one before clearing. 473The quickest way to set up a position is usually to start 474with the pallette board, and move the pieces to were you 475want them, duplicating them where necessary by using the 476@kbd{Ctrl} key, dragging those you don't want off board, 477and use static button 2 or 3 clicks to place the Pawns. 478The old behavior with a piece menu can still be configured 479with the aid of the @code{pieceMenu} option. 480Dragging empty squares off board can create boards with 481holes (inaccessible black squares) in them. 482Selecting @samp{Edit Position} causes XBoard to discard 483all remembered moves in the current game. 484 485In ICS mode, changes made to the position by @samp{Edit Position} are 486not sent to the ICS: @samp{Edit Position} takes XBoard out of 487@samp{ICS Client} mode and lets you edit positions locally. If you want to 488edit positions on ICS in a way that other ICS users can see, use 489the ICS @kbd{examine} command, or start an ICS match against yourself. 490(See also the ICS Client topic above.) 491@item Edit Tags 492@cindex Edit Tags, Menu Item 493Lets you edit the PGN (portable game notation) 494tags for the current game. After editing, the tags must still conform to 495the PGN tag syntax: 496 497@example 498<tag-section> ::= <tag-pair> <tag-section> 499 <empty> 500<tag-pair> ::= [ <tag-name> <tag-value> ] 501<tag-name> ::= <identifier> 502<tag-value> ::= <string> 503@end example 504@noindent 505See the PGN Standard for full details. Here is an example: 506 507@example 508[Event "Portoroz Interzonal"] 509[Site "Portoroz, Yugoslavia"] 510[Date "1958.08.16"] 511[Round "8"] 512[White "Robert J. Fischer"] 513[Black "Bent Larsen"] 514[Result "1-0"] 515@end example 516@noindent 517Any characters that do not match this syntax are silently ignored. Note that 518the PGN standard requires all games to have at least the seven tags shown 519above. Any that you omit will be filled in by XBoard 520with @samp{?} (unknown value), or @samp{-} (inapplicable value). 521@item Edit Comment 522@cindex Edit Comment, Menu Item 523Adds or modifies a comment on the current position. Comments are 524saved by @samp{Save Game} and are displayed by @samp{Load Game}, 525PGN variations will also be printed in this window, 526and can be promoted to main line by right-clicking them. 527@samp{Forward}, and @samp{Backward}. 528@item Edit Book 529@cindex Edit Book, Menu Item 530Pops up a window listing the moves available in the GUI book 531(specified in the @samp{Common Engine Settings} dialog) 532from the currently displayed position, 533together with their weights and (optionally in braces) learn info. 534You can then edit this list, and the new list will be stored 535back into the book when you press 'save changes'. 536When you press the button 'add next move', and play a move 537on the board, that move will be added to the list with weight 1. 538Note that the listed percentages are neither used, nor updated when 539you change the weights; they are just there as an optical aid. 540When you right-click a move in the list it will be played. 541@item Revert 542@itemx Annotate 543@cindex Revert, Menu Item 544@cindex Annotate, Menu Item 545If you are examining an ICS game and Pause mode is off, 546Revert issues the ICS command @samp{revert}. 547In local mode, when you were editing or analyzing a game, 548and the @code{-variations} command-line option is switched on, 549you can start a new variation by holding the Shift key down while 550entering a move not at the end of the game. 551Variations can also become the currently displayed line by 552clicking a PGN variation displayed in the Comment window. 553This can be applied recursively, 554so that you can analyze variations on variations; 555each time you create a new variation by entering an alternative move 556with Shift pressed, or select a new one from the Comment window, 557the current variation will be shelved. 558@samp{Revert} allows you to return to the most recently shelved variation. 559The difference between @samp{Revert} and @samp{Annotate} 560is that with the latter, 561the variation you are now abandoning will be added as a comment 562(in PGN variation syntax, i.e. between parentheses) 563to the original move where you deviated, for later recalling. 564The @kbd{Home} key is a keyboard equivalent to @samp{Revert}. 565@item Truncate Game 566@cindex Truncate Game, Menu Item 567Discards all remembered moves of the game beyond the current 568position. Puts XBoard into @samp{Edit Game} mode if it was not there 569already. 570The @kbd{End} key is a keyboard equivalent. 571@item Backward 572@itemx < 573@cindex Backward, Menu Item 574@cindex <, Button 575Steps backward through a series of remembered moves. 576The @samp{[<]} button and the @kbd{Alt+LeftArrow} key are equivalents, 577as is turning the mouse wheel towards you. 578In addition, pressing the ??? key steps back one move, and releasing 579it steps forward again. 580 581In most modes, @samp{Backward} only lets you look back at old positions; 582it does not retract moves. This is the case if you are playing against 583a chess engine, playing or observing a game on an ICS, or loading a game. 584If you select @samp{Backward} in any of these situations, you will not 585be allowed to make a different move. Use @samp{Retract Move} or 586@samp{Edit Game} if you want to change past moves. 587 588If you are examining an ICS game, the behavior of @samp{Backward} 589depends on whether XBoard is in Pause mode. If Pause mode is 590off, @samp{Backward} issues the ICS backward command, which backs up 591everyone's view of the game and allows you to make a different 592move. If Pause mode is on, @samp{Backward} only backs up your local 593view. 594@item Forward 595@itemx > 596@cindex Forward, Menu Item 597@cindex >, Button 598Steps forward through a series of remembered moves (undoing the 599effect of @samp{Backward}) or forward through a game file. The 600@samp{[>]} button and the @kbd{Alt+RightArrow} key are equivalents, 601as is turning the mouse wheel away from you. 602 603If you are examining an ICS game, the behavior of Forward 604depends on whether XBoard is in Pause mode. If Pause mode is 605off, @samp{Forward} issues the ICS forward command, which moves 606everyone's view of the game forward along the current line. If 607Pause mode is on, @samp{Forward} only moves your local view forward, 608and it will not go past the position that the game was in when 609you paused. 610@item Back to Start 611@itemx << 612@cindex Back to Start, Menu Item 613@cindex <<, Button 614Jumps backward to the first remembered position in the game. 615The @samp{[<<]} button and the @kbd{Alt+Home} key are equivalents. 616 617In most modes, Back to Start only lets you look back at old 618positions; it does not retract moves. This is the case if you 619are playing against a local chess engine, playing or observing a game on 620a chess server, or loading a game. If you select @samp{Back to Start} in any 621of these situations, you will not be allowed to make different 622moves. Use @samp{Retract Move} or @samp{Edit Game} if you want to change past 623moves; or use Reset to start a new game. 624 625If you are examining an ICS game, the behavior of @samp{Back to 626Start} depends on whether XBoard is in Pause mode. If Pause mode 627is off, @samp{Back to Start} issues the ICS @samp{backward 999999} 628command, which backs up everyone's view of the game to the start and 629allows you to make different moves. If Pause mode is on, @samp{Back 630to Start} only backs up your local view. 631@item Forward to End 632@itemx >> 633@cindex Forward to End, Menu Item 634@cindex >>, Button 635Jumps forward to the last remembered position in the game. The 636@samp{[>>]} button and the @kbd{Alt+End} key are equivalents. 637 638If you are examining an ICS game, the behavior of @samp{Forward to 639End} depends on whether XBoard is in Pause mode. If Pause mode 640is off, @samp{Forward to End} issues the ICS @samp{forward 999999} 641command, which moves everyone's view of the game forward to the end of 642the current line. If Pause mode is on, @samp{Forward to End} only moves 643your local view forward, and it will not go past the position 644that the game was in when you paused. 645@end table 646 647@node View Menu 648@section View Menu 649@cindex Menu, View 650@cindex View Menu 651@table @asis 652@item Flip View 653@cindex Flip View, Menu Item 654Inverts your view of the chess board for the duration of the 655current game. Starting a new game returns the board to normal. 656The @kbd{F2} key is a keyboard equivalent. 657@item Show Engine Output 658@cindex Show Engine Output, Menu Item 659Shows or hides a window in which the thinking output of any loaded engines 660is displayed. The shifted @kbd{Alt+O} key is a keyboard equivalent. 661XBoard will display lines of thinking output of the same depth ordered by score, 662(highest score on top), rather than in the order the engine produced them. 663Usually this amounts to the same, as a normal engine search will only find new PV 664(and emit it as thinking output) 665when it searches a move with a higher score than the previous variation. 666But when the engine is in multi-variation mode this needs not always be true, 667and it is more convenient for someone analyzing games to see the moves sorted by score. 668The order in which the engine found them is only of interest to the engine author, 669and can still be deduced from the time or node count printed with the line. 670Right-clicking a line in this window, and then moving the mouse vertically with the 671right button kept down, will make XBoard play through the PV listed there. 672The use of the board window as 'variation board' will normally end when 673you release the right button, 674or when the opponent plays a move. 675But beware: in Analysis mode, moves thus played out might be added to the game, 676depending on the setting of the option 'Play moves of clicked PV', 677when you initiate the click left of the PV in the score area. 678The Engine-Output pane for each engine will contain a header displaying the 679multi-PV status and a list of excluded moves in Analysis mode, 680which are also responsive to right-clicking: 681Clicking the words 'fewer' or 'more' will alter the number of variations 682shown at each depth, through the engine's MultiPV option, 683while clicking in between those and moving the mouse horizontally adjust 684the option 'Multi-PV Margin'. (In so far the engines support those.) 685@item Show Move History 686@cindex Show Move History, Menu Item 687Shows or hides a list of moves of the current game. 688The shifted @kbd{Alt+H} key is a keyboard equivalent. 689This list allows you to move the display to any earlier position in the game 690by clicking on the corresponding move. 691@item Show Evaluation Graph 692@cindex Show Evaluation Graph, Menu Item 693Shows or hides a window which displays a graph of how the engine score(s) 694evolved as a function of the move number. 695The shifted @kbd{Alt+E} key is a keyboard equivalent. 696The title bar shows the score (and search depth at which it was obtained) 697of the currently displayed position numerically. 698Clicking on the graph will bring 699the corresponding position in the board display. 700A button 3 click will toggle the display mode between plain and differential 701(showing the difference in score between successive half moves). 702Using the mouse wheel over the window will change the scale of the 703low-score region (from -1 to +1). 704@item Show Game List 705@cindex Show Game List, Menu Item 706Shows or hides the list of games generated by the last @samp{Load Game} 707command. The shifted @kbd{Alt+G} key is a keyboard equivalent. 708The line describing each game is built from a selection of the PGN tags. 709Which tags contribute, and in what order, can be changed by the @samp{Game list tags} 710menu dialog, which can be popped up through the @samp{Tags} button below the Game List. 711Display can be restricted to a sub-set of the games meeting certain criteria. 712A text entry below the game list allows you to type a text that the game lines 713must contain in order to be displayed. 714Games can also be selected based on their Elo PGN tag, 715as set in the @samp{Load Game Options} dialog, which can be popped up through the 716@samp{Thresholds} button below the Game List. 717Finally they can be selected based on containing a position similar to the one 718currently displayed in the main window, by pressing the 'Position' button below 719the Game List, (which searches the entire list for the position), or the 'Narrow' 720button (which only searches the already-selected games). 721What counts as similar enough to be selected can also be set in the 722@samp{Load Game Options} dialog, and ranges from an exact match to just the 723same material. 724@item Tags 725@cindex Tags, Menu Item 726Pops up a window which shows the PGN (portable game notation) 727tags for the current game. 728For now this is a duplicate of the @samp{Edit Tags} item in the @samp{Edit} menu. 729@item Comments 730@cindex Comments, Menu Item 731Pops up a window which shows any comments to or variations on the current move. 732For now this is a duplicate of the @samp{Edit Comment} item in the @samp{Edit} menu. 733@item ICS Input Box 734@cindex ICS Input Box, Menu Item 735If this option is set in ICS mode, 736XBoard 737creates an extra window that you can use for typing in ICS commands. 738The input box is especially useful if you want to type in something long or do 739some editing on your input, because output from ICS doesn't get mixed 740in with your typing as it would in the main terminal window. 741@item ICS/Chat Console 742@cindex ICS Chat/Console, Menu Item 743This menu item opens a window in which you can interact with the ICS, 744so you don't have to use the messy xterm from which you launched XBoard 745for that. 746The window has a text entry at the bottom where you can type your 747commands and messages unhindered by the stream of ICS output. 748The latter will be displayed in a large pane above the input field, 749the ICS Console. 750Up and down arrow keys can be used to recall previous input lines. 751Typing an <Esc> character in the input field transfers focus back 752to the board window (so you could operate the menus there 753through accelerator keys). 754Typing a printable character in the board window transfers focus 755back to the input field of the @samp{ICS Chat/Console} window. 756@item Chats 757@cindex Chats 758There is a row of buttons at the top of the @samp{ICS Chat/Console} dialog, 759which can be used to navigate between upto 5 'chats' 760with other ICS users (or channels). 761These will switch the window to 'chat mode', 762where the ICS output pane is vertically split to divert messages from 763a specific user or ICS channel to the lower half. 764Lines typed in the input field will then be interpreted as messages 765to be sent to that user or channel, 766(automatically prefixed with the apporpriate ICS command and user name) 767rather than as commands to the ICS. 768Chats will keep collecting ICS output intended for them even when not displayed, 769and their buttons will turn orange to alert the user there has been activity. 770Typing <Tab> in the input field will switch to another active chat, 771giving priority to those with content you have not seen yet. 772@item New Chat 773@cindex New Chat, Menu Item 774Buttons for chats currently not assigned to a user or channel 775will carry the text @samp{New Chat}, and pressing them will 776switch to chat mode, enabling you to enter the user name or channel number 777you want to use it for. 778Typing Ctrl-N in the input field is a keyboard equivalent. 779@item Chat partner 780@cindex Chat partner, Menu Item 781To (re-)assign a chat, write the name of your chat partner, the channel number, 782or the words 'shouts', 'whispers', 'cshouts' in the @samp{Chat partner} text entry 783(ending with <Enter>!). 784Typing Ctrl-O in the input field at the bottom of the window will 785open a chat with the person that last sent you a 'tell' that was printed 786in the ICS Console output pane. 787The @samp{ICS text menu} can contain a button @samp{Open Chat (name)} 788that can be used to open a chat with as partner the word/number you 789right-clicked in the output pane to pop up this menu. 790@item End Chat 791@cindex End Chat, Menu Item 792This button, only visible when the chat pane is open, 793will clear the @samp{Chat partner} field, so that the chat can be 794assigned to a new user or channel. 795Typing Ctrl-E in the input field is a keyboard equivalent. 796@item Hide 797@cindex Hide, Menu Item 798This button, only visible when the chat pane is open, 799will close the latter, so you can use the input field 800to give commands to the ICS again. 801Typing Ctrl-H in the input field is a keyboard equivalent. 802@item ICS text menu 803@cindex ICS text menu, Menu Item 804Brings up a menu that is user-configurable through the @code{icsMenu} option. 805Buttons in this menu can sent pre-configured commands directly to the ICS, 806or can put partial commands in the input field of the @samp{ICS Chat/Console} 807window, so that you can complete those with some text of your own before 808sending them to the ICS by pressing Enter. 809This menu item can also be popped up by right-clicking in the text memos 810of the ICS Chat/Console window. 811In that case the word that was clicked can be incorporated in the message 812sent to the ICS. E.g. to challenge a player whose name you click for a game, 813or prepare for sending him a message through a 'tell' commands. 814@item Edit ICS menu 815@cindex Edit ICS menu, Menu Item 816Brings up an edit box with the definition of the @samp{ICS text menu}, 817so you can adapt its appearance to your needs. 818The menu is defined by a semi-colon-separated list, 819each button through a pair of items in it. 820The first item of each pair is the text on the button, 821the second the text to be sent when the button is pressed. 822The word '$input' in the text will put that text in the input field 823of the @samp{ICS Chat/Console} with the cursor in that place, 824the word '$name' will be replaced by the word right-clicked 825to pop up the text menu. 826@item Edit Theme List 827@cindex Edit Theme List 828Brings up an edit box with the definitions of the themes 829shown in the listbox of the @samp{Board} dialog, 830so you can delete, re-order or alter themes defined previously. 831@item Board 832@cindex Board, Menu Item 833Summons a dialog where you can customize the look of the chess board. 834@item White Piece Color 835@itemx Black Piece Color 836@itemx Light Square Color 837@itemx Dark Square Color 838@itemx Highlight Color 839@itemx Premove Highlight Color 840@cindex Piece Color, Menu Item 841@cindex Square Color, Menu Item 842@cindex Highlight Color, Menu Item 843These items set the color of pieces, board squares and move highlights 844(borders or arrow). 845Square colors are only used when the @samp{Use Board Textures} option is off, 846the piece colors only when @samp{Use piece bitmaps with their own colors} is off. 847You can type the color as hexadecimally encoded RGB value preceded by '#', 848or adjust it through the R, G, B and D buttons to make it redder, greener, bluer 849or darker. 850A sample of the adjusted color will be displayed behind its text description; 851pressing this colored button restores the default value for the color. 852@item Flip Pieces Shogi Style 853@cindex Flip Pieces Shogi Style, Menu Item 854With this option on XBoard will swap white and black pieces, 855when you flip the view of the board to make white play downward. 856This should be used with piece themes that do not distinguish sides by color, 857but by orientation. 858@item Mono Mode 859@cindex Mono Mode, Menu Item 860This option sets XBoard to pure black-and-white display 861(no grey scales, and thus no anti-aliasing). 862@item Logo Size 863@cindex Logo Size, Menu Item 864Specifies the width of the engine logos displayed next to the clocks, in pixels. 865Setting it to 0 suppresses the display of such logos. 866The height of the logo will be half its width. 867In the GTK build of XBoard any non-zero value is equivalent, 868and the logos are always sized to 1/4 of the board width. 869@item Line Gap 870@cindex Line Gap, Menu Item 871This option specifies the width of the grid lines that separate the squares, 872which change color on highlighting the move. 873Setting it to 0 suppresses these lines, which in general looks better, 874but hides the square-border highlights, 875so that you would have to rely on other forms of highlighting. 876Setting the value to -1 makes XBoard choose a width by itself, 877depending on the square size. 878@item Use Board Textures 879@itemx Light-Squares Texture File 880@itemx Dark-Squares Texture File 881@cindex Use Board Texture, Menu Item 882@cindex Texture Files, Menu Item 883When the option @samp{Use Board Textures} is set, 884the squares will not be drawn as evenly colored surfaces, 885but will be cut from a texture image, as specified by the 886@samp{Texture Files}. 887Separate images can be used for light and dark squares. 888XBoard will try to cut the squares out of the texture image 889with as little overlap as possible, so they all look different. 890The name of the texture file can contain a size hint, 891e.g. @code{xqboard-9x10.png}, alerting XBoard to the fact that 892it contains a whole-board image, out of which squares have to 893be cut in register with the nominal sub-division. 894@item Use external piece bitmaps with their own color 895@cindex Draw pieces with their own colors, Menu Item 896When this option is on XBoard will ignore the piece-color settings, 897and draw the piece images in their original colors. 898The piece-color settings would only work well for evenly colored 899pieces, such as the default theme. 900@item Directory with Pieces Images 901@cindex Piece-Image Directory, Menu Item 902When a directory is specified here, XBoard will first look for 903piece images (SVG or PNG files) in that directory, 904and fall back on the image from the default theme only for 905images it cannot find there. 906An image file called White/BlackTile in the directory will be prefered 907as fall-back for missing pieces over the default image, however. 908@item Selectable themes 909@itemx New name for current theme 910@cindex Board Themes, Menu Item 911@cindex Theme name, Menu Item 912When a theme name is specified while pressing 'OK', 913the combination of settings specified in the dialog 914will be stored in XBoard's list of themes, 915which will be saved with the other options in the settings file 916(as the @code{themeNames} option). 917This name will then appear in the selection listbox next time 918you open the dialog, 919so that you can recall the entire combination of settings 920by double-clicking it. 921 922 923Here you can specify the directory from which piece images should be taken, 924when you don't want to use the built-in piece images 925(see @code{pieceImageDirectory} option), 926external images to be used for the board squares 927(@code{liteBackTextureFile} and @code{darkBackTextureFile} options), 928and square and piece colors for the default pieces. 929The current combination of these settings can be assigned a 'theme' name 930by typing one in the text entry in the lower-left of the dialog, 931and closing the latter with OK. 932It will then appear in the themes listbox next time you open the dialog, 933where you can recall the complete settings combination with a double-click. 934@item Fonts 935@cindex Fonts, Menu Item 936Pops up a dialog where you can set the fonts used in the main elements of various windows. 937Pango font names can be typed for each window type, 938and behind each text entry there are buttons to adjust the point size, 939and toggle the 'bold' or 'italic' attributes of the font. 940@item Game List Tags 941@cindex Game List Tags, Menu Item 942a duplicate of the Game List dialog in the Options menu. 943@end table 944 945@node Mode Menu 946@section Mode Menu 947@cindex Menu, Mode 948@cindex Mode Menu 949@table @asis 950@item Machine White 951@cindex Machine White, Menu Item 952Tells the chess engine to play White. 953The @kbd{Ctrl-W} key is a keyboard equivalent. 954@item Machine Black 955@cindex Machine Black, Menu Item 956Tells the chess engine to play Black. 957The @kbd{Ctrl-B} key is a keyboard equivalent. 958@item Two Machines 959@cindex Two Machines, Menu Item 960Plays a game between two chess engines. 961The @kbd{Ctrl-T} key is a keyboard equivalent. 962@item Analysis Mode 963@cindex Analysis Mode, Menu Item 964@cindex null move 965@cindex move exclusion 966XBoard tells the chess engine to start analyzing the current game/position 967and shows you the analysis as you move pieces around. 968The @kbd{Ctrl-A} key is a keyboard equivalent. 969Note: Some chess engines do not support Analysis mode. 970 971To set up a position to analyze, you do the following: 972 9731. Set up the position by any means. (E.g. using @samp{Edit Position} 974mode, pasing a FEN or loading a game and stepping to the position.) 975 9762. Select Analysis Mode from the Mode Menu to start the analysis. 977 978You can now play legal moves to create follow-up positions for the 979engine to analyze, while the moves will be remembered as a stored game, 980and then step backward through this game to take the moves back. 981Note that you can also click on the clocks to set the opposite 982side to move (adding a so-called @samp{null move} to the game). 983 984You can also tell the engine to exclude some moves from analysis. 985(Engines that do not support the exclude-moves feature will 986ignore this, however.) 987The general way to do this is to play the move you want to exclude 988starting with a double click on the piece. 989When you use drag-drop moving, the piece you grab with a double click 990will also remain on its square, to show you that you are not really 991making the move, but just forbid it from the current position. 992Playing a thus excluded move a second time will include it again. 993Excluded moves will be listed as text in a header line in the 994Engine Output window, and you can also re-include them by 995right-clicking them there. 996This header line will also contain the words 'best' and 'tail'; 997right-clicking those will exclude the currently best move, 998or all moves not explicitly listed in the header line. 999Once you leave the current position all memory of excluded 1000moves will be lost when you return there. 1001 1002 1003Selecting this menu item while already in @samp{Analysis Mode} will 1004toggle the participation of the second engine in the analysis. 1005The output of this engine will then be shown in the lower pane 1006of the Engine Output window. 1007The analysis function can also be used when observing games on an ICS 1008with an engine loaded (zippy mode); the engine then will analyze 1009the positions as they occur in the observed game. 1010 1011@item Analyze Game 1012@cindex Analyze Game, Menu Item 1013This option subjects the currently loaded game to automatic 1014analysis by the loaded engine. 1015The @kbd{Ctrl-G} key is a keyboard equivalent. 1016XBoard will start auto-playing the game from the currently displayed position, 1017while the engine is analyzing the current position. 1018The game will be annotated with the results of these analyses. 1019In particlar, the score and depth will be added as a comment, 1020and the PV will be added as a variation. 1021 1022Normally the analysis would stop after reaching the end of the game. 1023But when a game is loaded from a multi-game file 1024while @samp{Analyze Game} was already switched on, 1025the analysis will continue with the next game in the file 1026until the end of the file is reached (or you switch to another mode). 1027 1028The time the engine spends on analyzing each move can be controlled 1029through the command-line option @samp{-timeDelay}, 1030which can also be set from the @samp{Load Game Options} menu dialog. 1031Note: Some chess engines do not support Analysis mode. 1032@item Edit Game 1033Duplicate of the item in the Edit menu. 1034Note that @samp{Edit Game} is the idle mode of XBoard, and can be used 1035to get you out of other modes. E.g. to stop analyzing, stop a game 1036between two engines or stop editing a position. 1037@item Edit Position 1038Duplicate of the item in the Edit menu. 1039@item Training 1040@cindex Training, Menu Item 1041Training mode lets you interactively guess the moves of a game for one 1042of the players. You guess the next move of the game by playing the 1043move on the board. If the move played matches the next move of the 1044game, the move is accepted and the opponent's response is auto-played. 1045If the move played is incorrect, an error message is displayed. You 1046can select this mode only while loading a game (that is, after 1047selecting @samp{Load Game} from the File menu). While XBoard is in 1048@samp{Training} mode, the navigation buttons are disabled. 1049@item ICS Client 1050@cindex ICS Client, Menu Item 1051This is the normal mode when XBoard 1052is connected to a chess server. If you have moved into 1053Edit Game or Edit Position mode, you can select this option to get out. 1054 1055To use xboard in ICS mode, run it in the foreground with the -ics 1056option, and use the terminal you started it from to type commands and 1057receive text responses from the chess server. See 1058@ref{Chess Servers} below for more information. 1059 1060XBoard activates some special position/game editing features when you 1061use the @kbd{examine} or @kbd{bsetup} commands on ICS and you have 1062@samp{ICS Client} selected on the Mode menu. First, you can issue the 1063ICS position-editing commands with the mouse. Move pieces by dragging 1064with mouse button 1. To drop a new piece on a square, press mouse 1065button 2 or 3 over the square. This brings up a menu of white pieces 1066(button 2) or black pieces (button 3). Additional menu choices let 1067you empty the square or clear the board. Click on the White or Black 1068clock to set the side to play. You cannot set the side to play or 1069drag pieces to arbitrary squares while examining on ICC, but you can 1070do so in @kbd{bsetup} mode on FICS. In addition, the menu commands 1071@samp{Forward}, @samp{Backward}, @samp{Pause}, and @samp{Stop Examining} 1072have special functions in this mode; see below. 1073@item Machine Match 1074@cindex Machine match, Menu Item 1075Starts a match between two chess programs, 1076with a number of games and other parameters set through 1077the @samp{Tournament Options} menu dialog. 1078When a match is already running, selecting this item will make 1079XBoard drop out of match mode after the current game finishes. 1080@item Pause 1081@cindex Pause, Menu Item 1082Pauses updates to the board, and if you are playing against a chess engine, 1083also pauses your clock. To continue, select @samp{Pause} again, and the 1084display will automatically update to the latest position. 1085The @samp{P} button and keyboard @kbd{Pause} key are equivalents. 1086 1087If you select Pause when you are playing against a chess engine and 1088it is not your move, the chess engine's clock 1089will continue to run and it will eventually make a move, at which point 1090both clocks will stop. Since board updates are paused, however, 1091you will not see the move until you exit from Pause mode (or select Forward). 1092This behavior is meant to simulate adjournment with a sealed move. 1093 1094If you select Pause while you are observing or examining a game on a 1095chess server, you can step backward and forward in the current history 1096of the examined game without affecting the other observers and 1097examiners, and without having your display jump forward to the latest 1098position each time a move is made. Select Pause again to reconnect 1099yourself to the current state of the game on ICS. 1100 1101If you select @samp{Pause} while you are loading a game, the game stops 1102loading. You can load more moves manually by selecting @samp{Forward}, or 1103resume automatic loading by selecting @samp{Pause} again. 1104@end table 1105 1106@node Action Menu 1107@section Action Menu 1108@cindex Menu, Action 1109@cindex Action, Menu 1110@table @asis 1111@item Accept 1112@cindex Accept, Menu Item 1113Accepts a pending match offer. 1114The @kbd{F3} key is a keyboard equivalent. 1115If there is more than one offer 1116pending, you will have to type in a more specific command 1117instead of using this menu choice. 1118@item Decline 1119@cindex Decline, Menu Item 1120Declines a pending offer (match, draw, adjourn, etc.). 1121The @kbd{F4} key is a keyboard equivalent. If there 1122is more than one offer pending, you will have to type in a more 1123specific command instead of using this menu choice. 1124@item Call Flag 1125@cindex Call Flag, Menu Item 1126Calls your opponent's flag, claiming a win on time, or claiming 1127a draw if you are both out of time. 1128The @kbd{F5} key is a keyboard equivalent. 1129You can also call your 1130opponent's flag by clicking on his clock. 1131@item Draw 1132@cindex Draw, Menu Item 1133Offers a draw to your opponent, accepts a pending draw offer 1134from your opponent, or claims a draw by repetition or the 50-move 1135rule, as appropriate. The @kbd{F6} key is a keyboard equivalent. 1136@item Adjourn 1137@cindex Adjourn, Menu Item 1138Asks your opponent to agree to adjourning the current game, or 1139agrees to a pending adjournment offer from your opponent. 1140The @kbd{F7} key is a keyboard equivalent. 1141@item Abort 1142@cindex Abort, Menu Item 1143Asks your opponent to agree to aborting the current game, or 1144agrees to a pending abort offer from your opponent. 1145The @kbd{F8} key is a keyboard equivalent. An aborted 1146game ends immediately without affecting either player's rating. 1147@item Resign 1148@cindex Resign, Menu Item 1149Resigns the game to your opponent. The @kbd{F9} key is a 1150keyboard equivalent. 1151@item Stop Observing 1152@cindex Stop Observing, Menu Item 1153Ends your participation in observing a game, by issuing the ICS 1154observe command with no arguments. ICS mode only. 1155The @kbd{F10} key is a keyboard equivalent. 1156@item Stop Examining 1157@cindex Stop Examining, Menu Item 1158Ends your participation in examining a game, by issuing the ICS 1159unexamine command. ICS mode only. 1160The @kbd{F11} key is a keyboard equivalent. 1161@item Upload to Examine 1162@cindex Upload to Examine, Menu Item 1163Create an examined game of the proper variant on the ICS, 1164and send the game there that is currenty loaded in XBoard 1165(e.g. through pasting or loading from file). 1166You must be connected to an ICS for this to work. 1167@item Adjudicate to White 1168@itemx Adjudicate to Black 1169@itemx Adjudicate Draw 1170@cindex Adjudicate to White, Menu Item 1171@cindex Adjudicate to Black, Menu Item 1172@cindex Adjudicate Draw, Menu Item 1173Terminate an ongoing game in Two-Machines mode (including match mode), 1174with as result a win for white, for black, or a draw, respectively. 1175The PGN file of the game will accompany the result string 1176by the comment "user adjudication". 1177@end table 1178 1179@node Engine Menu 1180@section Engine Menu 1181@cindex Engine Menu 1182@cindex Menu, Engine 1183@table @asis 1184@item Edit Engine List 1185@cindex Edit Engine List, Menu Item 1186Opens a window that shows the list of engines registered for use 1187by XBoard, together with the options that would be used with them 1188when you would select them from the @samp{Load Engine} dialogs. 1189You can then edit this list, e.g. for re-ordering the engines, 1190or adding uncommon options needed by this engine 1191(e.g. to cure non-compliant behavior). 1192 1193By editing you can also organize the engines into collapsible groups. 1194By sandwiching a number of engine lines between lines "# NAME" and "# end", 1195the thus enclosed engines will not initially appear in engine listboxes 1196of other dialogs, but only the single line "# NAME" 1197(where NAME can be an arbitrary text) will appear in their place. 1198Selecting that line will then show the enclosed engines in the listbox, 1199which recursively can contain other groups. 1200The line with the group name will still present as a header, 1201and selecting that line will collapse the group again, 1202and makes the listbox go back to displaying the surrounding group. 1203@item Load New 1st Engine 1204@itemx Load New 2nd Engine 1205@cindex Load New Engine, Menu Item 1206Pops up a dialog where you can select or specify an engine to be loaded. 1207You can even replace engines during a game, without disturbing that game. 1208(Beware that after loading an engine, XBoard will always be in Edit Game mode, 1209so you will have to tell the new engine what to do before it does anything!) 1210@table @asis 1211@item Select engine from list 1212@cindex Select engine, Menu Item 1213The listbox shows the engines registered for use with XBoard before. 1214(This means XBoard has information on the engine type, whether it plays book etc. 1215in the engine list stored in its settings file.) 1216Double-clicking an engine here will load it and close the dialog. 1217The list can also contain groups, indicated by a starting '#' sign. 1218Double-clicking such a group will 'open' it, 1219and show the group contents in the listbox instead of the total list, 1220with the group name as header. 1221Double-clicking the header will 'close' the group again. 1222@item Nickname 1223@itemx Use nickname in PGN player tags of engine-engine games 1224@cindex Nickname, Menu Item 1225When a @samp{Nickname} is specified, the engine will appear under this name 1226in the @samp{Select Engine} listbox. 1227Otherwise the name there will be a tidied version of the engine command. 1228The user can specify if the nickname is also to be used in PGN tags; 1229normally the name engines report theselves would be used there. 1230@item Engine Command 1231@cindex Engine Command, Menu Item 1232The command needed to start the engine from the command line. 1233For compliantly installed engine this is usually just a single word, 1234the name of the engine package (e.g. 'crafty' or 'stockfish'). 1235Some engines need additional parameters on the command line. 1236For engines that are not in a place where the system would expect them 1237a full pathname can be specified, and usually the browse button 1238for this oprion is the easiest way to obtain that. 1239@item Engine Directory 1240@cindex Engine Directory, Menu Item 1241Compliant engines could run from any directory, 1242and by default this option is proposed as '.', the current directory. 1243If a (path)name is specified here, XBoard will start the engine 1244in that directory. 1245If you make the field empty, it will try to derive the directory 1246from the engine command (if that was a path name). 1247@item UCI 1248@cindex UCI, Menu Item 1249When the @samp{UCI} checkbox is ticked XBoard will assume 1250the engine is of UCI type, and will invoke the corresponding adapter 1251(as specified in the @code{adapterCommand} option stored in its 1252settings file)to use it. 1253By default this adapter is Polyglot, 1254which must be installed from a separate package! 1255@item USI/UCCI 1256@cindex USI/UCCI, Menu Item 1257Ticking this checkbox informs XBoard that the engine is of USI or UCCI type 1258(as Shogi or Xiangqi engines often are). 1259This makes XBoard invoke an adapter to run the engines, 1260as specified by the @code{uxiAdapter} option stored in its settings file. 1261The UCI2WB program is an adapter that can handle both these engine types, 1262as well as UCI. 1263@item WB protocol v1 1264@cindex WB protocol v1, Menu Item 1265Ticking this checkbox informs XBoard the engine is using an old version (1) 1266of the communication protocol, so that it won't respond to a request 1267to interrogate its properties. 1268XBoard then won't even try that, saving you a wait of several seconds 1269each time the engine is started. 1270Do not use this on state-of-the-art engines, 1271as it would prevent XBoard from interrogating its capabilities, 1272so that many of its features might not work! 1273@item Must not use GUI book 1274@cindex Use GUI book, Menu Item 1275By default XBoard assumes engines are responsible for their own opening book, 1276but unticking this option makes XBoard consult its own book 1277(as per @samp{Opening-Book Filename}) on behalf of the engine. 1278@item Add this engine to the list 1279@cindex Add engine, Menu Item 1280By default XBoard would add the engine you specified, 1281with all the given options to its list of registered engines 1282(kept in its settings file), when you press 'OK'. 1283Next time you could then simply select it from the listbox, 1284or use the command "xboard -fe NICKNAME" to start XBoard with the 1285engine and accompanying options. 1286New engines are always added at the end of the existing list, 1287or, when you have opened a group in the @samp{Select Engine} listbox, 1288at the end of that group. 1289But can be re-ordered later with the aid 1290of the @samp{Edit Engine List} menu item. 1291When you untick this checkbox before pressing 'OK' 1292the engine will be loaded, but will not be added to the engine list. 1293@item Force current variant with this engine 1294@cindex Force variant with engine, Menu Item 1295Ticking this option will make XBoard automatically start the engine 1296in the current variant, even when XBoard was set for a different 1297variant when you loaded the engine. 1298Useful when the engine plays multiple variants, 1299and you specifically want to play one different from its primary one. 1300@end table 1301 1302@item Engine #1 Settings 1303@itemx Engine #2 Settings 1304@cindex Engine #N Settings, Menu Item 1305Pop up a menu dialog to alter the settings specific to the applicable engine. 1306For each parameter the engine allows to be set, 1307a control element will appear in this dialog that can be used to alter the value. 1308Depending on the type of parameter (text string, number, multiple choice, 1309on/off switch, instantaneous signal) the appropriate control will appear, 1310with a description next to it. 1311XBoard has no idea what these values mean; it just passes them on to the engine. 1312How this dialog looks is completely determined by the engine, 1313and XBoard just passes it on to the user. 1314Many engines do not have any parameters that can be set by the user, 1315and in that case the dialog will be empty (except for the OK and cancel buttons). 1316UCI engines usually have many parameters. (But these are only visible with 1317a sufficiently modern version of the Polyglot adapter needed to run UCI engines, 1318e.g. Polyglot 2.0.1.) For native XBoard engines this is less common. 1319 1320@item Common Settings 1321@cindex Common Settings, Menu Item 1322Pops up a menu dialog where you can set some engine parameters common to most engines, 1323such as hash-table size, tablebase cache size, maximum number of processors 1324that SMP engines can use. 1325The shifted @kbd{Alt+U} key is a keyboard equivalent. 1326Older XBoard/WinBoard engines might not respond to these settings, 1327but UCI engines always should. 1328@item Maximum Number of CPUs per Engine 1329@cindex Max. Number of CPUs, Menu Item 1330Specifies the number of search threads any engine can maximally use. 1331Do not set it to a number larger than the number of cores your computer has. 1332(Or half of it when you want two engines to run simultaneously, 1333as in a Two-Machines game with @samp{Ponder Next Move} on.) 1334@item Polyglot Directory 1335@item Hash-Table Size 1336@cindex Hash-Table Size 1337Specifies the maximum amount of memory (RAM) each engine is allowed to use 1338for storing info on positions it already searched, 1339so it would not have to search them again. 1340Do not set it so that it is more than half 1341(or if you use two engines, more than a quarter) 1342of the memory your computer has, 1343or it would slow the engines down by an extreme amount. 1344@item EGTB Path 1345@cindex EGTB Path, Menu Item 1346Sets the value of the @code{egtFormats} option, which specifies 1347where on your computer the files for End-Game Tables are stored. 1348It must be a comma-separated list of path names, 1349the path for each EGT flavor prefixed with the name of the latter 1350and a colon. E.g. "nalimov:/home/egt/dtm,syzygy:/home/egt/dtz50". 1351The path names after the colon will be sent to the engines 1352that say they can use the corresponding EGT flavor. 1353@item EGTB Cache Size 1354@cindex EGTB Cache Size, Menu Item 1355Specifies the amount of memory the engine should use to 1356buffer end-game information. 1357Together with the @samp{Hash-Table Size} this determines how 1358much memory the engine is allowed to use in total. 1359@item Use GUI Book 1360@itemx Opening-Book Filename 1361@cindex Use GUI Book, Menu Item 1362@cindex Opening-Book Filename, Menu Item 1363The @samp{Opening-Book Filename} specifies an opening book 1364in Polyglot format (usually a .bin file), 1365from which XBoard can play moves on behalf of the engine. 1366This is also the book file on which the @samp{Edit Book} 1367and @samp{Save Games as Book} menu items operate. 1368A checkbox @samp{Use GUI Book} can be used to temporarily 1369disable the book without losing the setting. 1370(This does not prevent editing or saving games on it!) 1371@item Book Depth 1372@itemx Book Variety 1373@cindex Book Depth, Menu Item 1374@cindex Book Variety, Menu Item 1375The way moves are selected from the book can be controlled by two options. 1376@samp{Book Depth} controls for how deep into the game the book 1377will be consulted (measured in full moves). 1378@samp{Book Variety} controls the likelihood of playing weaker moves. 1379When the variety is set to 50, moves will be played with the probability 1380specified in the book. 1381When set to 0, only the move(s) with the highest probability will be played. 1382When set to 100, all listed moves will be played with equal pobability. 1383Other settings interpolate between that. 1384@item Engine #1 Has Own Book 1385@itemx Engine #2 Has Own Book 1386@cindex Engine Has Own Book 1387These checkboxes control on a per-engine basis 1388whether XBoard will consult the opening book for them. 1389If ticked, XBoard will never play moves from its GUI book, 1390giving the engine the opportunity to use its own. 1391These options are automatically set whenever you load an engine, 1392based on the setting of @samp{Must not use GUI book} 1393when you installed that through the @samp{Load Engine} menu dialog. 1394@item Hint 1395@cindex Hint, Menu Item 1396Displays a move hint from the chess engine. 1397@item Book 1398@cindex Book, Menu Item 1399Displays a list of possible moves from the chess engine's opening 1400book. The exact format depends on what chess engine you are using. 1401With GNU Chess 4, the first column gives moves, the second column 1402gives one possible response for each move, and the third column shows 1403the number of lines in the book that include the move from the first 1404column. If you select this option and nothing happens, the chess 1405engine is out of its book or does not support this feature. 1406@item Move Now 1407@cindex Move Now, Menu Item 1408Forces the chess engine to move immediately. Chess engine mode only. 1409The @kbd{Ctrl-M} key is a keyboard equivalent. 1410Many engines won't respond to this. 1411@item Retract Move 1412@cindex Retract Move, Menu Item 1413Retracts your last move. In chess engine mode, you can do this only 1414after the chess engine has replied to your move; if the chess engine is still 1415thinking, use @samp{Move Now} first. In ICS mode, @samp{Retract Move} 1416issues the command @samp{takeback 1} or @samp{takeback 2} 1417depending on whether it is your opponent's move or yours. 1418The @kbd{Ctrl-X} key is a keyboard equivalent. 1419@item Recently Used Engines 1420@cindex Recently Used Engines, In Menu 1421At the bottom of the engine menu there can be a list of names 1422of engines that you recently loaded through the Load Engine menu dialog 1423in previous sessions. 1424Clicking on such a name will load that engine as first engine, 1425so you won't have to search for it in your list of installed engines, 1426if that is very long. 1427The maximum number of displayed engine names is set by the 1428@code{recentEngines} command-line option. 1429@end table 1430 1431@node Options Menu 1432@section Options Menu 1433@cindex Menu, Options 1434@cindex Options Menu 1435@section Mute all Sounds 1436@cindex Mute sounds, Menu Item 1437Ticking this menu item toggles all sounds XBoard can make on or off, 1438without losing their definitions. 1439@section General Options 1440@cindex General Options, Menu Item 1441The following items to set option values appear in the dialog 1442summoned by the general Options menu item. 1443@table @asis 1444@item Absolute Analysis Scores 1445@cindex Absolute Analysis Scores, Menu Item 1446Controls if scores on the Engine Output window during analysis 1447will be printed from the white or the side-to-move point-of-view. 1448@item Almost Always Queen 1449@cindex Almost Always Queen, Menu Item 1450If this option is on, 7th-rank pawns automatically change into 1451Queens when you pick them up, 1452and when you drag them to the promotion square and release them there, 1453they will promote to that. 1454But when you drag such a pawn backwards first, 1455its identity will start to cycle through the other available pieces. 1456This will continue until you start to move it forward; 1457at which point the identity of the piece will be fixed, 1458so that you can safely put it down on the promotion square. 1459If this option is off, what happens depends on the 1460option @code{alwaysPromoteToQueen}, 1461which would force promotion to Queen when true. 1462Otherwise XBoard would bring up a dialog 1463box whenever you move a pawn to the last rank, asking what piece 1464you want to promote to. 1465@item Animate Dragging 1466@cindex Animate Dragging, Menu Item 1467If Animate Dragging is on, while you are dragging a piece with the 1468mouse, an image of the piece follows the mouse cursor. 1469If Animate Dragging is off, there is no visual feedback while you are 1470dragging a piece, but if Animate Moving is on, the move will be 1471animated when it is complete. 1472@item Animate Moving 1473@cindex Animate Moving, Menu Item 1474If Animate Moving is on, all piece moves are animated. An image of the 1475piece is shown moving from the old square to the new square when the 1476move is completed (unless the move was already animated by Animate Dragging). 1477If Animate Moving is off, a moved piece instantly disappears from its 1478old square and reappears on its new square when the move is complete. 1479The shifted @kbd{Ctrl-A} key is a keyboard equivalent. 1480@item Auto Flag 1481@cindex Auto Flag, Menu Item 1482If this option is on and one player runs out of time 1483before the other, 1484XBoard 1485will automatically call his flag, claiming a win on time. 1486The shifted @kbd{Ctrl-F} key is a keyboard equivalent. 1487In ICS mode, Auto Flag will only call your opponent's flag, not yours, 1488and the ICS may award you a draw instead of a win if you have 1489insufficient mating material. In local chess engine mode, 1490XBoard 1491may call either player's flag. 1492@item Auto Flip View 1493@cindex Auto Flip View, Menu Item 1494If the Auto Flip View option is on when you start a game, the board 1495will be automatically oriented so that your pawns move from the bottom 1496of the window towards the top. 1497 1498If you are playing a game on an ICS, the board is always 1499oriented at the start of the game so that your pawns move from 1500the bottom of the window towards the top. Otherwise, the starting 1501orientation is determined by the @code{flipView} command line option; 1502if it is false (the default), White's pawns move from bottom to top 1503at the start of each game; if it is true, Black's pawns move from 1504bottom to top. @xref{User interface options}. 1505@item Blindfold 1506@cindex Blindfold, Menu Item 1507If this option is on, XBoard displays the board as usual but does 1508not display pieces or move highlights. You can still move in the 1509usual way (with the mouse or by typing moves in ICS mode), even though 1510the pieces are invisible. 1511@item Drop Menu 1512@cindex Drop Menu, Menu Item 1513Controls if right-clicking the board in crazyhouse / bughouse 1514will pop up a menu to drop a piece on the clicked square 1515(old, deprecated behavior) 1516or allow you to step through an engine PV 1517(new, recommended behavior). 1518@item Enable Variation Trees 1519@cindex Enable Variation Trees, Menu Item 1520If this option is on, playing a move in Edit Game or Analyze mode 1521while keeping the Shift key pressed will start a new variation. 1522You can then recall the previous line through the @samp{Revert} menu item. 1523When off, playing a move will truncate the game and append the move 1524irreversibly. 1525@item Headers in Engine Output Window 1526@cindex Headers in Engine Output Window, Menu Item 1527Controls the presence of column headers above the variations and 1528associated information printed by the engine, on which you can issue 1529button 3 clicks to open or close the columns. 1530Available columns are search depth, score, node count, time used, 1531tablebase hits, search speed and selective search depth. 1532@item Hide Thinking 1533@cindex Hide Thinking, Menu Item 1534If this option is off, the chess engine's notion of the score and best 1535line of play from the current position is displayed as it is 1536thinking. The score indicates how many pawns ahead (or if negative, 1537behind) the chess engine thinks it is. In matches between two 1538machines, the score is prefixed by @samp{W} or @samp{B} to indicate 1539whether it is showing White's thinking or Black's, and only the thinking 1540of the engine that is on move is shown. 1541The shifted @kbd{Ctrl-H} key is a keyboard equivalent. 1542@item Highlight Last Move 1543@cindex Highlight Last Move, Menu Item 1544If Highlight Last Move is on, after a move is made, the starting and 1545ending squares remain highlighted. In addition, after you use Backward 1546or Back to Start, the starting and ending squares of the last move to 1547be unmade are highlighted. 1548@item Highlight with Arrow 1549@cindex Highlight with Arrow, Menu Item 1550Causes the highlighting described in Highlight Last Move to be done 1551by drawing an arrow between the highlighted squares, 1552so that it is visible even when the width of the grid lines is set to zero. 1553@item One-Click Moving 1554@cindex One-Click Moving, Menu Item 1555If this option is on, XBoard does not wait for you to click both the 1556from- and the to-square, or drag the piece, but performs a move as soon 1557as it is uniqely specified. 1558This applies to clicking an own piece that only has a single legal move, 1559clicking an empty square or opponent piece where only one of your pieces 1560can move (or capture) to. 1561Furthermore, a double-click on a piece that can only make a single capture 1562will cause that capture to be made. 1563Promoting a Pawn by clicking its to-square will suppress the promotion 1564popup or other methods for selecting an under-promotion, 1565and make it promote to Queen. 1566@item Periodic Updates 1567@cindex Periodic Updates, Menu Item 1568If this option is off (or if 1569you are using a chess engine that does not support periodic updates), 1570the analysis window 1571will only be updated when the analysis changes. If this option is 1572on, the Analysis Window will be updated every two seconds. 1573@item Play Move(s) of Clicked PV 1574@cindex Play Move(s) of Clicked PV, Menu Item 1575If this option is on, right-clicking on the first move of a PV 1576or on the data fields left of it in the Engine Output window 1577during Analyze mode will cause the first move of that PV to be played. 1578You could also play more than one (or no) PV move by moving the mouse 1579to engage in the PV walk such a right-click will start, 1580to seek out another position along the PV where you want to continue 1581the analysis, before releasing the mouse button. 1582Clicking on later moves of the PV only temporarily show the moves 1583for as long you keep the mouse button down, 1584without adding them to the game. 1585@item Ponder Next Move 1586@cindex Ponder Next Move, Menu Item 1587If this option is off, the chess engine will think only when it is on 1588move. If the option is on, the engine will also think while waiting 1589for you to make your move. 1590The shifted @kbd{Ctrl-P} key is a keyboard equivalent. 1591@item Popup Exit Message 1592@cindex Popup Exit Message, Menu Item 1593If this option is on, when XBoard wants to display a message just 1594before exiting, it brings up a modal dialog box and waits for you to 1595click OK before exiting. If the option is off, XBoard prints the 1596message to standard error (the terminal) and exits immediately. 1597@item Popup Move Errors 1598@cindex Popup Move Errors, Menu Item 1599If this option is off, when you make an error in moving (such as 1600attempting an illegal move or moving the wrong color piece), the 1601error message is displayed in the message area. If the option is 1602on, move errors are displayed in small pop-up windows like other errors. 1603You can dismiss an error pop-up either by clicking its OK button or by 1604clicking anywhere on the board, including down-clicking to start a move. 1605@item Scores in Move List 1606@cindex Scores in Move List, Menu Item 1607If this option is on, XBoard will display the depth and score 1608of engine moves in the Move List, in the format of a PGN comment. 1609@item Show Coords 1610@cindex Show Coords, Menu Item 1611If this option is on, XBoard displays algebraic coordinates 1612along the board's left and bottom edges. 1613@item Show Target Squares 1614@cindex Show Target Squares, Menu Item 1615If this option is on, all squares a piece that is 'picked up' with the mouse 1616can legally move to are highighted with a fat colored dot in 1617yellow (non-captures) or red (captures). 1618Special moves might have other colors 1619(e.g. magenta for promotion, cyan for a partial move). 1620Legality testing must be on for XBoard to know how the piece moves, 1621but with legality testing off some engines would offer this information. 1622@item Sticky Windows 1623@cindex Sticky Windows, Menu Item 1624Controls whether the auxiliary windows such as Engine Output, Move History 1625and Evaluation Graph should keep touching XBoard's main window when 1626you move the latter. 1627@item Test Legality 1628@cindex Test Legality, Menu Item 1629If this option is on, XBoard tests whether the moves you try to make 1630with the mouse are legal and refuses to let you make an illegal move. 1631The shifted @kbd{Ctrl-L} key is a keyboard equivalent. 1632Moves loaded from a file with @samp{Load Game} are also checked. If 1633the option is off, all moves are accepted, but if a local chess engine 1634or the ICS is active, they will still reject illegal moves. Turning 1635off this option is useful if you are playing a chess variant with 1636rules that XBoard does not understand. (Bughouse, suicide, and wild 1637variants where the king may castle after starting on the d file are 1638generally supported with Test Legality on.) 1639@item Top-Level Dialogs 1640@cindex Top-Level Dialogs, Menu Item 1641Controls whether the auxiliary windows will appear as icons in the 1642task bar and independently controllable, or whether they open and 1643minimize all together with the main window. 1644@item Flash Moves 1645@itemx Flash Rate 1646@cindex Flash Moves, Menu Item 1647@cindex Flash Rate, Menu Item 1648If this option is non-zero, whenever a move is completed, 1649the moved piece flashes the specified number of times. 1650The flash-rate setting determines how rapidly this flashing occurs. 1651@item Animation Speed 1652@cindex Animation Speed, Menu Item 1653Determines the duration (in msec) of an animation step, 1654when @samp{Animate Moving} is swiched on. 1655@item Zoom factor in Evaluation Graph 1656@cindex Zoom factor in Evaluation Graph, Menu Item 1657Sets the value of the @code{evalZoom} option, 1658indicating the factor by which the score interval (-1,1) should be 1659blown up on the vertical axis of the Evaluation Graph. 1660@end table 1661@section Time Control 1662@cindex Time Control, Menu Item 1663Pops up a sub-menu where you can set the time-control parameters interactively. 1664The shifted @kbd{Alt+T} key is a keyboard equivalent. 1665@table @asis 1666@item classical 1667@cindex classical, Menu Item 1668Selects classical TC, 1669where the game is devided into sessions of a certain number of moves, 1670and after each session the start time is again added to the clocks. 1671@item incremental 1672@cindex incremental, Menu Item 1673Selects a TC mode where the game will start with a base time on the clocks, 1674and after every move an 'increment' will be added to it. 1675@item fixed max 1676@cindex fixed max, Menu Item 1677Selects a TC mode where you have to make each move within a given time, 1678and any left-over time is not carried over to the next move. 1679@item Divide entered times by 60 1680@cindex Divide entered times by 60, Menu Item 1681To allow entering of sub-minute initial time or sub-second increment, 1682you can tick this checkbox. 1683The initial time can then be entered in seconds, 1684and the increment in units of 1/60 second. 1685@item Moves per session 1686@cindex Moves per session, Menu Item 1687Sets the duration of a session for classical time control. 1688@item Initial time 1689@cindex Initial time, Menu Item 1690Time initially on the clock in classical or incremental time controls. 1691In classical time controls this time will also be added to the clock 1692at the start of ach new session. 1693@item Increment or max 1694@cindex Increment or max, Menu Item 1695Time to be added to the clock after every move in incremental TC mode. 1696Fore 'fixed maximum' TC mode, the clock will be set to this time 1697before every move, irrespective of how much was left on that clock. 1698@item Time-Odds factors 1699@cindex Time-Odds factors, Menu Item 1700When these options are set to 1 the clocks of the players will be set 1701according to the other specified TC parameters. 1702Players can be given unequal times by specifying a time-odds factor 1703for one of them (or a different factor for both of them). 1704Any time received by that player will then be divided by that factor. 1705@end table 1706 1707@section Adjudications 1708@cindex Adjudications, Menu Item 1709Pops up a sub-menu where you can enable or disable various adjudications 1710that XBoard can perform in engine-engine games. 1711The shifted @kbd{Alt+J} key is a keyboard equivalent. 1712@table @asis 1713@item Detect all Mates 1714@cindex Detect all Mates, Menu Item 1715When this option is set 1716XBoard will terminate the game on checkmate or stalemate, 1717even if the engines would not do so. 1718Only works when @samp{Test Legality} is on. 1719@item Verify Engine Result Claims 1720@cindex Verify Engine Result Claims, Menu Item 1721When this option is set 1722XBoard will verify engine result claims, 1723(forfeiting engines that make false claims), 1724rather than naively beleiving the engine. 1725Only works when @samp{Test Legality} is on. 1726@item Draw if Insufficient Mating Material 1727@cindex Draw if Insufficient Mating Material, Menu Item 1728When this option is set 1729XBoard will terminate games with a draw result 1730when so little material is left 1731that checkmate is not longer possible. 1732In normal Chess this applies to KK, KNK, KBK 1733and some positions with multiple Bishops all on the same 1734square shade. 1735Only works when @samp{Test Legality} is on. 1736@item Adjudicate Trivial Draws 1737@cindex Adjudicate Trivial Draws, Menu Item 1738When this option is set 1739XBoard will terminate games with a draw result 1740in positions that could only be won against an idiot. 1741In normal Chess this applies to KNNK, KRKR, KBKN, KNKN, 1742and KBKB with Bishops on different square shades. 1743KQKQ will also be adjudicated a draw (possibly unjustly so). 1744Only works when @samp{Test Legality} is on. 1745@item N-Move Rule 1746@cindex N-Move Rule, Menu Item 1747When this option is set to a value differnt from zero 1748XBoard will terminate games with a draw result 1749after the specified number of reversible moves 1750(i.e. without captures or pawn pushes) is made. 1751@item N-fold Repeats 1752@cindex N-fold Repeats, Menu Item 1753When this option is set to a value larger than 1, 1754XBoard will terminate games with a draw result when 1755the same position has occurred the specified number of times. 1756@item Draw after N Moves Total 1757@cindex Draw after N Moves Total, Menu Item 1758When this option is set to a value different from zero, 1759XBoard will terminate games with a draw result 1760after that many moves have been played. 1761Useful in automated engine-engine matches, 1762to prevent one game between stubborn engines will soak up 1763all your computer time. 1764@item Win / Loss Threshold 1765@cindex Win / Loss Threshold, Menu Item 1766When this option is set to a value different from zero, 1767XBoard will terminate games as a win when both engines 1768agree the score is above the specified value 1769(interpreted as centi-Pawn) 1770for three successive moves. 1771@item Negate Score of Engine #1 1772@itemx Negate Score of Engine #2 1773@cindex Negate Score of Engine, Menu Item 1774These options should be used with engines 1775that report scores from the white point of view, 1776rather than the side-to-move POV as XBoard would otherwise 1777assume when adjudicating games based on the engine score. 1778When the engine is installed with the extra option 1779@code{firstScoreIsAbs} true in the engine list 1780the option would be automatically set when the engine is 1781loaded throuhgh the Engine menu, 1782or with the @code{fe} or @code{se} command-line option. 1783@end table 1784 1785@section ICS Options 1786@cindex ICS Options, Menu Item 1787Pops up a menu dialog where options can be set that affect 1788playing against an Internet Chess Server. 1789@table @asis 1790@item Auto-Kibitz 1791@cindex Auto-Kibitz, Menu Item 1792Setting this option when playing with or aginst a chess program on an ICS 1793will cause the last line of thinking output of the engine before its move 1794to be sent to the ICS in a kibitz command. 1795In addition, any kibitz message received through the ICS from 1796an opponent chess program will be diverted to the engine-output window, 1797(and suppressed in the console), 1798where you can play through its PV by right-clicking it. 1799@item Auto-Comment 1800@cindex Auto-Comment, Menu Item 1801If this option is on, any remarks made on ICS while you are observing or 1802playing a game are recorded as a comment on the current move. This includes 1803remarks made with the ICS commands @kbd{say}, @kbd{tell}, @kbd{whisper}, 1804and @kbd{kibitz}. 1805Limitation: remarks that you type yourself are not recognized; 1806XBoard scans only the output from ICS, not the input you type to it. 1807@item Auto-Observe 1808@cindex Auto-Observe, Menu Item 1809If this option is on and you add a player to your @code{gnotify} 1810list on ICS, XBoard will automatically observe all of that 1811player's games, unless you are doing something else (such as 1812observing or playing a game of your own) when one starts. 1813The games are displayed 1814from the point of view of the player on your gnotify list; that is, his 1815pawns move from the bottom of the window towards the top. 1816Exceptions: If both players in a game are on your gnotify list, if 1817your ICS 1818@code{highlight} 1819variable is set to 0, or if the ICS you are using does not 1820properly support observing from Black's point of view, 1821you will see the game from White's point of view. 1822@item Auto-Raise Board 1823@cindex Auto Raise Board, Menu Item 1824If this option is on, whenever a new game begins, the chessboard window 1825is deiconized (if necessary) and raised to the top of the stack of windows. 1826@item Auto Save 1827@cindex Auto Save, Menu Item 1828If this option is true, at the end of every game XBoard prompts 1829you for a file name and appends a record of the game to the file 1830you specify. 1831Disabled if the @code{saveGameFile} command-line 1832option is set, as in that case all games are saved to the specified file. 1833@xref{Load and Save options}. 1834@item Background Observe while Playing 1835@cindex Background Observe while Playing, Menu Item 1836Setting this option will make XBoard suppress display of any boards 1837from observed games while you are playing. 1838Instead the last such board will be remembered, 1839and shown to you when you right-click the board. 1840This allows you to peek at your bughouse partner's game when you want, 1841without disturbing your own game too much. 1842@item Dual Board for Background-Observed Game 1843@cindex Dual Board for Background-Observed Game, Menu Item 1844Setting this option in combination with @samp{Background Observe} 1845will display boards of observed games while you are playing 1846on a second board next to that of your own game. 1847@item Get Move List 1848@cindex Get Move List, Menu Item 1849If this option is on, whenever XBoard 1850receives the first board of a new ICS game (or a different game from 1851the one it is currently displaying), it 1852retrieves the list of past moves from the ICS. 1853You can then review the moves with the @samp{Forward} and @samp{Backward} 1854commands 1855or save them with @samp{Save Game}. You might want to 1856turn off this option if you are observing several blitz games at once, 1857to keep from wasting time and network bandwidth fetching the move lists over 1858and over. 1859When you turn this option on from the menu, XBoard 1860immediately fetches the move list of the current game (if any). 1861@item Quiet Play 1862@cindex Quiet Play, Menu Item 1863If this option is on, XBoard will automatically issue an ICS 1864@kbd{set shout 0} 1865command whenever you start a game and a 1866@kbd{set shout 1} 1867command whenever you finish one. Thus, you will not be distracted 1868by shouts from other ICS users while playing. 1869@item Seek Graph 1870@cindex Seek Graph, Menu Item 1871Setting this option will cause XBoard to display an graph of 1872currently active seek ads when you left-click the board 1873while idle and logged on to an ICS. 1874@item Auto-Refresh Seek Graph 1875@cindex Auto-Refresh Seek Graph, Menu Item 1876In combination with the @samp{Seek Graph} option this 1877will cause automatic update of the seek graph while it is up. 1878This only works on FICS and ICC, 1879and requires a lot of bandwidth on a busy server. 1880@item Auto-InputBox PopUp 1881@cindex Auto-InputBox PopUp, Menu Item 1882Controls whether the ICS Input Box will pop up automatically when 1883you type a printable character to the board window in ICS mode. 1884@item Quit After Game 1885@cindex Quit After Game, Menu Item 1886Controls whether XBoard will automatically disconnect from the ICS 1887and close when the game currently in progress finishes. 1888@item Premove 1889@itemx Premove for White 1890@itemx Premove for Black 1891@itemx First White Move 1892@itemx First Black Move 1893@cindex Premove, Menu Item 1894@cindex Premove for White, Menu Item 1895@cindex Premove for Black, Menu Item 1896@cindex First White Move, Menu Item 1897@cindex First Black Move, Menu Item 1898If the @samp{Premove} option is on while playing a game on an ICS, 1899you can register your next planned move before it is your turn. 1900Move the piece with 1901the mouse in the ordinary way, and the starting and ending squares 1902will be highlighted with a special color (red by default). When it is 1903your turn, if your registered move is legal, XBoard will send it to 1904ICS immediately; if not, it will be ignored and you can make a 1905different move. If you change your mind about your premove, either 1906make a different move, or double-click on any piece to cancel the move 1907entirely. 1908 1909You can also enter premoves for the first white and black moves 1910of the game. 1911@item Alarm 1912@itemx Alarm Time 1913@cindex Alarm, Menu Item 1914@cindex Alarm Time, Menu Item 1915When this option is on, an alarm sound is played when your clock 1916counts down to the @samp{Alarm Time} in an ICS game. 1917(By default, the time is 5 seconds, but you can specify other values 1918with the Alarm Time spin control.) 1919For games with time controls that include an increment, the 1920alarm will sound each time the clock counts down to the icsAlarmTime. 1921By default, the alarm sound is the terminal bell, but on some systems 1922you can change it to a sound file using the soundIcsAlarm option; see 1923below. 1924@item Colorize Messages 1925@cindex Colorize Messages, Menu Item 1926Ticking this options causes various types of ICS messages do be 1927displayed with different foreground or background colors in the console. 1928The colors can be individually selected for each type, 1929through the accompanying text edits. 1930@item -icsMenu string 1931@cindex icsMenu, option 1932The string defines buttons for the @samp{ICS text menu}. 1933Each button definition consists of two semi-colon-terminated pieces of text, 1934the first giving the label to be written on the button, 1935the second the text that should be sent to the ICS when that button is pressed. 1936This second part (the 'message') can contain linefeeds, so that you can send 1937multiple ICS commands with one button. 1938Some message in the text, all starting with a $-sign, are treated special. 1939When the message contains '$input', it will not be sent directly to the ICS, 1940but will be put in the input field of the @samp{ICS Chat/Console}, 1941with the text cursor at the indicated place, so you can addsome text to 1942the message before sending it off. 1943If such a message starts with '$add' it will be placed behind any text 1944that is already present in the input field, otherwise this field will 1945be cleared first. 1946The word '$name' occurring in the message will be replaced by the word 1947that was clicked (through button 3) in the ICS Chat/Console. 1948There are two special messages: '$chat' will open a new chat with 1949the clicked word in the chat-partner field, 1950while '$copy' will copy the text that is currently-selected 1951in the ICS Console to the clipboard. 1952An example of a text menu as it might occur in your settings file 1953(where you could edit it): 1954 1955@example 1956-icsMenu @{copy;$copy; 1957list players;who; 1958list games;games; 1959finger (player);finger $name; 1960bullet (player);match $name 1 1 r; 1961blitz (player);match $name 5 1 r; 1962rapid (player);match $name 30 0 r; 1963open chat (player);$chat; 1964tell (player);tell $name $input; 1965ask pieces;ptell Please give me a $input; 1966P;$add Pawn $input; 1967N;$add Knight $input; 1968B;$add Bishop $input; 1969R;$add Rook $input; 1970Q;$add Queen $input; 1971@} 1972@end example 1973@end table 1974 1975@section Tournament Options 1976@cindex Tournament Options, Menu Item 1977Summons a dialog where you can set options important for playing automatic 1978matches between two or more chess programs 1979(e.g. by using the @samp{Machine Match} menu item in the @samp{Mode} menu). 1980@table @asis 1981@item Tournament file 1982@cindex Tournament file, Menu item 1983To run a tournament, XBoard needs a file to record its progress, 1984so it can resume the tourney when it is interrupted. 1985When you want to conduct anything more complex than a simple 1986two-player match with the currently loaded engines, 1987(i.e. when you select a list of participants), 1988you must not leave this field blank. 1989When you enter the name of an existing tournament file, 1990XBoard will ignore all other input specified in the dialog, 1991and will take the corresponding info from that tournament file. 1992This resumes an interrupted tournament, or adds another XBoard 1993agent playing games for it to those that are already doing so. 1994Specifying a not-yet-existing file will cause XBoard to create it, 1995according to the tournament parameters specified in the rest of the dialog, 1996before it starts the tournament on ‘OK’. 1997Provided that you specify participants; 1998without participants no tournament file will be made, but other entered values 1999(e.g. for the file with opening positions) will take effect. 2000Default: configured by the @code{defaultTourneyName} option. 2001@item Sync after round 2002@itemx Sync after cycle 2003@cindex Sync after round, Menu Item 2004@cindex Sync after cycle, Menu Item 2005The sync options, when on, will cause WinBoard to refrain from starting games 2006of the next round or cycle before all games of the previous round or cycle are finished. 2007This guarantees correct ordering in the games file, 2008even when multiple XBoard instances are concurrently playing games for the same tourney. 2009Default: sync after cycle, but not after round. 2010@item Select Engine 2011@itemx Tourney participants 2012@cindex Select Engine, Menu Item 2013@cindex Tourney participants, Menu Item 2014From the Select Engine listbox you can pick an engine from your list 2015of engines registered in the settings file, to be added to the tournament. 2016The engines selected so far will be listed in the ‘Tourney participants’ memo. 2017The latter is a normal text edit, so you can use normal text-editing functions 2018to delete engines you selected accidentally, or change their order. 2019Typing names here yourself is not recommended, because names that do not exactly match 2020one of the names from the selection listbox will lead to undefined behavior. 2021@item Tourney type 2022@cindex Tourney type, Menu Item 2023Here you can specify the type of tournament you want. 2024XBoard’s intrinsic tournament manager support round-robins (type = 0), 2025where each participant plays every other participant, and (multi-)gauntlets, 2026where one (or a few) so-called ‘gauntlet engines’ play an independent set of opponents. 2027In the latter case, you specify the number of gauntlet engines. 2028E.g. if you specified 10 engines, and tourney type = 2, 2029the first 2 engines each play the remaining 8. 2030A value of -1 instructs XBoard to play Swiss; for this to work an external 2031pairing engine must be specified through the @code{pairingEngine} option. 2032Each Swiss round will be considered a tourney cycle in that case. 2033Default:0 2034@item Number of tourney cycles 2035@itemx Default Number of Games in Match 2036@cindex Number of tourney cycles, Menu Item 2037@cindex Number of Games in Match, Menu Item 2038You can specify tourneys where every two opponents play each other multiple times. 2039Such multiple games can be played in a row, 2040as specified by the ‘number of games per pairing’, 2041or by repeating the entire tournament schedule a number of times 2042(specified by the ‘number of tourney cycles’). 2043The total number of times two engines meet will be the product of these two. 2044Default is 1 cycle; 2045the number of games per pairing is the same as the default number of match games, 2046stored in your settings file through the @code{defaultMatchGames} option. 2047@item Pause between Match Games 2048@cindex Pause between Match Games, Menu Item 2049Time (in milliseconds) XBoard waits before starting a new game after 2050a previous match or tournament game finishes. 2051Such a waiting period is important for engines that do not support 'ping', 2052as these sometimes still produce a move long after the game finished because 2053of the opponent resigning, which would be mistaken for a move in the next 2054game if that had already started. 2055@item Save Tourney Games on 2056@cindex Save Tourney Games, Menu Item 2057File where the tournament games are saved 2058(duplicate of the item in the @samp{Save Game Options}). 2059@item Game File with Opening Lines 2060@itemx File with Start Positions 2061@itemx Game Number 2062@itemx Position Number 2063@itemx Rewind Index after this many Games 2064@cindex Game File with Opening Lines, Menu Item 2065@cindex File with Start Positions, Menu Item 2066@cindex Game Number, Menu Item 2067@cindex Position Number, Menu Item 2068@cindex Rewind Index after, Menu Item 2069These items optionally specify the file with move sequences or board positions the tourney 2070games should start from. 2071The corresponding numbers specify the number of the game or position in the file. 2072Here a value -1 means automatic stepping through all games on the file, 2073-2 automatic stepping every two games. 2074The Rewind-Index parameter causes a stepping index to reset to one after reaching 2075a specified value. 2076A setting of -2 for the game number will also be effective in a tournament without 2077specifying a game file, but playing from the GUI book instead. 2078In this case the first (odd) games will randomly select from the book, 2079but the second (even) games will select the same moves from the book as the previous game. 2080(Note this leads to the same opening only if both engines use the GUI book!) 2081Default: No game or position file will be used. The default index if such a file is used is 1. 2082@item Disable own engine books by default 2083@cindex Disable own engine books by default, Menu Item 2084Setting this option reverses the default situation for use of the GUI opening book 2085in tournaments from what it normally is, namely not using it. 2086So unless the engine is installed with an option to explicitly specify it should 2087not use the GUI book (i.e. @code{-firstHasOwnBookUCI true}), 2088it will be made to use the GUI book. 2089@item Replace Engine 2090@itemx Upgrade Engine 2091@cindex Replace Engine, Menu Item 2092@cindex Upgrade Engine, Menu Item 2093With these two buttons you can alter the participants of an already running tournament. 2094After opening the Match Options dialog on an XBoard that is playing for the tourney, 2095you will see all the tourney parameters in the dialog fields. 2096You can then replace the name of one engine by that of another 2097by editing the @samp{participants} field. 2098(But preserve the order of the others!) 2099Pressing the button after that will cause the substitution. 2100With the @samp{Upgrade Engine} button the substitution will only affect future games. 2101With @samp{Replace Engine} all games the substituted engine has already played will 2102be invalidated, and they will be replayed with the substitute engine. 2103In this latter case the engine must not be playing when you do this, 2104but otherwise there is no need to pause the tournament play 2105for making a substitution. 2106@item Clone Tourney 2107@cindex CloneTourney, Menu Item 2108Pressing this button after you have specified an existing tournament file 2109will copy the contents of the latter to the dialog, 2110and then puts the originally proposed name for the tourney file back. 2111You can then run a tourney with the same parameters 2112(possibly after changing the proposed name of the tourney file for the new tourney) 2113by pressing 'OK'. 2114@item Continue Later 2115@cindex Continue Later, Menu Item 2116Pressing the @samp{Continue Later} button confirms the current value of all 2117items in the dialog and closes it, 2118but will not automatically start the tournament. 2119This allows you to return to the dialog later without losing the settings you 2120already entered, to adjust paramenters through other menu dialogs. 2121(The @samp{Common Engine Setting}, @samp{Time Control} and @samp{General Options} 2122dialogs can be accessed without closing the @samp{Tournament Options} dialog 2123through the respective buttons at the bottom of the latter.) 2124@end table 2125 2126@section Load Game Options 2127@cindex Load Game Options, Menu Item 2128Summons a dialog where you can set options that control loading of games. 2129@table @asis 2130@item Auto-Display Tags 2131@cindex Auto-Display Tags, Menu Item 2132Setting this option causes a window to pop up on loading a game, 2133displaying the PGN Tags for that game. 2134@item Auto-Display Comment 2135@cindex Auto-Display Comment, Menu Item 2136Setting this option causes a window to pop up whenever there 2137is a comment to (or variation on) the currently displayed move. 2138@item Auto-Play speed of loaded games 2139@cindex Auto-Play speed, Menu Item 2140This option sets the number of seconds between moves 2141when a newly loaded game is auto-playing. 2142A decimal fraction on the number is understood. 2143Setting it to -1 disables auto-play, staying in the start position 2144of the game after the loading completes. 2145Setting it to 0 will instantly move to the final position of the game. 2146The @samp{Auto-Play speed} is also used to determine the 2147analysis time for each move during @samp{Analyze Game}. 2148Note that auto-playing (including game analysis) can be stopped at any 2149time through the @samp{P} button above the board. 2150@item options to use in game-viewer mode 2151@cindex Game-Viewer options, Menu Item 2152Specifies the options automatically set when XBoard is invoked 2153with the option @code{-viewer} on its command line, 2154as will happen when it is started in response to clicking a PGN game file. 2155The default setting would start XBoard without engine 2156(due to the @code{-ncp} option), 2157but if you want it to automatically start with your favorite engine, 2158and automatically start analyzing, you could include the necessary 2159options for that here (e.g. @code{-fe <engine> -initialMode analysis}). 2160@item Thresholds for position filtering in game list 2161@cindex Thresholds for game selection, Menu Item 2162The following options can be set to limit the display of games 2163in the @samp{Game List} window to a sub-set, 2164meeting the specified criteria. 2165@item Elo of strongest player at least 2166@item Elo of weakest player at least 2167@cindex Elo limits, Menu Item 2168Games with an Elo tag specifying a lower rating for the mentioned player 2169will not be diplayed in the @samp{Game List}. 2170@item No games before year 2171@cindex Date limit, Menu item 2172Games with a Date tag before the specified year 2173will not be diplayed in the @samp{Game List}. 2174@item Final nr of pieces 2175@cindex Final number of pieces, Menu Item 2176A single number or a range (like 8-10) can be entered here, 2177and will cause only games where the number of men in the final 2178position is in the given range 2179will be diplayed in the @samp{Game List}. 2180@item Minimum nr consecutive positions 2181@cindex Consecutive positions, Menu Item 2182Specifies for how many consecutive positions the more fuzzy 2183position-matching criteria have to be satisfied 2184in order to count as a match. 2185@item Search mode 2186@itemx find position 2187@cindex Search mode, Menu Item 2188@cindex find position, Menu Item 2189XBoard can select games for display in the @samp{Game List} 2190based on whether (in addition to the conditions on the PGN tags) 2191they contain a position that matches the 2192position currently displayed on the board, 2193by pressing the @samp{find position} 2194or @samp{narrow} buttons in the @samp{Game List} window. 2195The @samp{Search mode} setting determines what counts as match. 2196You can search for an exact match, 2197a position that has all shown material in the same place, 2198but might contain additional material, 2199a position that has all Pawns in the same place, 2200but can have the shown material anywhere, 2201a position that can have all shown material anywhere, 2202or a position that has material between certain limits anywhere. 2203For the latter you have to place the material that must minimally be present 2204in the four lowest ranks of the board, 2205and optional additional material in the four highest ranks of the board. 2206You can request the optional material to be balanced, 2207i.e. equal for white and black. 2208@item narrow 2209@cindex narrow, Menu Item 2210The @samp{narrow} button is similar in fuction to the @samp{find position} button, 2211but only searches in the already selected games, 2212rather than the complete game file, 2213and can thus be used to refine a search based on multiple criteria. 2214@item Also match reversed colors 2215@itemx Also match left-right flipped position 2216@cindex Match reversed colors, Menu Item 2217@cindex Match left-right flipped position, Menu Item 2218When looking for matching positions rather than by material, 2219these settings determine whether mirror images 2220(in case of a vertical flip in combination with color reversal) 2221will be also considered a match. 2222The left-right flipping is only useful after all castling rights 2223have expired (or in Xiangqi). 2224@end table 2225 2226@section Save Game Options 2227@cindex Save Game Options, Menu Item 2228Summons a dialog where you can specify whether XBoard should 2229automatically save files of games when they finish, 2230and where and how to do that. 2231@table @asis 2232@item Auto-Save Games 2233@cindex Auto-Save Games, Menu Item 2234When set XBoard will automatically save games on a file as they finish. 2235(Not when you abort them by pressing @samp{New Game}, though!) 2236It will either prompt you for a filename, 2237or use the file specified by the @code{saveGameFile} option. 2238@item Own Games Only 2239@cindex Own Games Only, Menu Item 2240Setting this option will exclude games by others observed on an 2241Internet Chess Server from automatic saving. 2242@item Save Games on File 2243@cindex Save Games on File, Menu Item 2244Name of the file on which games should be saved automatically. 2245Games are always appended to the file, 2246and will never overwrite anything. 2247@item Save Final Position on File 2248@cindex Save Final Position on File, Menu Item 2249When a name is defined, the final position of each game 2250is appended to the mentioned file. 2251@item PGN Event Header 2252@cindex PGN Event Header, Menu Item 2253Specifies the name of the event used in the PGN event tag 2254of new games that you create. 2255@item Old Save Style 2256@cindex Old Save Style, Menu Item 2257Saves games in an obsolete and now long forgotten format, 2258rather than as PGN. Never use this for orthodox Chess! 2259@item Include Number Tag in tourney PGN 2260@cindex Include Number Tag in tourney PGN, Menu Item 2261When on this option will cause the non-standard 'Number' tag 2262to be written in any game saved in PGN format. 2263It will contain the unique number of the game in the tourney. 2264(As opposed to the 'Round' tag, which can be shared by many games.) 2265@item Save Score/Depth Info in PGN 2266@cindex Save Score/Depth in PGN, Menu Item 2267When on this option will cause the score and depth at which it was 2268calculated by an engine, and (when available) thinking time 2269to be saved with the move as a comment to the move, 2270in the format @{score/depth time@}. 2271Here 'score'is in pawn units from the point of view of the player 2272that made the move, with two digits behind the decimal Pawn. 2273'Time' is in seconds, or min:sec. 2274@item Save Out-of-Book Info in PGN 2275@cindex Save Out-of-Book Info in PGN, Menu Item 2276When on this option causes the score of the first move 2277the engine made after coming out of book in an 'Annotator' PGN tag. 2278@end table 2279 2280@section Game List 2281@cindex Game List Tags, Menu Item 2282Pops up a dialog where you can select the PGN tags that should appear 2283on the lines in the @samp{Game List}, and their order. 2284 2285@section Sound Options 2286@cindex Sound Options, Menu Item 2287Summons a dialog where you can specify the sounds that should accompany 2288various events that can occur in XBoard. 2289Most events are only relevant to ICS play, 2290but the move sound is an important exception. 2291For each event listed in the dialog, 2292you can select a standard sound from a menu. 2293@table @asis 2294@item Sound Program 2295@cindex Sound Program, Menu Item 2296Specifies the command XBoard should invoke to play sounds. 2297The specified text will be suffixed by the name of the sound file, 2298and then run as a command. 2299@item Sounds Directory 2300@cindex Sounds Directory, Menu Item 2301Specifies the directory where XBoard will look for files with 2302the names of the standard sounds. 2303@item User WAV File 2304@cindex User WAV File, Menu Item 2305When we type a filename here, it can be assigned to the events 2306by selecting @samp{Above WAV File} from the drop downs. 2307@item Try-Out Sound 2308@itemx Play 2309@cindex Try-Out Sound, Menu Item 2310The 'event' triggering the Try-Out sound is pressing 2311of the @samp{Play} button behind it. 2312This allows you to judge the sounds. 2313@end table 2314 2315@section Save Settings Now 2316@cindex Save Settings Now, Menu Item 2317Selecting this menu item causes the current XBoard settings to be 2318written to the settings file, (.xboardrc in your home directory), 2319so they will also apply in future sessions. 2320Note that some settings are 'volatile', and are not saved, 2321because XBoard considers it too unlikely that you want those to apply 2322next time. 2323In particular this applies to the Chess program, and all options 2324giving information on those Chess programs (such as their directory, 2325if they have their own opening book, if they are UCI or native XBoard), 2326or the variant you are playing. 2327Such options would still be understood when they appear in the settings 2328file in case they were put there with the aid of a text editor, but they 2329would disappear from the file as soon as you save the settings. 2330 2331Note that XBoard no longer pays attention to options values specified 2332in the .Xresources file. 2333(Specifying key bindings there will still work, though.) 2334To alter the default of volatile options, you can use the following method: 2335Rename your ~/.xboardrc settings file (to ~/.yboardrc, say), and create 2336a new file ~/.xboardrc, which only contains the options 2337 2338@example 2339-settingsFile ~/.yboardrc 2340-saveSettingsFile ~/.yboardrc 2341@end example 2342 2343@noindent 2344This will cause your settings to be saved on ~/.yboardrc in the future, 2345so that ~/.xboardrc is no longer overwritten. 2346You can then safely specify volatile options in ~/.xboardrc, either 2347before or after the settingsFile options. 2348Note that when you specify persistent options after the settingsFile options 2349in this ~/.xboardrc, you will essentially turn them into volatile options 2350with the specified value as default, because that value will overrule 2351the value loaded from the settings file (being read later). 2352 2353@section Save Settings on Exit 2354@cindex Save Settings on Exit, Menu Item 2355Setting this option has no immediate effect, but causes the settings 2356to be saved when you quit XBoard. What happens then is otherwise 2357identical to what happens when you use select "Save Settings Now", 2358see there. 2359 2360@node Help Menu 2361@section Help Menu 2362@cindex Menu, Help 2363@cindex Help Menu 2364@table @asis 2365@item Info XBoard 2366@cindex Info XBoard, Menu Item 2367Displays the XBoard documentation in info format. For this feature to 2368work, you must have the GNU info program installed on your system, and 2369the file @file{xboard.info} must either be present in the current 2370working directory, or have been installed by the @samp{make install} 2371command when you built XBoard. 2372@item Man XBoard 2373@cindex Man XBoard, Menu Item 2374Displays the XBoard documentation in man page format. 2375The @kbd{F1} key is a keyboard equivalent. For this 2376feature to work, the file @file{xboard.6} must have been installed by 2377the @samp{make install} command when you built XBoard, and the 2378directory it was placed in must be on the search path for your 2379system's @samp{man} command. 2380@item About XBoard 2381@cindex About XBoard, Menu Item 2382Shows the current XBoard version number. 2383@end table 2384 2385@node Keys 2386@section Other Shortcut Keys 2387@cindex Keys 2388@cindex Shortcut keys 2389@table @asis 2390@item Show Last Move 2391@cindex Show Last Move, Shortcut Key 2392By hitting @kbd{Enter} the last move will be re-animated. 2393@item Load Next Game 2394@cindex Load Next Game, Menu Item 2395Loads the next game from the last game record file you loaded. 2396The @kbd{Alt+PgDn} key triggers this action. 2397@item Load Previous Game 2398@cindex Load Previous Game, Menu Item 2399Loads the previous game from the last game record file you 2400loaded. The @kbd{Alt+PgUp} key triggers this action. 2401Not available if the last game was loaded from a pipe. 2402@item Reload Same Game 2403@cindex Reload Same Game, Menu Item 2404Reloads the last game you loaded. 2405Not available if the last game was loaded from a pipe. 2406Currently no keystroke is assigned to this ReloadGameProc. 2407@item Reload Same Position 2408@cindex Reload Same Position, Menu Item 2409Reloads the last position you loaded. 2410Not available if the last position was loaded from a pipe. 2411Currently no keystroke is assigned to this ReloadPositionProc. 2412@end table 2413 2414In the Xaw build of XBoard you can add or remove shortcut keys 2415using the X resources @code{paneA.translations}. 2416Here is an example of what could go into your 2417@file{.Xdefaults} file: 2418 2419@example 2420XBoard*paneA.translations: \ 2421 Shift<Key>?: MenuItem(Help.About) \n\ 2422 Ctrl<Key>y: MenuItem(Action.Accept) \n\ 2423 Ctrl<Key>n: MenuItem(Action.Decline) \n\ 2424 Ctrl<Key>i: MenuItem(Nothing) 2425@end example 2426@noindent 2427So the key should always be bound to the action 'MenuItem', 2428with the (hierarchical) name of the menu item as argument. 2429There are a few actions available for which no menu item exists: 2430Binding a key to @code{Nothing} makes it do nothing, thus removing 2431it as a shortcut key. Other such functions that can be bound to keys 2432are: 2433 2434@example 2435AboutGame, DebugProc (switches the -debug option on or off), 2436LoadNextGame, LoadPrevGame, ReloadGame, ReloadPosition. 2437@end example 2438 2439@node Options 2440@chapter Options 2441@cindex Options 2442@cindex Options 2443 2444This section documents the command-line options to XBoard. You can 2445set these options in two ways: by typing them on the shell command 2446line you use to start XBoard, or by editing the settings file 2447(usually ~/.xboardrc) to alter the value of the setting that was 2448saved there. Some of the options 2449cannot be changed while XBoard is running; others set the initial 2450state of items that can be changed with the @ref{Options} menu. 2451 2452Most of the options have both a long name and a short name. To turn a 2453boolean option on or off from the command line, either give its long 2454name followed by the value true or false 2455(@samp{-longOptionName true}), or give just the short name to turn the 2456option on (@samp{-opt}), or the short name preceded by @samp{x} to 2457turn the option off (@samp{-xopt}). For options that take strings or 2458numbers as values, you can use the long or short option names 2459interchangeably. 2460 2461@menu 2462* Chess engine options:: Controlling the chess engine. 2463* UCI + WB Engine Settings:: Setting some very common engine parameters 2464* Tournament options:: Running tournaments and matches between engines. 2465* ICS options:: Connecting to and using ICS. 2466* Load and Save options:: Input/output options. 2467* User interface options:: Look and feel options. 2468* Adjudication Options:: Control adjudication of engine-engine games. 2469* Install options:: Maintaining and extending the XBoard install. 2470* Other options:: Miscellaneous. 2471@end menu 2472 2473@node Chess engine options 2474@section Chess Engine Options 2475@cindex options, Chess engine 2476@cindex Chess engine options 2477@table @asis 2478@item -tc or -timeControl minutes[:seconds] 2479@cindex tc, option 2480@cindex timeControl, option 2481Each player begins with his clock set to the @code{timeControl} period. 2482Default: 5 minutes. 2483The additional options @code{movesPerSession} and @code{timeIncrement} 2484are mutually exclusive. 2485@item -mps or -movesPerSession moves 2486@cindex mps, option 2487@cindex movesPerSession, option 2488When both players have made @code{movesPerSession} moves, a 2489new @code{timeControl} period is added to both clocks. Default: 40 moves. 2490@item -inc or -timeIncrement seconds 2491@cindex inc, option 2492@cindex timeIncrement, option 2493If this option is specified, @code{movesPerSession} is ignored. 2494Instead, after each player's move, @code{timeIncrement} seconds are 2495added to his clock. 2496Use @samp{-inc 0} if you want to require the entire 2497game to be played in one @code{timeControl} period, with no increment. 2498Default: -1, which specifies @code{movesPerSession} mode. 2499@item -clock/-xclock or -clockMode true/false 2500@cindex clock, option 2501@cindex clockMode, option 2502Determines whether or not to display the chess clocks. If clockMode is 2503false, the clocks are not shown, but the side that is to play next 2504is still highlighted. Also, unless @code{searchTime} 2505is set, the chess engine still keeps track of the clock time and uses it to 2506determine how fast to make its moves. 2507@item -shoMoveTime true/false 2508@cindex showMoveTime, option 2509When this option is set the time that has been thought about the current move 2510will be displayed behind the remaining time in parentheses (in seconds). 2511Default: false. 2512@item -st or -searchTime minutes[:seconds] 2513@cindex st, option 2514@cindex searchTime, option 2515Tells the chess engine to spend at most the given amount of time 2516searching for each of its moves. Without this option, the chess engine 2517chooses its search time based on the number of moves and amount 2518of time remaining until the next time control. 2519Setting this option also sets clockMode to false. 2520@item -depth or -searchDepth number 2521@cindex sd, option 2522@cindex searchDepth, option 2523Tells the chess engine to look ahead at most the given number of moves 2524when searching for a move to make. Without this option, the chess 2525engine chooses its search depth based on the number of moves and 2526amount of time remaining until the next time control. With the option, 2527the engine will cut off its search early if it reaches the specified depth. 2528@item -firstNPS number 2529@itemx -secondNPS number 2530@cindex firstNPS, option 2531@cindex secondNPS, option 2532Tells the chess engine to use an internal time standard based on its node count, 2533rather then wall-clock time, to make its timing decisions. 2534The time in virtual seconds should be obtained by dividing the node count 2535through the given number, like the number was a rate in nodes per second. 2536Xboard will manage the clocks in accordance with this, relying on the number 2537of nodes reported by the engine in its thinking output. If the given number equals zero, 2538it can obviously not be used to convert nodes to seconds, and the time reported 2539by the engine is used to decrement the XBoard clock in stead. The engine is supposed to 2540report in CPU time it uses, rather than wall-clock time, in this mode. This option 2541can provide fairer conditions for engine-engine matches on heavily loaded machines, 2542or with very fast games (where the wall clock is too inaccurate). 2543@code{showThinking} must be on for this option to work. Default: -1 (off). 2544Not many engines might support this yet! 2545@item -firstTimeOdds factor 2546@itemx -secondTimeOdds factor 2547@cindex firstTimeOdds, option 2548@cindex secondTimeOdds, option 2549Reduces the time given to the mentioned engine by the given factor. 2550If pondering is off, the effect is indistinguishable from what would happen 2551if the engine was running on an n-times slower machine. Default: 1. 2552@item -timeOddsMode mode 2553@cindex timeOddsMode, option 2554This option determines how the case is handled where both engines have a time-odds handicap. 2555If mode=1, the engine that gets the most time will always get the nominal time, 2556as specified by the time-control options, and its opponent's time is renormalized accordingly. 2557If mode=0, both play with reduced time. Default: 0. 2558@item -hideThinkingFromHuman true/false 2559Controls the Hide Thinking option. @xref{Options Menu}. Default: true. 2560(Replaces the Show-Thinking option of older xboard versions.) 2561@item -thinking/-xthinking or -showThinking true/false 2562@cindex thinking, option 2563@cindex showThinking, option 2564Forces the engine to send thinking output to xboard. 2565Used to be the only way to control if thinking output was displayed 2566in older xboard versions, 2567but as the thinking output in xboard 4.3 is also used for several other 2568purposes (adjudication, storing in PGN file) the display of it is now controlled 2569by the new option Hide Thinking. @xref{Options Menu}. Default: false. 2570(But if xboard needs the thinking output for some purpose, 2571it makes the engine send it despite the setting of this option.) 2572@item -ponder/-xponder or -ponderNextMove true/false 2573@cindex ponder, option 2574@cindex ponderNextMove, option 2575Sets the Ponder Next Move menu option. @xref{Options Menu}. Default: true. 2576@item -smpCores number 2577Specifies the maximum number of CPUs an SMP engine is allowed to use. 2578Only works for engines that support the XBoard/WinBoard-protocol cores feature. 2579@item -mg or -matchGames n 2580@cindex mg, option 2581@cindex matchGames, option 2582Automatically runs an n-game match between two chess engines, 2583with alternating colors. 2584If the @code{loadGameFile} or @code{loadPositionFile} option is set, 2585XBoard 2586starts each game with the given opening moves or the given position; 2587otherwise, the games start with the standard initial chess position. 2588If the @code{saveGameFile} option is set, a move record for the 2589match is appended to the specified file. If the @code{savePositionFile} 2590option is set, the final position reached in each game of the match is appended 2591to the specified file. When the match is over, XBoard 2592displays the match score and exits. Default: 0 (do not run a match). 2593@item -mm/-xmm or -matchMode true/false 2594@cindex mm, option 2595@cindex matchMode, option 2596Setting @code{matchMode} to true is equivalent to setting 2597@code{matchGames} to 1. 2598@item -sameColorGames n 2599@cindex sameColorGames, option 2600Automatically runs an n-game match between two chess engines, 2601without alternating colors. 2602Otherwise the same applies as for the @samp{-matchGames} option, 2603over which it takes precedence if both are specified. (See there.) 2604Default: 0 (do not run a match). 2605@item -epd 2606@cindex epd, option 2607This option puts XBoard in a special mode for solving EPD test-suites, 2608for the entire duration of the session. 2609In this mode games are aborted after a single move, 2610and that move will be compared with the best-move or avoid-move 2611from the EPD position description from which the 'game' was started. 2612Playing a best move counts as a win, playing an avoid move as a loss, 2613and playing any other move counts as a draw. 2614This option should be used in combination with match mode, 2615and an EPD file of starting positions with an auto-incrementing index. 2616Color assignment will be such that the first engine plays all moves, 2617and the second engine will be never involved. 2618The results for individual positions, 2619as well as the time used for solving them, 2620will be reported in the lower pane of the Engine Output window. 2621@item -fcp or -firstChessProgram program 2622@itemx -scp or -secondChessProgram program 2623@cindex fcp, option 2624@cindex firstChessProgram, option 2625@cindex scp, option 2626@cindex secondChessProgram, option 2627Name of first and second chess engine, respectively. 2628A second chess engine is started only in Two Machines (match) mode, 2629or in Analyze mode with two engines. 2630The second engine is by default the same as the first. 2631Default for the first engine: @file{fairymax}. 2632@item -fe or -firstEngine nickname 2633@itemx -se or -secondEngine nickname 2634@cindex se, option 2635@cindex secondEngine, option 2636@cindex fe, option 2637@cindex firstEngine, option 2638This is an alternative to the @code{fcp} and @code{scp} options 2639for specifying the first and second engine, 2640for engines that were already registered (using the @samp{Load Engine} dialog) 2641in XBoard's settings file. 2642It will not only retrieve the real name of the engine, 2643but also all options configured with it. 2644(E.g. if it is UCI, whether it should use book.) 2645@item -fb/-xfb or -firstPlaysBlack true/false 2646@cindex fb, option 2647@cindex firstPlaysBlack, option 2648In games between two chess engines, firstChessProgram normally plays 2649white. If this option is true, firstChessProgram plays black. In a 2650multi-game match, this option affects the colors only for the first 2651game; they still alternate in subsequent games. 2652@item -fh or -firstHost host 2653@itemx -sh or -secondHost host 2654@cindex fh, option 2655@cindex firstHost, option 2656@cindex sh, option 2657@cindex secondHost, option 2658Hosts on which the chess engines are to run. The default for 2659each is @file{localhost}. If you specify another host, XBoard 2660uses @file{rsh} to run the chess engine there. (You can substitute a 2661different remote shell program for rsh using the @code{remoteShell} 2662option described below.) 2663@item -fd or -firstDirectory dir 2664@itemx -sd or -secondDirectory dir 2665@cindex fd, option 2666@cindex firstDirectory, option 2667@cindex sd, option 2668@cindex secondDirectory, option 2669Working directories in which the chess engines are to be run. 2670The default is "", which means to run the chess engine 2671in the same working directory as XBoard 2672itself. (See the CHESSDIR environment variable.) 2673This option is effective only when the chess engine is being run 2674on the local host; it does not work if the engine is run remotely 2675using the -fh or -sh option. 2676@item -initString string or -firstInitString 2677@itemx -secondInitString string 2678@cindex initString, option 2679@cindex firstInitString, option 2680@cindex secondInitString, option 2681The string that is sent to initialize each chess engine for a new game. 2682Default: 2683 2684@example 2685new 2686random 2687@end example 2688@noindent 2689Setting this option from the command line is tricky, because you must 2690type in real newline characters, including one at the very end. 2691In most shells you can do this by 2692entering a @samp{\} character followed by a newline. 2693Using the character sequence @samp{\n} in the string should work too, though. 2694 2695If you change this option, don't remove the @samp{new} 2696command; it is required by all chess engines to 2697start a new game. 2698 2699You can remove the @samp{random} command if you like; including it 2700causes GNU Chess 4 to randomize its move selection slightly so that it 2701doesn't play the same moves in every game. Even without 2702@samp{random}, GNU Chess 4 randomizes its choice of moves from its 2703opening book. Many other chess engines ignore this command entirely 2704and always (or never) randomize. 2705 2706You can also try adding other commands to the initString; see the 2707documentation of the chess engine you are using for details. 2708@item -firstComputerString string 2709@itemx -secondComputerString string 2710@cindex firstComputerString, option 2711@cindex secondComputerString, option 2712The string that is sent to the chess engine if its opponent is another 2713computer chess engine. The default is @samp{computer\n}. Probably the 2714only useful alternative is the empty string (@samp{}), which keeps the 2715engine from knowing that it is playing another computer. 2716@item -reuse/-xreuse or -reuseFirst true/false 2717@itemx -reuse2/-xreuse2 or -reuseSecond true/false 2718@cindex reuse, option 2719@cindex reuseFirst, option 2720@cindex reuse2, option 2721@cindex reuseSecond, option 2722If the option is false, 2723XBoard kills off the chess engine after every game and starts 2724it again for the next game. 2725If the option is true (the default), 2726XBoard starts the chess engine only once 2727and uses it repeatedly to play multiple games. 2728Some old chess engines may not work properly when 2729reuse is turned on, but otherwise games will start faster if it is left on. 2730@item -firstProtocolVersion version-number 2731@itemx -secondProtocolVersion version-number 2732@cindex firstProtocolVersion, option 2733@cindex secondProtocolVersion, option 2734This option specifies which version of the chess engine communication 2735protocol to use. By default, version-number is 2. In version 1, the 2736"protover" command is not sent to the engine; since version 1 is a 2737subset of version 2, nothing else changes. Other values for 2738version-number are not supported. 2739@item -firstScoreAbs true/false 2740@itemx -secondScoreAbs true/false 2741@cindex firstScoreAbs, option 2742@cindex secondScoreAbs, option 2743If this option is set, the score reported by the engine is taken to be 2744that in favor of white, even when the engine plays black. 2745Important when XBoard uses the score for adjudications, or in PGN reporting. 2746@item -niceEngines priority 2747@cindex niceEngines, option 2748This option allows you to lower the priority of the engine processes, 2749so that the generally insatiable hunger for CPU time of chess engines does not interfere so much 2750with smooth operation of XBoard (or the rest of your system). 2751Negative values could increase the engine priority, which is not recommended. 2752@item -firstOptions string 2753@itemx -secondOptions string 2754@cindex firstOptions, option 2755@cindex secondOptions, option 2756The given string is a comma-separated list of (option name=option value) pairs, 2757like the following example: "style=Karpov,blunder rate=0". 2758If an option announced by the engine at startup through the feature commands of the XBoard/WinBoard protocol 2759matches one of the option names (i.e. "style" or "blunder rate"), 2760it would be set to the given value (i.e. "Karpov" or 0) 2761through a corresponding option command to the engine. 2762This provided that the type of the value (text or numeric) matches as well. 2763@item -firstNeedsNoncompliantFEN string 2764@itemx -secondNeedsNoncompliantFEN string 2765@cindex firstNeedsNoncompliantFEN, option 2766@cindex secondNeedsNoncompliantFEN, option 2767The castling rights and e.p. fields of the FEN sent to the mentioned engine 2768with the setboard command will be replaced by the given string. This can for 2769instance be used to run engines that do not understand Chess960 FENs in 2770variant fischerandom, to make them at least understand the opening position, 2771through setting the string to "KQkq -". (Note you also have to give the e.p. field!) 2772Other possible applications are to provide work-arounds for engines that want to see 2773castling and e.p. fields in variants that do not have castling or e.p. 2774(shatranj, courier, xiangqi, shogi) so that XBoard would normally omit them 2775(string = "- -"), or to add variant-specific fields that are not yet supported by XBoard 2776(e.g. to indicate the number of checks in 3check). 2777@item -shuffleOpenings 2778@cindex shuffleOpenings, option 2779Forces shuffling of the opening setup in variants that normally have a fixed initial position. 2780Shufflings are symmetric for black and white, and exempt King and Rooks in variants 2781with normal castling. 2782Remains in force until a new variant is selected. 2783@item -fischerCastling 2784@cindex fischerCastling, option 2785Specifies Fischer castling (as in Chess960) should be enabled in variants 2786that normally would not have it. 2787Remains in force until a new variant is selected. 2788@end table 2789 2790@node UCI + WB Engine Settings 2791@section UCI + WB Engine Settings 2792@cindex Engine Settings 2793@cindex Settings, Engine 2794@table @asis 2795@item -fUCI or -firstIsUCI true/false 2796@itemx -sUCI or -secondIsUCI true/false 2797@cindex fUCI, option 2798@cindex sUCI, option 2799@cindex firstIsUCI, option 2800@cindex secondIsUCI, option 2801Indicates if the mentioned engine executable file is a UCI engine, 2802and should be run with the aid of the Polyglot adapter rather than directly. 2803Xboard will then pass the other UCI options and engine name to Polyglot 2804on its command line, according to the option @code{adapterCommand}. 2805@item -fUCCI 2806@itemx -sUCCI 2807@itemx -fUSI 2808@itemx -sUSI 2809@cindex fUCCI, option 2810@cindex sUCCI, option 2811@cindex fUSI, option 2812@cindex sUSI, option 2813Options similar to @code{fUCI} and @code{sUCI}, except that they 2814use the indicated engine with the protocol adapter specified in 2815the @samp{uxiAdapter} option. 2816This can then be configured for running a UCCI or USI adapter, 2817as the need arises. 2818@item -adapterCommand string 2819@cindex adapterCommand, option 2820The string contains the command that should be issued by XBoard 2821to start an engine that is accompanied by the @code{fUCI} option. 2822Any identifier following a percent sign in the command (e.g. %fcp) 2823will be considered the name of an XBoard option, and be replaced 2824by the value of that option at the time the engine is started. 2825For starting the second engine, any leading "f" or "first" in 2826the option name will first be replaced by "s" or "second", 2827before finding its value. 2828Default: 'polyglot -noini -ec "%fcp" -ed "%fd"' 2829@item -uxiAdapter string 2830@cindex uxiAdapter, option 2831Similar to @code{adapterCommand}, but used for engines accompanied 2832by the @code{fUCCI} or @code{fUSI} option, so you can configure 2833XBoard to be ready to handle more than one flavor of non-native protocols. 2834Default: "" 2835@item -polyglotDir filename 2836@cindex polyglotDir, option 2837Gives the name of the directory in which the Polyglot adapter for UCI engines resides. 2838Default: "". 2839@item -usePolyglotBook true/false 2840@cindex usePolyglotBook, option 2841Specifies if the Polyglot book should be used as GUI book. 2842@item -polyglotBook filename 2843@cindex polyglotBook, option 2844Gives the filename of the opening book. 2845The book is only used when the @code{usePolyglotBook} option is set to true, 2846and the option @code{firstHasOwnBookUCI} or @code{secondHasOwnBookUCI} 2847applying to the engine is set to false. 2848The engine will be kept in force mode as long as the current position is in book, 2849and XBoard will select the book moves for it. Default: "". 2850@item -fNoOwnBookUCI or -firstXBook or -firstHasOwnBookUCI true/false 2851@itemx -sNoOwnBookUCI or -secondXBook or -secondHasOwnBookUCI true/false 2852@cindex fNoOwnBookUCI, option 2853@cindex sNoOwnBookUCI, option 2854@cindex firstHasOwnBookUCI, option 2855@cindex secondHasOwnBookUCI, option 2856@cindex firstXBook, option 2857@cindex secondXBook, option 2858Indicates if the mentioned engine has its own opening book it should play from, 2859rather than using the external book through XBoard. 2860Default: depends on setting of the option @code{discourageOwnBooks}. 2861@item -discourageOwnBooks true/false 2862@cindex discourageOwnBooks, option 2863When set, newly loaded engines will be assumed to use the GUI book, 2864unless they explicitly specify differently. 2865Otherwise they will be assumed to not use the GUI book, 2866unless the specify differently (e.g. with @code{firstXBook}). 2867Default: false. 2868@item -bookDepth n 2869@cindex bookDepth, option 2870Limits the use of the GUI book to the first n moves of each side. 2871Default: 12. 2872@item -bookVariation n 2873@cindex bookVariation, option 2874A value n from 0 to 100 tunes the choice of moves from the GUI books 2875from totally random to best-only. Default: 50 2876@item -mcBookMode 2877@cindex mcBookMode, option 2878When this volatile option is specified, the probing algorithm of the 2879GUI book is altered to always select the move that is most under-represented 2880based on its performance. 2881When all moves are played in approximately the right proportion, 2882a book miss will be reported, to give the engine opportunity to 2883explore a new move. 2884In addition score of the moves will be kept track of during the session 2885in a book buffer. 2886By playing an match in this mode, a book will be built from scratch. 2887The only output are the saved games, which can be converted to an 2888actual book later, with the @samp{Save Games as Book} command. 2889The latter command can also be used to pre-fill the book buffer 2890before adding new games based on the probing algorithm. 2891@item -fn string or -firstPgnName string 2892@itemx -sn string or -secondPgnName string 2893@cindex firstPgnName, option 2894@cindex secondPgnName, option 2895@cindex fn, option 2896@cindex sn, option 2897Indicates the name that should be used for the engine in PGN tags of 2898engine-engine games. 2899Intended to allow you to install versions of the same engine with different settings, 2900and still distinguish them. 2901Default: "". 2902@item -defaultHashSize n 2903@cindex defaultHashSize, option 2904Sets the size of the hash table to n MegaBytes. Together with the EGTB cache size 2905this number is also used to calculate the memory setting of XBoard/WinBoard engines, 2906for those that support the memory feature of the XBoard/WinBoard protocol. Default: 64. 2907@item -defaultCacheSizeEGTB n 2908@cindex defaultCacheSizeEGTB, option 2909Sets the size of the EGTB cache to n MegaBytes. Together with the hash-table size 2910this number is also used to calculate the memory setting of XBoard/WinBoard engines, 2911for those that support the memory feature of the XBoard/WinBoard protocol. Default: 4. 2912@item -defaultPathEGTB filename 2913@cindex defaultPathEGTB, option 2914Gives the name of the directory where the end-game tablebases are installed, for UCI engines. 2915Default: "/usr/local/share/egtb". 2916@item -egtFormats string 2917@cindex egtFormats, option 2918Specifies which end-game tables are installed on the computer, and where. 2919The argument is a comma-separated list of format specifications, 2920each specification consisting of a format name, a colon, and a directory path name, 2921e.g. "nalimov:/usr/local/share/egtb". 2922If the name part matches that of a format that the engine requests through a feature command, 2923xboard will relay the path name for this format to the engine through an egtpath command. 2924One egtpath command for each matching format will be sent. 2925Popular formats are "nalimov" and "gaviota" DTM tablebases, 2926syzygy DTZ tablebases and "scorpio" bitbases. 2927Default: "". 2928@item -firstChessProgramNames=@{names@} 2929@cindex firstChessProgramNames, option 2930This option lets you customize the listbox with chess-engine names 2931that appears in the @samp{Load Engine} and @samp{Tournament Options} dialog. 2932It consists of a list of strings, one per line. 2933When an engine is loaded, the corresponding line is prefixed with "-fcp ", 2934and processed like it appeared on the command line. 2935That means that apart from the engine command, 2936it can contain any number of XBoard options you want to use with this engine. 2937(Commonly used options here are -fd, -firstXBook, -fUCI, -variant.) 2938 2939The value of this option is gradually built as you load new engines 2940through the @samp{Load Engine} menu dialog, with @samp{Add to list} ticked. 2941To change it in other ways, (e.g. deleting engines), 2942use the menu item @samp{Edit Engine List} in the @samp{Engine} menu. 2943@end table 2944 2945@node Tournament options 2946@section Tournament options 2947@cindex Tournament Options 2948@cindex Options, Tournament 2949@table @asis 2950@item -defaultMatchGames n 2951@cindex defaultMatchGames, option 2952Sets the number of games that will be used for a match between two engines 2953started from the menu to n. Also used as games per pairing in other tournament 2954formats. Default: 10. 2955@item -matchPause n 2956@cindex matchPause, option 2957Specifies the duration of the pause between two games of a match or tournament 2958between engines as n milliseconds. 2959Especially engines that do not support ping need this option, 2960to prevent that the move they are thinking on when an opponent unexpectedly 2961resigns will be counted for the next game, (leading to illegal moves there). 2962Default: 10000. 2963@item -tf filename or -tourneyFile filename 2964@cindex tf, option 2965@cindex tourneyFile, option 2966Specifies the name of the tournament file used in match mode 2967to conduct a multi-player tournament. 2968This file is a special settings file, 2969which stores the description of the tournament (including progress info), 2970through normal options (e.g. for time control, load and save files), 2971and through some special-purpose options listed below. 2972@item -tt number or -tourneyType number 2973@cindex tt, option 2974@cindex tourneyType, option 2975Specifies the type of tourney: 0 = round-robin, 2976N>0 = (multi-)gauntlet with N gauntlet engines, 2977-1 = Swiss through external pairing engine. 2978Volatile option, but stored in tourney file. 2979@item -cy number or -tourneyCycles number 2980@cindex cy, option 2981@cindex tourneyCycles, option 2982Specifies the number of cycles in a tourney. 2983Volatile option, but stored in tourney file. 2984@item -participants list 2985@cindex participants, option 2986The list is a multi-line text string that specifies engines 2987occurring in the @code{firstChesProgramNames} list 2988in the settings file by their (implied or explicitly given) nicknames, 2989one engine per line. 2990The mentioned engines will play in the tourney. 2991Volatile option, but stored in tourney file. 2992@item -results string 2993@cindex results, option 2994The string of +=- characters lists the result of all played games in a tourney. 2995Games currently playing are listed as *, 2996while a space indicates a game that is not yet played. 2997Volatile option, but stored in tourney file. 2998@item -defaultTourneyName string 2999@cindex defaultTourneyName, option 3000Specifies the name of the tournament file XBoard should propose 3001when the @samp{Match Options} dialog is opened. 3002Any %y, %M, %d, %h, %m, %s in the string are replaced by the current 3003year, month, day of the month, hours, minutes, seconds of the current time, 3004respectively, as two-digit number. 3005A %Y would be replaced by the year as 4-digit number. Default: empty string. 3006@item -pairingEngine filename 3007@cindex pairingEngine, option 3008Specifies the external program to be used to pair the participants in Swiss tourneys. 3009XBoard communicates with this engine in the same way as it communicates with Chess engines. 3010The only commands sent to the pairing engine are “results N string”, 3011(where N is the number of participants, 3012and string the results so far in the format of the results option), 3013and “pairing N”, (where N is the number of the tourney game). 3014To the latter the pairing engine should answer with “A-B”, 3015where A and B are participant numbers (in the range 1-N). 3016(There should be no reply to the results command.) Default: empty string. 3017@item -afterGame string 3018@itemx -afterTourney string 3019@cindex afterGame, option 3020@cindex afterTourney, option 3021When non-empty, the given string will be executed as a system command 3022after each tournament game, or after the tourney completes, respectively. 3023This can be used, for example, to autmatically run a cross-table generator 3024on the PGN file where games are saved, to update the tourney standings. 3025Default: "" 3026@item -syncAfterRound true/false 3027@itemx -syncAfterCycle true/false 3028@cindex syncAfterRound, option 3029@cindex syncAfterCycle, option 3030Controls whether different instances of XBoard concurrently running the 3031same tournament will wait for each other. 3032Defaults: sync after cycle, but not after round. 3033@item -seedBase number 3034@cindex seedBase, option 3035Used to store the seed of the pseudo-random-number generator in the 3036tourneyFile, so that separate instances of XBoard working on the same 3037tourney can take coherent 'random' decisions, such as picking an 3038opening for a given game number. 3039@end table 3040 3041@node ICS options 3042@section ICS options 3043@cindex ICS options 3044@cindex Options, ICS 3045@table @asis 3046@item -ics/-xics or -internetChessServerMode true/false 3047@cindex ics, option 3048@cindex internetChessServerMode, option 3049Connect with an Internet Chess Server to play chess against its 3050other users, observe games they are playing, or review games 3051that have recently finished. Default: false. 3052@item -icshost or -internetChessServerHost host 3053@cindex icshost, option 3054@cindex internetChessServerHost, option 3055The Internet host name or address of the chess server to connect 3056to when in ICS mode. Default: @code{chessclub.com}. 3057Another popular chess server to try is @code{freechess.org}. 3058If your site doesn't have a working Internet name server, try 3059specifying the host address in numeric form. 3060You may also need 3061to specify the numeric address when using the icshelper option 3062with timestamp or timeseal (see below). 3063@item -icsport or -internetChessServerPort port-number 3064@cindex icsport, option 3065@cindex internetChessServerPort, option 3066The port number to use when connecting to a chess server in ICS 3067mode. Default: 5000. 3068@item -icshelper or -internetChessServerHelper prog-name 3069@cindex icshelper, option 3070@cindex internetChessServerHelper, option 3071An external helper program used to communicate with the chess server. 3072You would set it to "timestamp" for ICC (chessclub.com) or 3073"timeseal" for FICS (freechess.org), after 3074obtaining the correct version of timestamp or timeseal for your 3075computer. See "help timestamp" on ICC and "help timeseal" on FICS. 3076This option is shorthand for @code{-useTelnet -telnetProgram program}. 3077@item -telnet/-xtelnet or -useTelnet true/false 3078@cindex telnet, option 3079@cindex useTelnet, option 3080This option is poorly named; it should be called useHelper. 3081If set to true, it instructs XBoard to run an external 3082program to communicate with the Internet Chess Server. 3083The program to use is given by the telnetProgram option. 3084If the option is 3085false (the default), XBoard opens a TCP socket and uses its own 3086internal implementation of the telnet protocol to communicate with the 3087ICS. @xref{Firewalls}. 3088@item -telnetProgram prog-name 3089@cindex telnetProgram, option 3090This option is poorly named; it should be called helperProgram. 3091It gives the name of the telnet program to be used with 3092the @code{gateway} and @code{useTelnet} options. The default is 3093@file{telnet}. The telnet program is invoked with the value of 3094@code{internetChessServerHost} as its first argument and the value 3095of @code{internetChessServerPort} as its second argument. 3096@xref{Firewalls}. 3097@item -gateway host-name 3098@cindex gateway, option 3099If this option is set to a host name, XBoard communicates with the 3100Internet Chess Server by using @file{rsh} to run 3101the @code{telnetProgram} on the given host, 3102instead of using its own internal implementation 3103of the telnet protocol. You can substitute a different remote shell 3104program for @file{rsh} using the @code{remoteShell} option described below. 3105@xref{Firewalls}. 3106@item -internetChessServerCommPort or -icscomm dev-name 3107@cindex internetChessServerCommPort, option 3108@cindex icscomm, option 3109If this option is set, XBoard communicates with the ICS through 3110the given character I/O device instead of opening a TCP connection. 3111Use this option if your system does not have any kind of 3112Internet connection itself (not even a SLIP or PPP connection), 3113but you do have dial-up access (or a hardwired terminal line) to 3114an Internet service provider from which you can telnet to the ICS. 3115 3116The support for this option in XBoard is minimal. You need to 3117set all communication parameters and tty modes before you enter 3118XBoard. 3119 3120Use a script something like this: 3121 3122@example 3123stty raw -echo 9600 > /dev/tty00 3124xboard -ics -icscomm /dev/tty00 3125@end example 3126 3127Here replace @samp{/dev/tty00} with the name of the device that your 3128modem is connected to. You might have to add several more 3129options to these stty commands. See the man pages for @file{stty} 3130and @code{tty} if you run into problems. Also, on many systems stty 3131works on its standard input instead of standard output, so you 3132have to use @samp{<} instead of @samp{>}. 3133 3134If you are using linux, try starting with the script below. 3135Change it as necessary for your installation. 3136 3137@example 3138#!/bin/sh -f 3139# configure modem and fire up XBoard 3140 3141# configure modem 3142( 3143 stty 2400 ; stty raw ; stty hupcl ; stty -clocal 3144 stty ignbrk ; stty ignpar ; stty ixon ; stty ixoff 3145 stty -iexten ; stty -echo 3146) < /dev/modem 3147xboard -ics -icscomm /dev/modem 3148@end example 3149@noindent 3150After you start XBoard in this way, type whatever commands are 3151necessary to dial out to your Internet provider and log in. 3152Then telnet to ICS, using a command like 3153@kbd{telnet chessclub.com 5000}. 3154Important: See the paragraph below about extra echoes, 3155in @ref{Limitations}. 3156@item -icslogon or -internetChessServerLogonScript file-name 3157@cindex icslogon, option 3158@cindex internetChessServerLogonScript, option 3159@cindex .icsrc 3160Whenever XBoard connects to the Internet Chess Server, 3161if it finds a file with the name given in this option, it feeds the 3162file's contents to the ICS as commands. The default file name 3163is @file{.icsrc}. 3164Usually the first two lines of the file should be 3165your ICS user name and password. 3166The file can be either in $CHESSDIR, in XBoard's working 3167directory if CHESSDIR is not set, or in your home directory. 3168@item -msLoginDelay delay 3169@cindex msLoginDelay, option 3170If you experience trouble logging on to an ICS when using the 3171@code{-icslogon} option, inserting some delay between characters 3172of the logon script may help. This option adds @code{delay} 3173milliseconds of delay between characters. Good values to try 3174are 100 and 250. 3175@item -icsinput/-xicsinput or -internetChessServerInputBox true/false 3176@cindex icsinput, option 3177@cindex internetChessServerInputBox, option 3178Sets the ICS Input Box menu option. @xref{Mode Menu}. Default: false. 3179@item -autocomm/-xautocomm or -autoComment true/false 3180@cindex autocomm, option 3181@cindex autoComment, option 3182Sets the Auto Comment menu option. @xref{Options Menu}. Default: false. 3183@item -autoflag/-xautoflag or -autoCallFlag true/false 3184@cindex autoflag, option 3185@cindex autoCallFlag, option 3186Sets the Auto Flag menu option. @xref{Options Menu}. Default: false. 3187@item -autobs/-xautobs or -autoObserve true/false 3188@cindex autobs, option 3189@cindex autoObserve, option 3190Sets the Auto Observe menu option. @xref{Options Menu}. Default: false. 3191@item -autoKibitz 3192@cindex autoKibitz, option 3193Enables kibitzing of the engines last thinking output (depth, score, time, speed, PV) 3194before it moved 3195to the ICS, in zippy mode. The option @code{showThinking} must be switched on for 3196this option to work. 3197Also diverts similar kibitz information of an opponent engine that is playing you 3198through the ICS to the engine-output window, as if the engine was playing locally. 3199@item -seekGraph true/false or -sg 3200@cindex seekGraph, option 3201@cindex sg, option 3202Enables displaying of the seek graph by left-clicking the board when 3203you are logged on to an ICS and currently idle. 3204The seek graph show all players currently seeking games on the ICS, 3205plotted according to their rating and the time control of the game they seek, 3206in three different colors (for rated, unrated and wild games). 3207Computer ads are displayed as squares, human ads are dots. 3208Default: false. 3209@item -autoRefresh true/false 3210@cindex autoRefresh, option 3211Enables automatic updating of the seek graph, 3212by having the ICS send a running update of all newly placed 3213and removed seek ads. 3214This consumes a substantial amount of communication bandwidth, 3215and is only supported for FICS and ICC. 3216Default: false. 3217@item -backgroundObserve true/false 3218@cindex backgroundObserve, option 3219When true, boards sent to you by the ICS from other games while you are playing 3220(e.g. because you are observing them) 3221will not be automatically displayed. 3222Only a summary of time left and material of both players will appear 3223in the message field above the board. 3224XBoard will remember the last board it has received this way, 3225and will display it instead of the position in your own game 3226when you press the right mouse button. 3227No other information is stored on such games observed in the background; 3228you cannot save such a game later, or step through its moves. 3229This feature is provided solely for the benefit of bughouse players, 3230to enable them to peek at their partner's game without the need 3231to logon twice. 3232Default: false. 3233@item -dualBoard true/false 3234@cindex dualBoard, option 3235In combination with -backgroundObserve true, this option will display 3236the board of the background game side by side with that of your own game, 3237so you can have it in view permanently. 3238Any board or holdings info coming in will be displayed on the secondary 3239board immediately. 3240This feature is still experimental and largely unfinished. 3241There is no animation or highlighting of moves on the secondary board. 3242Default: false. 3243@item -disguisePromotedPieces true/false 3244@cindex disguisePromotedPieces, option 3245When set promoted Pawns in crazyhouse/bughouse are displayed identical 3246to primordial pieces of the same type, rather than distinguishable. 3247Default: true. 3248@item -moves/-xmoves or -getMoveList true/false 3249@cindex moves, option 3250@cindex getMoveList, option 3251Sets the Get Move List menu option. @xref{Options Menu}. Default: true. 3252@item -alarm/-xalarm or -icsAlarm true/false 3253@cindex alarm, option 3254@cindex icsAlarm, option 3255Sets the ICS Alarm menu option. @xref{Options Menu}. Default: true. 3256@item -icsAlarmTime ms 3257@cindex icsAlarmTime, option 3258Sets the time in milliseconds for the ICS Alarm menu option. 3259@xref{Options Menu}. Default: 5000. 3260@item lowTimeWarning true/false 3261@cindex lowTimeWarning, option 3262Controls a color change of the board as a warning your time is running out. 3263@xref{Options Menu}. Default: false. 3264@item -pre/-xpre \fRor\fB -premove true/false 3265@cindex pre, option 3266@cindex premove, option 3267Sets the Premove menu option. @xref{Options Menu}. Default: true. 3268@item -prewhite/-xprewhite or -premoveWhite 3269@itemx -preblack/-xpreblack or -premoveBlack 3270@itemx -premoveWhiteText string 3271@itemx -premoveBlackText string 3272@cindex prewhite, option 3273@cindex premoveWhite, option 3274@cindex preblack, option 3275@cindex premoveBlack, option 3276@cindex premoveWhiteText, option 3277@cindex premoveBlackText, option 3278Set the menu options for specifying the first move for either color. 3279@xref{Options Menu}. Defaults: false and empty strings, so no pre-moves. 3280@item -quiet/-xquiet or -quietPlay true/false 3281@cindex quiet, option 3282@cindex quietPlay, option 3283Sets the Quiet Play menu option. @xref{Options Menu}. Default: false. 3284@item -colorizeMessages or -colorize/-xcolorize 3285@cindex Colors 3286@cindex colorize, option 3287@cindex colorizeMessages, option 3288Setting colorizeMessages 3289to true tells XBoard to colorize the messages received from 3290the ICS. Colorization works only if your xterm 3291supports ISO 6429 escape sequences for changing text colors. 3292Default: true. 3293@item -colorShout foreground,background,bold 3294@itemx -colorSShout foreground,background,bold 3295@itemx -colorCShout foreground,background,bold 3296@itemx -colorChannel1 foreground,background,bold 3297@itemx -colorChannel foreground,background,bold 3298@itemx -colorKibitz foreground,background,bold 3299@itemx -colorTell foreground,background,bold 3300@itemx -colorChallege foreground,background,bold 3301@itemx -colorRequest foreground,background,bold 3302@itemx -colorSeek foreground,background,bold 3303@itemx -colorNormal foreground,background,bold 3304@cindex Colors 3305@cindex colorShout, option 3306@cindex colorSShout, option 3307@cindex colorCShout, option 3308@cindex colorChannel1, option 3309@cindex colorChannel, option 3310@cindex colorKibitz, option 3311@cindex colorTell, option 3312@cindex colorChallenge, option 3313@cindex colorRequest, option 3314@cindex colorSeek, option 3315@cindex colorNormal, option 3316These options set the colors used when colorizing ICS messages. 3317All ICS messages are grouped into one of these categories: 3318shout, sshout, channel 1, other channel, kibitz, tell, challenge, 3319request (including abort, adjourn, draw, pause, and takeback), or 3320normal (all other messages). 3321 3322Each foreground or background argument can be one of the following: 3323black, red, green, yellow, blue, magenta, cyan, white, or default. 3324Here ``default'' means the default foreground or background color of 3325your xterm. Bold can be 1 or 0. If background is omitted, ``default'' 3326is assumed; if bold is omitted, 0 is assumed. 3327 3328@item -soundProgram progname 3329@cindex soundProgram, option 3330@cindex Sounds 3331If this option is set to a sound-playing program that is installed and 3332working on your system, XBoard can play sound files when certain 3333events occur, listed below. The default program name is "play". If 3334any of the sound options is set to "$", the event rings the terminal 3335bell by sending a ^G character to standard output, instead of playing 3336a sound file. If an option is set to the empty string "", no sound is 3337played for that event. 3338@item -soundDirectory directoryname 3339@cindex soundDirectory, option 3340@cindex Sounds 3341This option specifies where XBoard will look for sound files, 3342when these are not given as an absolute path name. 3343@item -soundShout filename 3344@itemx -soundSShout filename 3345@itemx -soundCShout filename 3346@itemx -soundChannel filename 3347@itemx -soundChannel1 filename 3348@itemx -soundKibitz filename 3349@itemx -soundTell filename 3350@itemx -soundChallenge filename 3351@itemx -soundRequest filename 3352@itemx -soundSeek filename 3353@cindex soundShout, option 3354@cindex soundSShout, option 3355@cindex soundCShout, option 3356@cindex soundChannel, option 3357@cindex soundChannel1, option 3358@cindex soundKibitz, option 3359@cindex soundTell, option 3360@cindex soundChallenge, option 3361@cindex soundRequest, option 3362@cindex soundSeek, option 3363These sounds are triggered in the same way as the colorization events 3364described above. They all default to "", no sound. They are played 3365only if the colorizeMessages is on. 3366CShout is synonymous with SShout. 3367@item -soundMove filename 3368@cindex soundMove, option 3369This sound is played when a player other than yourself makes a move. 3370Default: "$". 3371@item -soundRoar filename 3372@cindex soundRoar, option 3373This sound is played when a Lion makes a hit-and-run or double capture/ 3374Default: "" (no sound). 3375@item -soundIcsAlarm filename 3376@cindex soundIcsAlarm, option 3377This sound is used by the ICS Alarm menu option. Default: "$". 3378@item -soundIcsWin filename 3379@cindex soundIcsWin, option 3380This sound is played when you win an ICS game. Default: "" (no sound). 3381@item -soundIcsLoss filename 3382@cindex soundIcsLoss, option 3383This sound is played when you lose an ICS game. Default: "" (no sound). 3384@item -soundIcsDraw filename 3385@cindex soundIcsDraw, option 3386This sound is played when you draw an ICS game. Default: "" (no sound). 3387@item -soundIcsUnfinished filename 3388@cindex soundIcsUnfinished, option 3389This sound is played when an ICS game that you are participating in is 3390aborted, adjourned, or otherwise ends inconclusively. Default: "" (no 3391sound). 3392@end table 3393 3394@node Load and Save options 3395@section Load and Save options 3396@cindex Options, Load and Save 3397@cindex Load and Save options 3398@table @asis 3399@item -lgf or -loadGameFile file 3400@itemx -lgi or -loadGameIndex index 3401@cindex lgf, option 3402@cindex loadGameFile, option 3403@cindex lgi, option 3404@cindex loadGameIndex, option 3405If the @code{loadGameFile} option is set, XBoard loads the specified 3406game file at startup. The file name @file{-} specifies the standard 3407input. If there is more than one game in the file, XBoard 3408pops up a menu of the available games, with entries based on their PGN 3409(Portable Game Notation) tags. 3410If the @code{loadGameIndex} option is set to @samp{N}, the menu is suppressed 3411and the N th game found in the file is loaded immediately. 3412The menu is also suppressed if @code{matchMode} is enabled or if the game file 3413is a pipe; in these cases the first game in the file is loaded immediately. 3414Use the @file{pxboard} shell script provided with XBoard if you 3415want to pipe in files containing multiple games and still see the menu. 3416If the loadGameIndex specifies an index -1, this triggers auto-increment 3417of the index in @code{matchMode}, which means that after every game the 3418index is incremented by one, causing each game of the match to be played 3419from the next game in the file. Similarly, specifying an index value of -2 3420causes the index to be incremented every two games, so that each game 3421in the file is used twice (with reversed colors). 3422The @code{rewindIndex} option causes the index to be reset to the 3423first game of the file when it has reached a specified value. 3424@item -rewindIndex n 3425Causes a position file or game file to be rewound to its beginning after n 3426positions or games in auto-increment @code{matchMode}. 3427See @code{loadPositionIndex} and @code{loadGameIndex}. 3428default: 0 (no rewind). 3429@item -td or -timeDelay seconds 3430@cindex td, option 3431@cindex timeDelay, option 3432Time delay between moves during @samp{Load Game} or @samp{Analyze File}. 3433Fractional seconds are allowed; try @samp{-td 0.4}. 3434A time delay value of -1 tells 3435XBoard not to step through game files automatically. Default: 1 second. 3436@item -sgf or -saveGameFile file 3437@cindex sgf, option 3438@cindex saveGameFile, option 3439If this option is set, XBoard appends a record of every game 3440played to the specified file. The file name @file{-} specifies the 3441standard output. 3442@item -autosave/-xautosave or -autoSaveGames true/false 3443@cindex autosave, option 3444@cindex autoSaveGames, option 3445Sets the Auto Save menu option. @xref{Options Menu}. Default: false. 3446Ignored if @code{saveGameFile} is set. 3447@item -onlyOwnGames true/false 3448@cindex onlyOwnGames, option 3449Suppresses auto-saving of ICS observed games. Default: false. 3450@item -lpf or -loadPositionFile file 3451@itemx -lpi or -loadPositionIndex index 3452@cindex lpf, option 3453@cindex loadPositionFile, option 3454@cindex lpi, option 3455@cindex loadPositionIndex, option 3456If the @code{loadPositionFile} option is set, XBoard loads the 3457specified position file at startup. The file name @file{-} specifies the 3458standard input. If the @code{loadPositionIndex} option is set to N, 3459the Nth position found in the file is loaded; otherwise the 3460first position is loaded. 3461If the loadPositionIndex specifies an index -1, this triggers auto-increment 3462of the index in @code{matchMode}, which means that after every game the 3463index is incremented by one, causing each game of the match to be played 3464from the next position in the file. Similarly, specifying an index value of -2 3465causes the index to be incremented every two games, so that each position 3466in the file is used twice (with the engines playing opposite colors). 3467The @code{rewindIndex} option causes the index to be reset to the 3468first position of the file when it has reached a specified value. 3469@item -spf or -savePositionFile file 3470@cindex spf, option 3471@cindex savePositionFile, option 3472If this option is set, XBoard appends the final position reached 3473in every game played to the specified file. The file name @file{-} 3474specifies the standard output. 3475@item -positionDir directory 3476@cindex positionDir, option 3477Specifies the directory where file browsing should start when using 3478the @samp{Load Position} menu item. 3479@item -pgnExtendedInfo true/false 3480@cindex pgnExtendedInfo, option 3481If this option is set, XBoard saves depth, score and time used for each 3482move that the engine found as a comment in the PGN file. 3483Default: false. 3484@item -pgnTimeLeft true/false 3485@cindex pgnTimeLeft, option 3486If this option is set, XBoard will save the remaining clock time for 3487the player that has just moved as part of the @samp{pgnExtendedInfo}, 3488rather than the time that player thought about his latest move. 3489Default: false. 3490@item -pgnEventHeader string 3491Default: false. 3492@cindex pgnEventHeader, option 3493Sets the name used in the PGN event tag to string. 3494Default: "Computer Chess Game". 3495@item -pgnNumberTag true/false 3496@cindex pgnNumberTag, option 3497Include the (unique) sequence number of a tournament game into the saved 3498PGN file as a 'number' tag. 3499Default: false. 3500@item -saveOutOfBookInfo true/false 3501@cindex saveOutOfBookInfo, option 3502Include the information on how the engine(s) game out of its opening book 3503in a special 'annotator' tag with the PGN file. 3504Default: true. 3505@item -oldsave/-xoldsave or -oldSaveStyle true/false 3506@cindex oldsave, option 3507@cindex oldSaveStyle, option 3508Sets the Old Save Style menu option. @xref{Options Menu}. Default: false. 3509@item -gameListTags string 3510@cindex gameListTags, option 3511The character string lists the PGN tags that should be printed in the 3512Game List, and their order. The meaning of the codes is e=event, 3513s=site, d=date, o=round, p=players, r=result, w=white Elo, b=black Elo, 3514t=time control, v=variant, a=out-of-book info, c=result comment. 3515Default: "eprd" 3516@item -ini or -settingsFile filename 3517@itemx -saveSettingsFile filename 3518@itemx @@filename 3519@cindex saveSettingsFile, option 3520@cindex SettingsFile, option 3521@cindex init, option 3522@cindex at sign, option 3523When XBoard encounters an option -settingsFile (or -ini for short), 3524or @@filename, it tries to read the mentioned file, 3525and substitutes the contents of it (presumaby more command-line options) 3526in place of the option. 3527In the case of -ini or -settingsFile, the name of a successfully read 3528settings file is also remembered as the file to use for saving settings 3529(automatically on exit, or on user command). 3530An option of the form @@filename does not affect saving. 3531The option -saveSettingsFile does specify a name of the file to use 3532for saving, without reading any options from it, and is thus also effective 3533when the file did not exist yet. 3534So the settings will be saved to the file specified in the last 3535-saveSettingsFile or succesfull -settingsFile / -ini command, 3536if any, and in /etc/xboard/xboard.conf otherwise. 3537Usualy the latter is only accessible for the system administrator, though, 3538and will be used to contain system-wide default settings, amongst which 3539a -saveSettingsFile and -settingsFile options to specify a settings file 3540accessible to the individual user, such as ~/.xboardrc in the user's 3541home directory. 3542@item -saveSettingsOnExit true/false 3543@cindex saveSettingsOnExit, option 3544Controls saving of options on the settings file. @xref{Options Menu}. 3545Default: true. 3546@end table 3547 3548@node User interface options 3549@section User interface options 3550@cindex User interface options 3551@cindex Options, User interface 3552@table @asis 3553@item -noGUI 3554@cindex noGUI, option 3555Suppresses all GUI functions of XBoard 3556(to speed up automated ultra-fast engine-engine games, which you don't want to watch). 3557There will be no board or clock updates, no printing of moves, 3558and no update of the icon on the task bar in this mode. 3559@item -logoSize N 3560@cindex logoSize, option 3561This option controls the drawing of player logos next to the clocks. 3562The integer N specifies the width of the logo in pixels; 3563the logo height will always be half the width. 3564When N = 0, no logos will be diplayed. 3565Default: 0. 3566@item -firstLogo imagefile 3567@itemx -secondLogo imagefile 3568@cindex firstLogo, option 3569@cindex secondLogo, option 3570Specify the images to be used as player logos when @code{logoSize} 3571is non-zero, next to the white and black clocks, respectively. 3572@item -autoLogo true/false 3573@itemx -logoDir filename 3574@cindex autoLogo, option 3575@cindex logoDir, option 3576When @code{autoLogo} is set, XBoard will search for a PNG image file 3577with the name of the engine or ICS in the directory specified 3578by @code{logoDir}. 3579For a human player it will look for a file <username>.png in this 3580directory, but only when ~/.logo.png does not provide one. 3581@item -recentEngines number 3582@itemx -recentEngineList list 3583@cindex recentEngines, option 3584@cindex recentEngineList, option 3585When the number is larger than zero, it determines how many recently 3586used engines will be appended at the bottom of the @samp{Engines} menu. 3587The engines will be saved in your settings file as the option 3588@code{recentEngineList}, by their nicknames, 3589and the most recently used one will always be sorted to the top. 3590If the list after that is longer than the specified number, 3591the last one is discarded. 3592Changes in the list will only become visible the next session, 3593provided you saved the settings. 3594Default: 6. 3595@item -oneClickMove true/false 3596@cindex oneClickMove, option 3597When set, this option allows you to enter moves by only clicking the to- 3598or from-square, when only a single legal move to or from that square 3599is possible. 3600Double-clicking a piece (or clicking an already selected piece) 3601will instruct that piece to make the only capture it can legally do. 3602Default: false. 3603@item -monoMouse true/false 3604@cindex monoMouse, option 3605When set button 1 clicks on empty squares in Edit Position mode 3606will be interpreted as button 3 clicks, so they place a piece. 3607Default: false. 3608@item -movesound/-xmovesound or -ringBellAfterMoves true/false 3609@cindex movesound, option 3610@cindex bell, option 3611@cindex ringBellAfterMoves, option 3612Sets the Move Sound menu option. @xref{Options Menu}. Default: false. 3613For compatibility with old XBoard versions, -bell/-xbell are also 3614accepted as abbreviations for this option. 3615@item -analysisBell N 3616@cindex analysisBell, option 3617When N is non-zero, the Move Sound will be played whenever a new 3618PV arrives in analysis mode after more than N seconds of analysis. 3619Default: 0. 3620@item -exit/-xexit or -popupExitMessage true/false 3621@cindex exit, option 3622@cindex popupExitMessage, option 3623Sets the Popup Exit Message menu option. @xref{Options Menu}. Default: true. 3624@item -popup/-xpopup or -popupMoveErrors true/false 3625@cindex popup, option 3626@cindex popupMoveErrors, option 3627Sets the Popup Move Errors menu option. @xref{Options Menu}. Default: false. 3628@item -queen/-xqueen or -alwaysPromoteToQueen true/false 3629@cindex queen, option 3630@cindex alwaysPromoteToQueen, option 3631Sets the Always Queen menu option. @xref{Options Menu}. Default: false. 3632@item -sweepPromotions true/false 3633@cindex sweepPromotion, option 3634Sets the @samp{Almost Always Promote to Queen} menu option. 3635@xref{Options Menu}. Default: false. 3636@item -legal/-xlegal or -testLegality true/false 3637@cindex legal, option 3638@cindex testLegality, option 3639Sets the Test Legality menu option. @xref{Options Menu}. Default: true. 3640@item -size or -boardSize (sizeName | n1,n2,n3,n4,n5,n6,n7) 3641@cindex size, option 3642@cindex boardSize, option 3643@cindex board size 3644Determines how large the board will be, by selecting the pixel size 3645of the pieces and setting a few related parameters. 3646The sizeName can be one of: Titanic, giving 129x129 pixel pieces, 3647Colossal 116x116, Giant 108x108, Huge 95x95, Big 87x87, Large 80x80, Bulky 72x72, 3648Medium 64x64, Moderate 58x58, Average 54x54, Middling 49x49, Mediocre 364945x45, Small 40x40, Slim 37x37, Petite 33x33, Dinky 29x29, Teeny 25x25, 3650or Tiny 21x21. 3651Xboard installs with a set of scalable (svg) piece images, 3652which it scales to any of the requested sizes. 3653The square size can further be continuously scaled by sizing the board window, 3654but this only adapts the size of the pieces, 3655and has no effect on the width of the grid lines or the font choice 3656(both of which would depend on he selected boardSize). 3657The default depends on the size of your screen; it is approximately the 3658largest size that will fit without clipping. 3659 3660You can select other sizes or vary other layout parameters by providing 3661a list of comma-separated values (with no spaces) as the argument. 3662You do not need to provide all the values; for any you omit from the 3663end of the list, defaults are taken from the nearest built-in size. 3664The value @code{n1} gives the piece size, @code{n2} the width of the 3665black border 3666between squares, @code{n3} the desired size for the 3667clockFont, @code{n4} the desired size for the coordFont, 3668@code{n5} the desired size for the messageFont, 3669@code{n6} the smallLayout flag (0 or 1), 3670and @code{n7} the tinyLayout flag (0 or 1). 3671All dimensions are in pixels. 3672If the border between squares is eliminated (0 width), the various 3673highlight options will not work, as there is nowhere to draw the highlight. 3674If smallLayout is 1 and @code{titleInWindow} is true, 3675the window layout is rearranged to make more room for the title. 3676If tinyLayout is 1, the labels on the menu bar are abbreviated 3677to one character each and the buttons in the button bar are made narrower. 3678@item -overrideLineGap n 3679@cindex overrideLineGap, option 3680When n >= 0, this forces the width of the black border between squares 3681to n pixels for any board size. Mostly used to suppress the grid 3682entirely by setting n = 0, e.g. in xiangqi or just getting a prettier 3683picture. When n < 0 this the size-dependent width of the grid lines 3684is used. Default: -1. 3685@item -coords/-xcoords or -showCoords true/false 3686@cindex coords, option 3687@cindex showCoords, option 3688Sets the Show Coords menu option. @xref{Options Menu}. Default: false. 3689The @code{coordFont} option specifies what font to use. 3690@item -autoraise/-xautoraise or -autoRaiseBoard true/false 3691@cindex autoraise, option 3692@cindex autoRaiseBoard, option 3693Sets the Auto Raise Board menu option. @xref{Options Menu}. Default: true. 3694@item -autoflip/-xautoflip or -autoFlipView true/false 3695@cindex autoflip, option 3696@cindex autoFlipView, option 3697Sets the Auto Flip View menu option. @xref{Options Menu}. Default: true. 3698@item -flip/-xflip or -flipView true/false 3699@cindex flip, option 3700@cindex flipView, option 3701If Auto Flip View is not set, or if you are observing but not participating 3702in a game, then the positioning of the board at the start of each game 3703depends on the flipView option. If flipView is false (the default), 3704the board is positioned so that the white pawns move from the bottom to the 3705top; if true, the black pawns move from the bottom to the top. 3706In any case, the Flip menu option (see @ref{Options Menu}) 3707can be used to flip the board after 3708the game starts. 3709@item -title/-xtitle or -titleInWindow true/false 3710@cindex title, option 3711@cindex titleInWindow, option 3712If this option is true, XBoard displays player names (for ICS 3713games) and game file names (for @samp{Load Game}) inside its main 3714window. If the option is false (the default), this information is 3715displayed only in the window banner. You probably won't want to 3716set this option unless the information is not showing up in the 3717banner, as happens with a few X window managers. 3718@item -buttons/-xbuttons or -showButtonBar True/False 3719@cindex buttons, option 3720@cindex showButtonBar, option 3721If this option is False, xboard omits the [<<] [<] [P] [>] [>>] button 3722bar from the window, allowing the message line to be wider. You can 3723still get the functions of these buttons using the menus or their keyboard 3724shortcuts. Default: true. 3725@item -evalZoom factor 3726@cindex evalZoom, option 3727The score interval (-1,1) is blown up on the vertical axis of 3728the Evaluation Graph by the given factor. 3729Default: 1 3730@item -evalThreshold n 3731@cindex evalThreshold, option 3732Score below n (centiPawn) are plotted as 0 in the Evaluation Graph. 3733Default: 25 3734@item -mono/-xmono or -monoMode true/false 3735@cindex mono, option 3736@cindex monoMode, option 3737Determines whether XBoard displays its pieces and squares with 3738two colors (true) or four (false). You shouldn't have to 3739specify @code{monoMode}; XBoard will determine if it is necessary. 3740@item -showTargetSquares true/false 3741@cindex showTargetSquares, option 3742Determines whether XBoard can highlight the squares a piece has 3743legal moves to, when you grab that piece with the mouse. 3744Default: false. 3745@item -flashCount count 3746@itemx -flashRate rate 3747@itemx -flash/-xflash 3748@cindex flashCount, option 3749@cindex flashRate, option 3750@cindex flash, option 3751@cindex xflash, option 3752These options enable flashing of pieces when they 3753land on their destination square. 3754@code{flashCount} 3755tells XBoard how many times to flash a piece after it 3756lands on its destination square. 3757@code{flashRate} 3758controls the rate of flashing (flashes/sec). 3759Abbreviations: 3760@code{flash} 3761sets flashCount to 3. 3762@code{xflash} 3763sets flashCount to 0. 3764Defaults: flashCount=0 (no flashing), flashRate=5. 3765@item -highlight/-xhighlight or -highlightLastMove true/false 3766@cindex highlight, option 3767@cindex highlightLastMove, option 3768Sets the Highlight Last Move menu option. @xref{Options Menu}. Default: false. 3769@item -highlightMoveWithArrow true/false 3770@cindex highlight Arrow, option 3771@cindex highlightMoveWithArrow, option 3772Sets the Highlight with Arrow menu option. @xref{Options Menu}. Default: false. 3773@item -blind/-xblind or -blindfold true/false 3774@cindex blind, option 3775@cindex blindfold, option 3776Sets the Blindfold menu option. @xref{Options Menu}. Default: false. 3777@item -periodic/-xperiodic or -periodicUpdates true/false 3778@cindex periodic, option 3779@cindex periodicUpdates, option 3780Controls updating of current move andnode counts in analysis mode. Default: true. 3781@item -fSAN 3782@itemx -sSAN 3783@cindex fSAN, option 3784@cindex sSAN, option 3785Causes the PV in thinking output of the mentioned engine to be converted 3786to SAN before it is further processed. 3787Warning: this might lose engine output not understood by the parser, 3788and uses a lot of CPU power. 3789Default: the PV is displayed exactly as the engine produced it. 3790@item -showEvalInMoveHistory true/false 3791@cindex showEvalInMoveHistory, option 3792Controls whether the evaluation scores and search depth of engine moves 3793are displayed with the move in the move-history window. 3794Default: true. 3795@item -clockFont font 3796@cindex clockFont, option 3797@cindex Font, clock 3798The font used for the clocks. If the option value is a pattern 3799that does not specify the font size, XBoard tries to choose an 3800appropriate font for the board size being used. 3801Default Xaw: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*. 3802Default GTK: Sans Bold %d. 3803@item -coordFont font 3804@cindex coordFont, option 3805@cindex Font, coordinates 3806The font used for rank and file coordinate labels if @code{showCoords} 3807is true. If the option value is a pattern that does not specify 3808the font size, XBoard tries to choose an appropriate font for 3809the board size being used. 3810Default Xaw: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*. 3811Default GTK: Sans Bold %d. 3812@item -messageFont font 3813@cindex messageFont, option 3814@cindex Font, message 3815The font used for popup dialogs, menus, etc. 3816If the option value is a pattern that does not specify 3817the font size, XBoard tries to choose an appropriate font for 3818the board size being used. 3819Default Xaw: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*. 3820Default GTK: Sans Bold %d 3821@item -tagsFont font 3822@cindex tagsFont, option 3823@cindex Font, tags 3824The font used in the Edit Tags dialog. 3825If the option value contains %d, XBoard will replace it by 3826an appropriate font for the board size being used. 3827(Only used in GTK build.) 3828Default: Sans Normal %d. 3829@item -commentFont font 3830@cindex commentFont, option 3831@cindex Font, comment 3832The font used in the Edit Comment dialog. 3833If the option value contains %d, XBoard will replace it by 3834an appropriate font for the board size being used. 3835(Only used in GTK build.) 3836Default: Sans Normal %d. 3837@item -icsFont font 3838@cindex icsFont, option 3839@cindex Font, ics 3840The font used to display ICS output in the ICS Chat window. 3841As ICS output often contains tables aligned by spaces, 3842a mono-space font is recommended here. 3843If the option value contains %d, XBoard will replace it by 3844an appropriate font for the board size being used. 3845(Only used in GTK build.) 3846Default: Monospace Normal %d. 3847@item -moveHistoryFont font 3848@cindex moveHistoryFont, option 3849@cindex Font, moveHistory 3850The font used in Move History and Engine Output windows. 3851As these windows display mainly moves, 3852one could use a figurine font here. 3853If the option value contains %d, XBoard will replace it by 3854an appropriate font for the board size being used. 3855(Only used in GTK build.) 3856Default: Sans Normal %d. 3857@item -gameListFont font 3858@cindex gameListFont, option 3859@cindex Font, gameList 3860The font used in the listbox of the Game List window. 3861If the option value contains %d, XBoard will replace it by 3862an appropriate font for the board size being used. 3863(Only used in GTK build.) 3864Default: Sans Bold %d. 3865@item -fontSizeTolerance tol 3866@cindex fontSizeTolerance, option 3867In the font selection algorithm, a nonscalable font will be preferred 3868over a scalable font if the nonscalable font's size differs 3869by @code{tol} pixels 3870or less from the desired size. A value of -1 will force 3871a scalable font to always be used if available; a value of 0 will 3872use a nonscalable font only if it is exactly the right size; 3873a large value (say 1000) will force a nonscalable font to always be 3874used if available. Default: 4. 3875@item -pid or -pieceImageDirectory dir 3876@cindex pid, option 3877@cindex pieceImageDirectory, option 3878This options control what piece images xboard uses. 3879XBoard will look in the specified directory for an image in png 3880or svg format for every piece type, with names like BlackQueen.svg, 3881WhiteKnight.svg etc. 3882When neither of these is found (or no valid directory is specified) 3883XBoard will first ty to use an image White/BlackTile.svg in that same 3884directory, and if that is not present either 3885use the svg piece that was installed with it 3886(from the source-tree directory @samp{svg}). 3887Both svg and png images will be scaled by XBoard to the required size, 3888but the png pieces lose much in quality when scaled too much. 3889Default: "". 3890@item -inscriptions utf8string 3891@cindex inscriptions, option 3892The positions in the utf8string correspond to XBoard's piece types, 3893and for each type a glyph can be defined. 3894This glyph will then be rendered on top of the image for the piece. 3895This is useful in combination with the White/BlackTile.svg images, 3896which could be the image of a blank Shogi tile, for writing the 3897kanji piece name on top of it on the fly. 3898Default: "". 3899 3900@item -whitePieceColor color 3901@itemx -blackPieceColor color 3902@itemx -lightSquareColor color 3903@itemx -darkSquareColor color 3904@itemx -highlightSquareColor color 3905@itemx -preoveHighlightColor color 3906@itemx -lowTimeWarningColor color 3907@cindex Colors 3908@cindex whitePieceColor, option 3909@cindex blackPieceColor, option 3910@cindex lightSquareColor, option 3911@cindex darkSquareColor, option 3912@cindex highlightSquareColor, option 3913@cindex premoveHighlightColor, option 3914@cindex lowTimeWarningColor, option 3915Colors to use for the pieces, squares, and square highlights. 3916Defaults: 3917 3918@example 3919-whitePieceColor #FFFFCC 3920-blackPieceColor #202020 3921-lightSquareColor #C8C365 3922-darkSquareColor #77A26D 3923-highlightSquareColor #FFFF00 3924-premoveHighlightColor #FF0000 3925-lowTimeWarningColor #FF0000 3926@end example 3927 3928On a grayscale monitor you might prefer: 3929 3930@example 3931-whitePieceColor gray100 3932-blackPieceColor gray0 3933-lightSquareColor gray80 3934-darkSquareColor gray60 3935-highlightSquareColor gray100 3936-premoveHighlightColor gray70 3937-lowTimeWarningColor gray70 3938@end example 3939 3940The PieceColor options only work properly if the image files 3941defining the pieces were pure black & white 3942(possibly anti-aliased to produce gray scales 3943and semi-transparancy), 3944like the pieces images that come with the install. 3945Their effect on colored pieces is undefined. 3946The SquareColor option only have an effect 3947when no board textures are used. 3948@item -trueColors true/false 3949@cindex trueColors, option 3950When set, this option suppresses the effect of the 3951PieceColor options mentioned above. 3952This is recommended for images that are already colored. 3953@item -useBoardTexture true/false 3954@itemx -liteBackTextureFile filename 3955@itemx -darkBackTextureFile filename 3956@cindex useBoardTexture, option 3957@cindex liteBackTextureFile, option 3958@cindex darkBackTextureFile, option 3959Indicate the png image files to be used for drawing the board squares, 3960and if they should be used rather than using simple colors. 3961The algorithm for cutting squares out of a given bitmap is such that 3962the picture is perfectly reproduced when a bitmap the size of 3963the complete board is given. 3964If the filename ends in "-NxM.png", with integer N and M, 3965it is assumed to contain a bitmap of a complete board of N files 3966and M ranks, and XBoard will scale it to exactly match the 3967current square size. 3968If N=M=0 it scales the entire bitmap to the size of the board, 3969irrespective of the number of files and ranks of the latter. 3970Without any -NxM suffix textures are only blown up by an integer 3971factor when they are smaller than the square size, or, 3972when the name starts with "xq", too small to cover the 3973complete Xiangqi board. 3974Default: false and "" 3975@item -drag/-xdrag or -animateDragging true/false 3976@cindex drag, option 3977@cindex animateDragging, option 3978Sets the Animate Dragging menu option. @xref{Options Menu}. Default: true. 3979@item -animate/-xanimate or -animateMoving true/false 3980@cindex animate, option 3981@cindex animateMoving, option 3982Sets the Animate Moving menu option. @xref{Options Menu}. Default: true. 3983@item -animateSpeed n 3984@cindex -animateSpeed, option 3985Number of milliseconds delay between each animation frame when Animate 3986Moves is on. 3987@item -autoDisplayComment true/false 3988@itemx -autoDisplayTags true/false 3989@cindex -autoDisplayComment, option 3990@cindex -autoDisplayTags, option 3991If set to true, these options cause the window with the move comments, 3992and the window with PGN tags, respectively, to pop up automatically when 3993such tags or comments are encountered during the replaying a stored or 3994loaded game. Default: true. 3995@item -pasteSelection true/false 3996@cindex -pasteSelection, option 3997If this option is set to true, the Paste Position and Paste Game 3998options paste from the currently selected text. If false, they paste 3999from the clipboard. Default: false. 4000@item -autoCopyPV true|false 4001@cindex autoCopyPV, option 4002When this option is set, the position displayed on the board when 4003you terminate a PV walk 4004(initiated by a right-click on board or engine-output window) 4005will be automatically put on the clipboard as FEN. 4006Default: false. 4007@item -dropMenu true|false 4008@cindex dropMenu, option 4009This option allows you to emulate old behavior, 4010where the right mouse button brings up the (now deprecated) drop menu 4011rather than displaying the position at the end of the principal variation. 4012Default: False. 4013@item -pieceMenu true|false 4014@cindex pieceMenu, option 4015This option allows you to emulate old behavior, 4016where the right mouse button brings up the (now deprecated) piece menu 4017in Edit Position mode. 4018From this menu you can select the piece to put on the square you 4019clicked to bring up the menu, 4020or select items such as @kbd{clear board}. 4021You can also @kbd{promote} or @kbd{demote} a clicked piece to convert 4022it into an unorthodox piece that is not directly in the menu, 4023or give the move to @kbd{black} or @kbd{white}. 4024@item -variations true|false 4025@cindex variations, option 4026When this option is on, you can start new variations in Edit Game or 4027Analyze mode by holding the Shift key down while entering a move. 4028When it is off, the Shift key will be ignored. 4029Default: False. 4030@item -appendPV true|false 4031@cindex appendPV, option 4032When this option is on, a button 3 click left of a PV in the Engine 4033Output window will play the first move of that PV in Analyze mode, 4034or as many moves as you walk through it by moving the mouse. 4035Default: False. 4036@item -absoluteAnalysisScores true|false 4037@cindex absoluteAnalysisScores, option 4038When true, scores on the Engine Output window during analysis 4039will be printed from the white point-of-view, rather than the 4040side-to-move point-of-view. 4041Default: False. 4042@item -scoreWhite true|false 4043@cindex scoreWhite, option 4044When true, scores will always be printed from the white point-of-view, 4045rather than the side-to-move point-of-view. 4046Default: False. 4047@item -memoHeaders true|false 4048@cindex memoHeaders, option 4049When true, column headers will be displayed in the Engine Output window 4050for the depth, score, time and nodes data. 4051A button 3 click on these headers will hide or show the corresponding data. 4052(Not intended for dynamic use, as already printed data of the current search 4053will not be affected!) 4054Defaul: False. 4055@end table 4056 4057@node Adjudication Options 4058@section Adjudication Options 4059@cindex Options, adjudication 4060@table @asis 4061@item -adjudicateLossThreshold n 4062@cindex adjudicateLossThreshold, option 4063If the given value is non-zero, XBoard adjudicates the game as a loss 4064if both engines agree for a duration of 6 consecutive ply that the score 4065is below the given score threshold for that engine. Make sure the score 4066is interpreted properly by XBoard, 4067using @code{-firstScoreAbs} and @code{-secondScoreAbs} if needed. 4068Default: 0 (no adjudication) 4069@item -adjudicateDrawMoves n 4070@cindex adjudicateDrawMoves, option 4071If the given value is non-zero, XBoard adjudicates the game as a draw 4072if after the given number of moves it was not yet decided. Default: 0 (no adjudication) 4073@item -checkMates true/false 4074@cindex checkMates, option 4075If this option is set, XBoard detects all checkmates and stalemates, 4076and ends the game as soon as they occur. 4077Legality-testing must be switched on for this option to work. 4078Default: true 4079@item -testClaims true/false 4080@cindex testClaims, option 4081If this option is set, XBoard verifies all result claims made by engines, 4082and those who send false claims will forfeit the game because of it. 4083Legality-testing must be switched on for this option to work. Default: true 4084@item -materialDraws true/false 4085@cindex materialDraws, option 4086If this option is set, XBoard adjudicates games as draws when there is 4087no sufficient material left to inflict a checkmate. 4088This applies to KBKB with like bishops (any number, actually), and to KBK, KNK and KK. 4089Legality-testing must be switched on for this option to work. Default: true 4090@item -trivialDraws true/false 4091@cindex trivialDraws, option 4092If this option is set, XBoard adjudicates games as draws that cannot be 4093usually won without opponent cooperation. This applies to KBKB with unlike bishops, 4094and to KBKN, KNKN, KNNK, KRKR and KQKQ. The draw is called after 6 ply into these end-games, 4095to allow quick mates that can occur in some exceptional positions to be found by the engines. 4096KQKQ does not really belong in this category, and might be taken out in the future. 4097(When bitbase-based adjudications are implemented.) 4098Legality-testing must be on for this option to work. Default: false 4099@item -ruleMoves n 4100@cindex ruleMoves, option 4101If the given value is non-zero, XBoard adjudicates the game as a draw after the given 4102number of consecutive reversible moves. Engine draw claims are always accepted after 50 moves, 4103irrespective of the given value of n. 4104@item -repeatsToDraw n 4105If the given value is non-zero, xboard adjudicates the game as a draw if a position 4106is repeated the given number of times. Engines draw claims are always accepted after 3 repeats, 4107(on the 3rd occurrence, actually), irrespective of the value of n. 4108Beware that positions that have different castling or en-passant rights do not count 4109as repeats, XBoard is fully e.p. and castling aware! 4110@end table 4111 4112@node Install options 4113@section Install options 4114@cindex Options, install 4115@table @asis 4116@item --show-config parameter 4117@cindex show-config, option 4118When called with this option, XBoard will close immediately after printing the 4119value of the indicated configuration parameter, or, when no parameter was given, 4120after printing a list of all such parameters. 4121Currently the only valid values for parameter are Datadir and Sysconfdir. 4122This option can be used by install scripts for board themes 4123to figure out where the currently active XBoard stores its data. 4124@item -date timestamp 4125@itemx -saveDate timestamp 4126@cindex date, option 4127@cindex saveDate, option 4128These options specify an epoch as an integer number. 4129The @code{saveDate} option is written by XBoard in the settings file every time the 4130settings are saved, with the current time, so that later runs of XBoard can know this. 4131The @code{date} option can be included in settings files to indicate when lines 4132following it were added to those files. 4133Some options will be ignored if the epoch specified by the latest @code{date} option 4134predates the -saveDate setting (implying they must have been seen before). 4135@item -autoInstall list 4136@cindex autoInstall, option 4137When the list is set to a non-empty string, XBoard will scan the 4138operating system's plugin directory for engines supporting UCI 4139and XBoard protocol at startup. 4140When it finds an engine that was installed after it last saved 4141its settings, a line to launch that engine (as per specs in 4142the plugin file) is appended to the -firstChessProgramNames 4143list of installed engines. 4144In the future it will be possible to use the autoInstall list to limit 4145this automatic adding of engines based on the chess variant they play. 4146@item -addMasterOption string 4147@cindex addMasterOption, option 4148Adds the mentioned string as an additional line of XBoard's master settings file, 4149after adding a line with a @code{date} option to timestamp it. 4150Intended to add options of the 'install' type (see below) to the master file, 4151which will then be processed by any XBoard that has not seen them since 4152it last saved its settings. 4153@item -autoClose 4154@cindex autoClose, option 4155The presence of this option cause XBoard to close immediately after processing 4156all its options (from settings file and command line). 4157Typically used from install scripts together with options that change XBoard's 4158settings files, so that XBoard can be run in batch mode rather than interactively. 4159@item -installEngine string 4160@cindex installEngine, option 4161Adds the given string as an additional line to the value of the 4162@code{firstChessProgramNames} option when the -saveDate setting preceeds the -date setting. 4163Intended for adding to the master settings file with the aid of -addMasterOption 4164in the install script of engines, as a method for broadcasting the presence 4165of a new engine to all users, 4166which would then see it automatically registered with XBoard. 4167Made obsolete by the advent of the plugin standard (see the @code{autoInstall} option), 4168which broadcasts such presence in a non-XBoard-specific way 4169by dropping *.eng files in a certain system directory. 4170@item -installTheme string 4171@cindex installTheme, option 4172Adds the given string as an additional line to the value of the 4173-themeNames option when the -saveDate setting preceeds the -date setting. 4174Intended for adding to the master settings file with the aid of -addMasterOption 4175in the install script of board graphics themes, 4176as a method for broadcasting the availability of a new theme to all users, 4177who would then see the theme appear automatically in the listbox in the 4178View Board menu dialog next time they run XBoard. 4179@end table 4180 4181@node Other options 4182@section Other options 4183@cindex Options, miscellaneous 4184@table @asis 4185@item -ncp/-xncp or -noChessProgram true/false 4186@cindex ncp, option 4187@cindex noChessProgram, option 4188If this option is true, XBoard acts as a passive chessboard; it 4189does not start a chess engine at all. Turning on this option 4190also turns off clockMode. Default: false. 4191@item -viewer 4192@itemx -viewerOptions string 4193@cindex viewer, option 4194@cindex viewerOptions, option 4195Presence of the volatile option @code{viewer} on the command line 4196will cause the value of the persistent option @code{viewerOptions} 4197as stored in the settings file to be appended to the command line. 4198The @code{view} option will be used by desktop associations with 4199game or position file types, so that @code{viewerOptions} can be 4200used to configure the exact mode XBoard will start in when it 4201should act on such a file (e.g. in -ncp mode, or analyzing 4202with your favorite engine). The options are also automatically 4203appended when Board is invoked with a single argument not being 4204an option name, which is then assumed to be the name of a 4205@code{loadGameFile} or (when the name ends in .fen) a 4206@code{loadPositionFile}. 4207Default: "-ncp -engineOutputUp false -saveSettingsOnExit false". 4208@item -tourneyOptions string 4209@cindex tourneyOptions, option 4210When XBoard is invoked with a single argument that is a file 4211with .trn extension, it will assume this argument to be the value 4212of a @code{tourneyFile} option, 4213and append the value of the persistent option @code{tourneyOptions} 4214as stored in the settings file to the command line. 4215Thus the value of @code{tourneyOptions} can be 4216used to configure XBoard to automatically start running a 4217tournament when it should act on such a file. 4218Default: "-ncp -mm -saveSettingsOnExit false". 4219@item -mode or -initialMode modename 4220@cindex mode, option 4221@cindex initalMode, option 4222If this option is given, XBoard selects the given modename 4223from the Mode menu after starting and (if applicable) processing the 4224loadGameFile or loadPositionFile option. Default: "" (no selection). 4225Other supported values are 4226MachineWhite, MachineBlack, TwoMachines, Analysis, 4227AnalyzeFile, EditGame, EditPosition, and Training. 4228@item -variant varname 4229@cindex variant, option 4230Activates (sometimes partial) support for playing chess variants 4231against a local engine or editing variant games. This flag is not 4232needed in ICS mode. Recognized variant names are: 4233 4234@example 4235normal Normal chess 4236wildcastle Shuffle chess, king can castle from d file 4237nocastle Shuffle chess, no castling allowed 4238fischerandom Fischer Random shuffle chess 4239bughouse Bughouse, ICC/FICS rules 4240crazyhouse Crazyhouse, ICC/FICS rules 4241losers Lose all pieces or get mated (ICC wild 17) 4242suicide Lose all pieces including king (FICS) 4243giveaway Try to have no legal moves (ICC wild 26) 4244twokings Weird ICC wild 9 4245kriegspiel Opponent's pieces are invisible 4246atomic Capturing piece explodes (ICC wild 27) 42473check Win by giving check 3 times (ICC wild 25) 4248shatranj An ancient precursor of chess (ICC wild 28) 4249xiangqi Chinese Chess (on a 9x10 board) 4250shogi Japanese Chess (on a 9x9 board & piece drops) 4251capablanca Capablanca Chess (10x8 board, with Archbishop 4252 and Chancellor pieces) 4253gothic similar, with a better initial position 4254caparandom An FRC-like version of Capablanca Chess (10x8) 4255janus A game with two Archbishops (10x8 board) 4256courier Medieval intermediate between shatranj and 4257 modern Chess (on 12x8 board) 4258falcon Patented 10x8 variant with two Falcon pieces 4259berolina Pawns capture straight ahead, and move diagonally 4260cylinder Pieces wrap around the board edge 4261knightmate King moves as Knight, and vice versa 4262super Superchess (shuffle variant with 4 exo-pieces) 4263makruk Thai Chess (shatranj-like, P promotes on 6th rank) 4264asean ASEAN Chess (a modernized version of Makruk) 4265spartan Spartan Chess (black has unorthodox pieces) 4266great Great Shatranj, a 10x8 variant without sliders 4267grand Grand Chess, on 10x10 with Capablanca pieces 4268lion Mighty-Lion Chess, with a multi-capturing Lion 4269elven Eleven Chess, with Lion and crowned sliders on 10x10 4270chu Chu Shogi, historic 12x12 variant with 2x46 pieces 4271fairy A catchall variant in which all piece types 4272 known to XBoard can participate (8x8) 4273unknown Catchall for other unknown variants 4274@end example 4275 4276In the shuffle variants, XBoard does shuffle the pieces, although 4277you can still do it by hand using Edit Position. Some variants are 4278supported only in ICS mode, including bughouse, and 4279kriegspiel. 4280Berolina and cylinder chess are only partially supported, 4281and can only be played with legality testing off. 4282 4283Apart from these standard variants, engines can define variants 4284of arbitrary names, briefing XBoard transparently on the rules 4285for piece movement, board size and initial setup, 4286so that they work nearly as well as fully-supported standard variants. 4287(But obviously only while using that engine.) 4288The user might have to alter the adjudication settings for some 4289variants, however. E.g. it makes no sense to adjudicate a draw 4290after 50 reversible moves in variants that have a 64-move rule, 4291or no similar rule at all. 4292 4293Default: "normal". Except when the first engine gave an explicit list 4294of variants it supports, and 'normal' is not amongst those. 4295In that case the first variant the engine mentioned it did play will 4296be chosen. 4297@item -boardHeight N 4298@cindex boardHeight, option 4299Allows you to set a non-standard number of board ranks in any variant. 4300If the height is given as -1, the default height for the variant is used. 4301Default: -1 4302@item -boardWidth N 4303@cindex boardWidth, option 4304Allows you to set a non-standard number of board files in any variant. 4305If the width is given as -1, the default width for the variant is used. 4306With a non-standard width, the initial position will always be an empty board, 4307as the usual opening array will not fit. 4308Default: -1 4309@item -holdingsSize N 4310@cindex holdingsSize, option 4311Allows you to set a non-standard size for the holdings in any variant. 4312If the size is given as -1, the default holdings size for the variant is used. 4313The first N piece types will go into the holdings on capture, and you will be 4314able to drop them on the board in stead of making a normal move. If size equals 0, 4315there will be no holdings. 4316Default: -1 4317@item -defaultFrcPosition N 4318@cindex defaultFrcPosition, option 4319Specifies the number of the opening position in shuffle games like Chess960. 4320A value of -1 means the position is randomly generated by XBoard 4321at the beginning of every game. 4322Default: -1 4323@item -pieceToCharTable string 4324@cindex pieceToCharTable, option 4325The characters that are used to represent the piece types XBoard knows in FEN 4326diagrams and SAN moves. 4327You should not have to use this option often: each variant has its own default 4328setting for the piece representation in FEN, which should be sufficient in normal use. 4329The string argument has to specify an even number of pieces 4330(or it will be ignored), as white and black pieces have to be given separately 4331(in that order). The last letter for each color will be the King. 4332The letters before that will be PNBRQ and then a whole host of fairy pieces 4333in an order that has not fully crystallized yet (currently FEACWMOHIJGDVLSU, 4334F=Ferz, Elephant, A=Archbishop, C=Chancellor, W=Wazir, M=Commoner, O=Cannon, 4335H=Nightrider). You should list at least all pieces that occur in the variant 4336you are playing. If you have fewer characters in the string than XBoard has 4337pieces, the pieces not mentioned will get assigned a period, 4338and will not be usable in the variant. 4339You can also explicitly assign pieces a period, in which case they 4340will not be counted in deciding which captured pieces can go into the holdings. 4341A tilde '~' as a piece name does mean this piece is used to represent a promoted 4342Pawn in crazyhouse-like games, i.e. on capture it turns back to a Pawn. 4343A '+' similarly indicates the piece is a shogi-style promoted piece, that should 4344revert to its non-promoted version on capture (rather than to a Pawn). 4345By default the second 11 pieces known to XBoard are the promoted forms of the first 11. 4346A piece specified by the character combination ^ plus letter will be assumed 4347to be the promoted form of the piece indicated by that letter, 4348and get a '+' assigned. 4349To get around the limitation of the alphabet, 4350piece IDs can also be 'dressed letters', i.e. a single letter 4351(upper case for white, lower case for black) 4352followed by a single quote or an exclamation point. 4353Default: "" (meaning the default for the variant is used). 4354@item -pieceNickNames string 4355@cindex pieceNickNames, option 4356The characters in the string are interpreted the same way as in the 4357@code{pieceToCharTable} option. But on input, piece-ID letters are 4358first looked up in the nicknames, and only if not defined there, 4359in the normal pieceToCharTable. This allows you to have two letters 4360designate the same piece, (e.g. N as an alternative to H for Horse 4361in Xiangqi), to make reading of non-compliant notations easier. 4362Default: "" 4363@item -colorNickNames string 4364@cindex colorNickNames, option 4365The side-to-move field in a FEN will be first matched against the letters 4366in the string (first character for white, second for black), 4367before it is matched to the regular 'w' and 'b'. 4368This makes it easier to read non-compliant FENs, 4369which, say, use 'r' for white. 4370Default: "" 4371@item -debug/-xdebug or -debugMode true/false 4372@cindex debug, option 4373@cindex debugMode, option 4374Turns on debugging printout. 4375@item -debugFile filename or -nameOfDebugFile filename 4376@cindex debugFile, option 4377@cindex nameOfDebugFile, option 4378Sets the name of the file to which XBoard saves debug information 4379(including all communication to and from the engines). 4380A @kbd{%d} in the given file name (e.g. game%d.debug) will be replaced 4381by the unique sequence number of a tournament game, 4382so that the debug output of each game will be written on a separate file. 4383@item -engineDebugOutput number 4384@cindex engineDebugOutput, option 4385Specifies how XBoard should handle unsolicited output from the engine, 4386with respect to saving it in the debug file. 4387The output is further (hopefully) ignored. 4388If number=0, XBoard refrains from writing such spurious output to the debug file. 4389If number=1, all engine output is written faithfully to the debug file. 4390If number=2, any protocol-violating line is prefixed with a '#' character, 4391as the engine itself should have done if it wanted to submit info for inclusion in the debug file. 4392This option is provided for the benefit of applications that use the debug file 4393as a source of information, such as the broadcaster of live games TLCV / TLCS. 4394Such applications can be protected from spurious engine output that might otherwise confuse them. 4395@item -rsh or -remoteShell shell-name 4396@cindex rsh, option 4397@cindex remoteShell, option 4398Name of the command used to run programs remotely. The default 4399is @file{rsh} or @file{remsh}, determined when XBoard is 4400configured and compiled. 4401@item -ruser or -remoteUser user-name 4402@cindex ruser, option 4403@cindex remoteUser, option 4404User name on the remote system when running programs with the 4405@code{remoteShell}. The default is your local user name. 4406@item -userName username 4407@cindex userName, option 4408Name under which the Human player will be listed in the PGN file. 4409Default is the login name on your local computer. 4410@item -delayBeforeQuit number 4411@itemx -delayAfterQuit number 4412@cindex delayBeforeQuit, option 4413@cindex delayAfterQuit, option 4414These options order pauses before and after sending the "quit" command to an engine that must be terminated. 4415The pause between quit and the previous command is specified in milliseconds. 4416The pause after quit is used to schedule a kill signal to be sent to the engine process after the 4417number of specified seconds plus one. 4418This signal is a different one as the terminiation signal described in the protocol specs 4419which engines can suppress or ignore, and which is sent directly after the "quit" command. 4420Setting @code{delayAfterQuit} to -1 will suppress sending of the kill signal. 4421Default: 0 4422@item -searchMode n 4423@cindex searchMode, option 4424The integer n encodes the mode for the @samp{find position} function. 4425Default: 1 (= Exact position match) 4426@item -eloThresholdBoth elo 4427@itemx -eloThresholdAny elo 4428@cindex eloThresholdBoth, option 4429@cindex eloThresholdAny, option 4430Defines a lower limit for the Elo rating, which has to be surpassed 4431before a game will be considered when searching for a board position. 4432Default: 0 4433@item -dateThreshold year 4434@cindex dateThreshold, option 4435Only games not played before the given year will be considered when 4436searching for a board position 4437 4438 4439@end table 4440 4441@node Chess Servers 4442@chapter Chess Servers 4443@cindex ICS 4444@cindex ICS, addresses 4445@cindex Internet Chess Server 4446An @dfn{Internet Chess Server}, or @dfn{ICS}, is a place on the 4447Internet where people can get together to play chess, watch other 4448people's games, or just chat. You can use either @code{telnet} or a 4449client program like XBoard to connect to the server. There are 4450thousands of registered users on the different ICS hosts, and it is 4451not unusual to meet 200 on both chessclub.com and freechess.org. 4452 4453Most people can just type @kbd{xboard -ics} to start XBoard as an ICS 4454client. Invoking XBoard in this way connects you to the Internet 4455Chess Club (ICC), a commercial ICS. You can log in there as a guest 4456even if you do not have a paid account. To connect to the largest 4457Free ICS (FICS), use the command @kbd{xboard -ics -icshost freechess.org} 4458instead, or substitute a different host name to connect to your 4459favorite ICS. 4460For a full description of command-line options that control 4461the connection to ICS and change the default values of ICS options, see 4462@ref{ICS options}. 4463 4464While you are running XBoard as an ICS client, 4465you use the terminal window that you started XBoard from 4466as a place to type in commands and read information that is 4467not available on the chessboard. 4468 4469The first time you need to use the terminal is to enter your login name 4470and password, if you are a registered player. (You don't need to do 4471this manually; the @code{icsLogon} option can do it for you. 4472@pxref{ICS options}.) If you are not registered, 4473enter @kbd{g} as your name, and the server will pick a 4474unique guest name for you. 4475 4476Some useful ICS commands 4477include 4478@table @kbd 4479@item help <topic> 4480@cindex help, ICS command 4481to get help on the given <topic>. To get a list of possible topics type 4482@dfn{help} without topic. Try the help command before you ask other 4483people on the server for help. 4484 4485For example @kbd{help register} tells you how to become a registered 4486ICS player. 4487@item who <flags> 4488@cindex who, ICS command 4489to see a list of people who are logged on. Administrators 4490(people you should talk to if you have a problem) are marked 4491with the character @samp{*}, an asterisk. The <flags> allow you to 4492display only selected players: For example, @kbd{who of} shows a 4493list of players who are interested in playing but do not have 4494an opponent. 4495@item games 4496@cindex games, ICS command 4497to see what games are being played 4498@item match <player> [<mins>] [<inc>] 4499to challenge another player to a game. Both opponents get <mins> minutes 4500for the game, and <inc> seconds will be added after each move. 4501If another player challenges you, the server asks if you want to 4502accept the challenge; use the @kbd{accept} or @kbd{decline} commands 4503to answer. 4504@item accept 4505@itemx decline 4506@cindex accept, ICS command 4507@cindex decline, ICS command 4508to accept or decline another player's offer. 4509The offer may be to start a new game, or to agree to a 4510@kbd{draw}, @kbd{adjourn} or @kbd{abort} the current game. @xref{Action Menu}. 4511 4512If you have more than one pending offer (for example, if more than one player 4513is challenging you, or if your opponent offers both a draw and to adjourn the 4514game), you have to supply additional information, by typing something 4515like @kbd{accept <player>}, @kbd{accept draw}, or @kbd{draw}. 4516@item draw 4517@itemx adjourn 4518@itemx abort 4519@cindex draw, ICS command 4520@cindex adjourn, ICS command 4521@cindex abort, ICS command 4522asks your opponent to terminate a game by mutual agreement. Adjourned 4523games can be continued later. 4524Your opponent can either @kbd{decline} your offer or accept it (by typing the 4525same command or typing @kbd{accept}). In some cases these commands work 4526immediately, without asking your opponent to agree. For example, you can 4527abort the game unilaterally if your opponent is out of time, and you can claim 4528a draw by repetition or the 50-move rule if available simply by typing 4529@kbd{draw}. 4530@item finger <player> 4531@cindex finger, ICS command 4532to get information about the given <player>. (Default: yourself.) 4533@item vars 4534@cindex vars, ICS command 4535to get a list of personal settings 4536@item set <var> <value> 4537@cindex set, ICS command 4538to modify these settings 4539@item observe <player> 4540@cindex observe, ICS command 4541to observe an ongoing game of the given <player>. 4542@item examine 4543@itemx oldmoves 4544@cindex examine, ICS command 4545@cindex oldmoves, ICS command 4546to review a recently completed game 4547@end table 4548 4549Some special XBoard features are activated when you are 4550in examine mode on ICS. See the descriptions of the menu commands 4551@samp{Forward}, @samp{Backward}, @samp{Pause}, @samp{ICS Client}, 4552and @samp{Stop Examining} on the @ref{Edit Menu}, @ref{Mode Menu}, and 4553@ref{Action Menu}. 4554 4555@node Firewalls 4556@chapter Firewalls 4557By default, XBoard communicates with an Internet Chess Server 4558by opening a TCP socket directly from the machine it is running on 4559to the ICS. If there is a firewall between your machine and the ICS, 4560this won't work. Here are some recipes for getting around common 4561kinds of firewalls using special options to XBoard. 4562Important: See the paragraph in the below about extra echoes, in 4563@ref{Limitations}. 4564 4565Suppose that you can't telnet directly to ICS, but you can telnet 4566to a firewall host, log in, and then telnet from there to ICS. 4567Let's say the firewall is called @samp{firewall.example.com}. Set 4568command-line options as follows: 4569 4570@example 4571xboard -ics -icshost firewall.example.com -icsport 23 4572@end example 4573@noindent 4574Then when you run XBoard in ICS mode, you will be prompted 4575to log in to the firewall host. This works because port 23 is the 4576standard telnet login service. Do so, then telnet to ICS, using a 4577command like @samp{telnet chessclub.com 5000}, or whatever command 4578the firewall provides for telnetting to port 5000. 4579 4580If your firewall lets you telnet (or rlogin) to remote hosts but 4581doesn't let you telnet to port 5000, you may be able to connect to the 4582chess server on port 23 instead, which is the port the telnet program 4583uses by default. Some chess servers support this (including 4584chessclub.com and freechess.org), while some do not. 4585 4586If your chess server does not allow connections on port 23 and your 4587firewall does not allow you to connect to other ports, you may be able 4588to connect by hopping through another host outside the firewall that 4589you have an account on. For instance, suppose you have a shell 4590account at @samp{foo.edu}. Follow the recipe above, but instead of 4591typing @samp{telnet chessclub.com 5000} to the firewall, type 4592@samp{telnet foo.edu} (or @samp{rlogin foo.edu}), log in there, and 4593then type @samp{telnet chessclub.com 5000}. 4594 4595Suppose that you can't telnet directly to ICS, but you can use rsh 4596to run programs on a firewall host, and that host can telnet to ICS. 4597Let's say the firewall is called @samp{rsh.example.com}. Set 4598command-line options as follows: 4599 4600@example 4601xboard -ics -gateway rsh.example.com -icshost chessclub.com 4602@end example 4603 4604@noindent 4605Then when you run XBoard in ICS mode, it will connect to 4606the ICS by using @file{rsh} to run the command 4607@samp{telnet chessclub.com 5000} on host @samp{rsh.example.com}. 4608 4609Suppose that you can telnet anywhere you want, but you have to 4610run a special program called @file{ptelnet} to do so. 4611 4612First, we'll consider the easy case, in which 4613@samp{ptelnet chessclub.com 5000} gets you to the chess server. 4614In this case set command line options as follows: 4615 4616@example 4617xboard -ics -telnet -telnetProgram ptelnet 4618@end example 4619 4620@noindent 4621Then when you run XBoard in ICS mode, it will issue the 4622command @samp{ptelnet chessclub.com 5000} to connect to the ICS. 4623 4624Next, suppose that @samp{ptelnet chessclub.com 5000} doesn't work; 4625that is, your @file{ptelnet} program doesn't let you connect to 4626alternative ports. As noted above, your chess server may allow you to 4627connect on port 23 instead. In that case, just add the option 4628@samp{-icsport ""} to the above command. 4629But if your chess server doesn't let you connect on port 23, you will have 4630to find some other host outside the firewall and hop through it. For 4631instance, suppose you have a shell account at @samp{foo.edu}. Set 4632command line options as follows: 4633 4634@example 4635xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport "" 4636@end example 4637 4638@noindent 4639Then when you run XBoard in ICS mode, it will issue the 4640command @samp{ptelnet foo.edu} to connect to your account at 4641@samp{foo.edu}. Log in there, then type @samp{telnet chessclub.com 5000}. 4642 4643ICC timestamp and FICS timeseal do not work through some 4644firewalls. You can use them only if your firewall gives a clean TCP 4645connection with a full 8-bit wide path. If your firewall allows you 4646to get out only by running a special telnet program, you can't use 4647timestamp or timeseal across it. But if you have access to a 4648computer just outside your firewall, and you have much lower netlag 4649when talking to that computer than to the ICS, it might be worthwhile 4650running timestamp there. Follow the instructions above for hopping 4651through a host outside the firewall (foo.edu in the example), 4652but run timestamp or timeseal on that host instead of telnet. 4653 4654Suppose that you have a SOCKS firewall that will give you a clean 46558-bit wide TCP connection to the chess server, but only after you 4656authenticate yourself via the SOCKS protocol. In that case, you could 4657make a socksified version of XBoard and run that. If you are using 4658timestamp or timeseal, you will to socksify it, not XBoard; this may 4659be difficult seeing that ICC and FICS do not provide source code for 4660these programs. Socksification is beyond the scope of this document, 4661but see the SOCKS Web site at http://www.socks.permeo.com/. 4662If you are missing SOCKS, try http://www.funbureau.com/. 4663 4664@node Environment 4665@chapter Environment variables 4666@cindex Environment variables 4667@cindex CHESSDIR 4668Game and position files are found in a directory named by the 4669@code{CHESSDIR} environment variable. If this variable is not set, the 4670current working directory is used. If @code{CHESSDIR} is set, 4671XBoard actually changes its working directory to 4672@code{$CHESSDIR}, so any files written by the chess engine 4673will be placed there too. 4674 4675@node Limitations 4676@chapter Limitations and known bugs 4677@cindex Limitations 4678@cindex Bugs 4679There is no way for two people running copies of XBoard to play 4680each other without going through an Internet Chess Server. 4681 4682Under some circumstances, your ICS password may be echoed when you log on. 4683 4684If you are connecting to the ICS by running telnet on an Internet 4685provider or firewall host, you may find that each line you type is 4686echoed back an extra time after you hit @key{Enter}. If your Internet 4687provider is a Unix system, you can probably turn its echo off by 4688typing @kbd{stty -echo} after you log in, and/or typing 4689@key{^E}@key{Enter} (Ctrl+E followed by the Enter key) to the telnet 4690program after you have logged into ICS. It is a good idea to do this 4691if you can, because the extra echo can occasionally confuse XBoard's 4692parsing routines. 4693 4694The game parser recognizes only algebraic notation. 4695 4696Many of the following points used to be limitations in XBoard 4.2.7 and earlier, 4697but are now fixed: 4698The internal move legality tester in XBoard 4.3.xx does look at the game history, 4699and is fully aware of castling or en-passant-capture rights. It permits castling with 4700the king on the d file because this is possible in some "wild 1" games on ICS. 4701The piece-drop menu does not check piece drops in bughouse to see if you actually hold 4702the piece you are trying to drop. But this way of dropping pieces should be considered 4703an obsolete feature, now that pieces can be dropped by dragging them from the holdings 4704to the board. Anyway, if you would attempt an illegal move when using a chess engine or the ICS, 4705XBoard will accept the error message that comes back, undo the move, and let you try another. 4706FEN positions saved by XBoard do include correct information about whether castling or 4707en passant are legal, and also handle the 50-move counter. 4708The mate detector does not understand that non-contact mate is not really mate in bughouse. 4709The only problem this causes while playing is minor: a "#" (mate indicator) character will 4710show up after a non-contact mating move in the move list. XBoard will not assume the game 4711is over at that point, not even when the option Detect Mates is on. 4712Edit Game mode always uses the rules of the selected variant, 4713which can be a variant that uses piece drops. 4714You can load and edit games that contain piece drops. 4715The (obsolete) piece menus are not active, 4716but you can perform piece drops by dragging pieces from the holdings. 4717Fischer Random castling is fully understood. 4718You can enter castlings by dragging the King on top of your Rook. 4719You can probably also play Fischer Random successfully on ICS by typing 4720castling moves into the ICS Interaction window. 4721 4722The menus may not work if your keyboard is in Caps Lock or Num Lock mode. 4723This seems to be a problem with the Athena menu widget, 4724not an XBoard bug. 4725 4726Also see the ToDo file included with the distribution for many other 4727possible bugs, limitations, and ideas for improvement that have been 4728suggested. 4729@node Problems 4730@chapter Reporting problems 4731@cindex Bugs 4732@cindex Bug reports 4733@cindex Reporting bugs 4734@cindex Problems 4735@cindex Reporting problems 4736 4737You can report bugs and problems with XBoard using 4738the bug tracker at @code{https://savannah.gnu.org/projects/xboard/} 4739or by sending mail to @code{<bug-xboard@@gnu.org>}. It can also 4740be useful to report or discuss bugs in the WinBoard Forum at 4741@code{http://www.open-aurec.com/wbforum/}, 4742WinBoard development section. 4743 4744Please use the @file{script} program to start a typescript, run 4745XBoard with the @samp{-debug} option, and include the typescript 4746output in your message. 4747Also tell us what kind of machine and what operating system version 4748you are using. The command @samp{uname -a} will often tell you this. 4749 4750If you improve XBoard, please send a message about your changes, 4751and we will get in touch with you about merging them in 4752to the main line of development. 4753 4754@node Contributors 4755@chapter Authors and contributors 4756@cindex Authors 4757@cindex Contributors 4758 4759Chris Sears and Dan Sears wrote the original XBoard. They were 4760responsible for versions 1.0 through 1.2. The color scheme was taken 4761from Wayne Christopher's @code{XChess} program. 4762 4763Tim Mann was primarily responsible for XBoard versions 1.3 through 47644.2.7, and for WinBoard (a port of XBoard to Microsoft Win32) from its 4765inception through version 4.2.7. 4766 4767John Chanak contributed the initial implementation of ICS mode. Evan 4768Welsh wrote @code{CMail}, and Patrick Surry helped in designing, 4769testing, and documenting it. Elmar Bartel contributed the new piece 4770bitmaps introduced in version 3.2. Jochen Wiedmann converted the 4771documentation to texinfo. Frank McIngvale added click/click moving, 4772the Analysis modes, piece flashing, ZIICS import, and ICS text 4773colorization to XBoard. Hugh Fisher added animated piece movement to 4774XBoard, and Henrik Gram added it to WinBoard. Mark Williams 4775contributed the initial (WinBoard-only) implementation of many new 4776features added to both XBoard and WinBoard in version 4.1.0, including 4777copy/paste, premove, icsAlarm, autoFlipView, training mode, auto 4778raise, and blindfold. Ben Nye contributed X copy/paste code for 4779XBoard. 4780 4781In a fork from version 4.2.7, Alessandro Scotti added many elements to 4782the user interface of WinBoard, including the board textures and 4783font-based rendering, the evaluation-graph, move-history and 4784engine-output window. He was also responsible for adding the UCI 4785support. 4786 4787H. G. Muller continued this fork of the project, producing version 47884.3. He made WinBoard castling- and e.p.-aware, added variant support 4789with adjustable board sizes, the crazyhouse holdings, and the fairy 4790pieces. In addition he added most of the adjudication options, made 4791WinBoard more robust in dealing with buggy and crashing engines, and 4792extended time control with a time-odds and node-count-based modes. 4793Most of the options that initially were WinBoard only have now been 4794back-ported to XBoard. 4795 4796Michel van den Bergh provided the code for reading Polyglot opening books. 4797 4798Meanwhile, some work continued on the GNU XBoard project maintained at 4799savannah.gnu.org, but version 4.2.8 was never released. Daniel 4800Mehrmann was responsible for much of this work. 4801 4802Most recently, Arun Persaud worked with H. G. Muller to merge all 4803the features of the never-released XBoard/WinBoard 4.2.8 of the GNU 4804XBoard project and the never-released 4.3.16 from H. G.'s fork into a 4805unified XBoard/WinBoard 4.4, which is now available both from the 4806savannah.gnu.org web site and the WinBoard forum. 4807 4808@node CMail 4809@chapter CMail 4810@cindex cmail 4811The @file{cmail} program can help you play chess by email with opponents of 4812your choice using XBoard as an interface. 4813 4814You will usually run @file{cmail} without giving any options. 4815 4816@menu 4817* CMail options:: Invoking CMail. 4818* CMail game:: Starting a CMail game. 4819* CMail answer:: Answering a move. 4820* CMail multi:: Multiple games in one message. 4821* CMail completion:: Completing a game. 4822* CMail trouble:: Known CMail problems. 4823@end menu 4824 4825@node CMail options 4826@section CMail options 4827@table @asis 4828@item -h 4829Displays @file{cmail} usage information. 4830@item -c 4831Shows the conditions of the GNU General Public License. 4832@xref{Copying}. 4833@item -w 4834Shows the warranty notice of the GNU General Public License. 4835@xref{Copying}. 4836@item -v 4837@itemx -xv 4838Provides or inhibits verbose output from @file{cmail} and XBoard, 4839useful for debugging. The 4840@code{-xv} 4841form also inhibits the cmail introduction message. 4842@item -mail 4843@itemx -xmail 4844Invokes or inhibits the sending of a mail message containing the move. 4845@item -xboard 4846@itemx -xxboard 4847Invokes or inhibits the running of XBoard on the game file. 4848@item -reuse 4849@itemx -xreuse 4850Invokes or inhibits the reuse of an existing XBoard to display the 4851current game. 4852@item -remail 4853Resends the last mail message for that game. This inhibits running 4854XBoard. 4855@item -game <name> 4856The name of the game to be processed. 4857@item -wgames <number> 4858@itemx -bgames <number> 4859@itemx -games <number> 4860Number of games to start as White, as Black or in total. Default is 1 as 4861white and none as black. If only one color is specified then none of the 4862other color is assumed. If no color is specified then equal numbers of 4863White and Black games are started, with the extra game being as White if an 4864odd number of total games is specified. 4865@item -me <short name> 4866@itemx -opp <short name> 4867A one-word alias for yourself or your opponent. 4868@item -wname <full name> 4869@itemx -bname <full name> 4870@itemx -myname <full name> 4871@itemx -oppname <full name> 4872The full name of White, Black, yourself or your opponent. 4873@item -wna <net address> 4874@itemx -bna <net address> 4875@itemx -na <net address> 4876@itemx -oppna <net address> 4877The email address of White, Black, yourself or your opponent. 4878@item -dir <directory> 4879The directory in which @file{cmail} keeps its files. This defaults to the 4880environment variable @code{$CMAIL_DIR} or failing that, @code{$CHESSDIR}, 4881@file{$HOME/Chess} or @file{~/Chess}. It will be created if it does not exist. 4882@item -arcdir <directory> 4883The directory in which @file{cmail} archives completed games. Defaults to 4884the environment variable @code{$CMAIL_ARCDIR} or, in its absence, the same 4885directory as cmail keeps its working files (above). 4886@item -mailprog <mail program> 4887The program used by cmail to send email messages. This defaults to the 4888environment variable @code{$CMAIL_MAILPROG} or failing that 4889@file{/usr/ucb/Mail}, @file{/usr/ucb/mail} or @file{Mail}. You will need 4890to set this variable if none of the above paths fit your system. 4891@item -logFile <file> 4892A file in which to dump verbose debugging messages that are invoked with 4893the @samp{-v} 4894option. 4895@item -event <event> 4896The PGN Event tag (default @samp{Email correspondence game}). 4897@item -site <site> 4898The PGN Site tag (default @samp{NET}). 4899@item -round <round> 4900The PGN Round tag (default @samp{-}, not applicable). 4901@item -mode <mode> 4902The PGN Mode tag (default @samp{EM}, Electronic Mail). 4903@item Other options 4904Any option flags not listed above are passed through to XBoard. 4905Invoking XBoard through CMail changes the default values of two XBoard 4906options: The default value for @samp{-noChessProgram} is changed to 4907true; that is, by default no chess engine is started. The default 4908value for @samp{-timeDelay} is changed to 0; that is, by default 4909XBoard immediately goes to the end of the game as played so far, 4910rather than stepping through the moves one by one. You can still set 4911these options to whatever values you prefer by supplying them on 4912CMail's command line. @xref{Options}. 4913@end table 4914 4915@node CMail game 4916@section Starting a CMail Game 4917Type @file{cmail} from a shell to start a game as white. After an opening 4918message, you will be prompted for a game name, which is optional---if you 4919simply press @key{Enter}, the game name will take the form 4920@samp{you-VS-opponent}. You will next be prompted for the short name 4921of your opponent. If you haven't played this person before, you will also 4922be prompted for his/her email address. @file{cmail} will then invoke 4923XBoard in the background. Make your first move and select 4924@samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. If all is well, 4925@file{cmail} will mail a copy of the move to your opponent. If you select 4926@samp{Exit} without having selected @samp{Mail Move} then no move will be 4927made. 4928 4929@node CMail answer 4930@section Answering a Move 4931When you receive a message from an opponent containing a move in one of 4932your games, simply pipe the message through @file{cmail}. In some mailers 4933this is as simple as typing @kbd{| cmail} when viewing the message, while in 4934others you may have to save the message to a file and do @kbd{cmail < file} 4935at the command line. In either case @file{cmail} will display the game using 4936XBoard. If you didn't exit XBoard when you made your first move 4937then @file{cmail} will do its best to use the existing XBoard instead 4938of starting a new one. As before, simply make a move and select 4939@samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. @file{cmail} 4940will try to use the 4941XBoard that was most recently used to display the current game. This 4942means that many games can be in progress simultaneously, each with its own 4943active XBoard. 4944 4945If you want to look at the history or explore a variation, go ahead, but 4946you must return to the current position before XBoard will allow you 4947to mail a move. If you edit the game's history you must select 4948@samp{Reload Same Game} from the @samp{File} menu to get back to the original 4949position, then make the move you want and select @samp{Mail Move}. 4950As before, if you decide you aren't ready to make a move just yet you can 4951either select @samp{Exit} without sending a move or just leave 4952XBoard running until you are ready. 4953 4954@node CMail multi 4955@section Multi-Game Messages 4956 4957It is possible to have a @file{cmail} message carry more than one game. 4958This feature was implemented to handle IECG (International Email Chess 4959Group) matches, where a match consists of one game as white and one as black, 4960with moves transmitted simultaneously. In case there are more general uses, 4961@file{cmail} itself places no limit on the number of black/white games 4962contained in a message; however, XBoard does. 4963 4964@node CMail completion 4965@section Completing a Game 4966Because XBoard can detect checkmate and stalemate, @file{cmail} 4967handles game termination sensibly. As well as resignation, the 4968@samp{Action} menu allows draws to be offered and accepted for 4969@file{cmail} games. 4970 4971For multi-game messages, only unfinished and just-finished games will be 4972included in email messages. When all the games are finished, they are 4973archived in the user's archive directory, and similarly in the opponent's 4974when he or she pipes the final message through @file{cmail}. The archive 4975file name includes the date the game was started. 4976 4977@node CMail trouble 4978@section Known CMail Problems 4979It's possible that a strange conjunction of conditions may occasionally 4980mean that @file{cmail} has trouble reactivating an existing 4981XBoard. If this should happen, simply trying it again should work. 4982If not, remove the file that stores the XBoard's PID 4983(@file{game.pid}) or use the @samp{-xreuse} option to force 4984@file{cmail} to start a new XBoard. 4985 4986Versions of @file{cmail} after 2.16 no longer understand the old file format 4987that XBoard used to use and so cannot be used to correspond with 4988anyone using an older version. 4989 4990Versions of @file{cmail} older than 2.11 do not handle multi-game messages, 4991so multi-game correspondence is not possible with opponents using an older 4992version. 4993 4994@node Other programs 4995@chapter Other programs you can use with XBoard 4996@cindex Other programs 4997 4998Here are some other programs you can use with XBoard 4999 5000@menu 5001* GNU Chess:: The GNU Chess engine. 5002* Fairy-Max:: The Fairy-Max chess engine. 5003* HoiChess:: The HoiChess chess engine. 5004* Crafty:: The Crafty chess engine. 5005@end menu 5006 5007@node GNU Chess 5008@section GNU Chess 5009 5010The GNU Chess engine is available from: 5011 5012ftp://ftp.gnu.org/gnu/gnuchess/ 5013 5014You can use XBoard to play a game against GNU Chess, or to 5015interface GNU Chess to an ICS. 5016 5017@node Fairy-Max 5018@section Fairy-Max 5019 5020Fairy-Max is a derivative from the once World's smallest Chess program micro-Max, 5021which measures only about 100 lines of source code. 5022The main difference with micro-Max is that Fairy-Max loads its move-generator 5023tables from a file, so that the rules for piece movement can be easily configured 5024to implement unorthodox pieces. 5025Fairy-Max can therefore play a large number of variants, normal Chess being one of those. 5026In addition it plays Knightmate, Capablanca and Gothic Chess, Shatranj, Courier Chess, 5027Cylinder chess, Berolina Chess, while the user can easily define new variants. 5028It can be obtained from: 5029 5030http://home.hccnet.nl/h.g.muller/dwnldpage.html 5031 5032@node HoiChess 5033@section HoiChess 5034 5035HoiChess is a not-so-very-strong Chess engine, which comes with a derivative HoiXiangqi, 5036able to play Chinese Chess. It can be obtained from the standard Linux repositories 5037through: 5038 5039sudo apt-get install hoichess 5040 5041@node Crafty 5042@section Crafty 5043 5044Crafty is a chess engine written by Bob Hyatt. 5045You can use XBoard to play a game against Crafty, hook Crafty up 5046to an ICS, or use Crafty to interactively analyze games and positions 5047for you. 5048 5049Crafty is a strong, rapidly evolving chess program. This rapid 5050pace of development is good, because it means Crafty is always 5051getting better. This can sometimes cause problems with 5052backwards compatibility, but usually the latest version of Crafty 5053will work well with the latest version of XBoard. 5054Crafty can be obtained from its author's FTP site: 5055ftp://ftp.cis.uab.edu/hyatt/. 5056 5057To use Crafty with XBoard, give the -fcp and -fd options as follows, where 5058<crafty's directory> is the directory in which you installed Crafty 5059and placed its book and other support files. 5060 5061@ifnottex 5062@node Copyright 5063@unnumbered Copyright 5064@include copyright.texi 5065@end ifnottex 5066 5067@node Copying 5068@unnumbered GNU GENERAL PUBLIC LICENSE 5069@include gpl.texinfo 5070 5071@c noman 5072@node Index 5073@unnumbered Index 5074 5075@printindex cp 5076@contents 5077@c end noman 5078 5079@bye 5080