Update info on key bindings in texi file
[xboard.git] / xboard.texi
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
11 INFO-DIR-SECTION Games
12 START-INFO-DIR-ENTRY
13 * xboard: (xboard).         An X Window System graphical chessboard.
14 END-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
30 xboard @- 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
52 XBoard is a graphical chessboard that can serve as a
53 user interface to chess engines (such as GNU Chess), the
54 Internet Chess Servers,
55 electronic mail correspondence chess, or your own collection of saved games.
56
57 This manual documents version @value{VERSION} of XBoard.
58
59 @menu
60 * Major modes::     The main things XBoard can do.
61 * Menus::           Menus, buttons, and keys.
62 * Options::         Command options supported by XBoard.
63 * Chess Servers::   Using XBoard with an Internet Chess Server (ICS).
64 * Firewalls::       Connecting to a chess server through a firewall.
65 * Environment::     Environment variables.
66 * Limitations::     Known limitations and/or bugs.
67 * Problems::        How and where to report any problems you run into.
68 * Contributors::    People who have helped developing XBoard.
69 * CMail::           Using XBoard for electronic correspondence chess.
70 * Other programs::  Other programs you can use with XBoard.
71 @ifnottex
72 * Copyright::       Copyright notice for this manual.
73 @end ifnottex
74 * Copying::         The GNU General Public License.
75
76 * Index::           Index of concepts and symbol names.
77 @end menu
78
79 @node Major modes
80 @chapter Major modes
81 @cindex Major modes
82
83 XBoard always runs in one of four major modes.  You select the
84 major mode from the command line when you start up XBoard.
85
86 @table @asis
87 @item xboard [options]
88 As an interface to GNU Chess or another chess engine running on your
89 machine, XBoard lets you play a game against the machine,
90 set up arbitrary positions, force variations, watch a game between two
91 chess engines, interactively analyze your stored games or set up and
92 analyze arbitrary positions.  (Note: Not all chess engines support
93 analysis.)
94 @item xboard -ics -icshost hostname [options]
95 As Internet Chess Server (ICS) interface, XBoard
96 lets you play against other ICS users, observe games
97 they are playing, or review games that have recently finished.  Most
98 of the ICS "wild" chess variants are supported, including bughouse.
99 @item xboard -ncp [options]
100 XBoard can also be used simply
101 as an electronic chessboard to play through games. It will read and
102 write game files and allow you to play through variations
103 manually. You can use it to browse games off the net or review games
104 you have saved.  These features are also available in the other modes.
105 @item |pxboard
106 If you want to pipe games into XBoard, use the supplied shell
107 script @file{pxboard}.  For example, from the news reader @file{xrn},
108 find a message with one or more games in it, click the Save button,
109 and type @samp{|pxboard} as the file name.
110 @item cmail [options]
111 As an interface to electronic mail correspondence chess, XBoard
112 works with the cmail program. See @ref{CMail} below for
113 instructions.
114 @end table
115
116 @node Menus
117 @chapter Menus, buttons, and keys
118 @cindex Menus
119
120 To move a piece, you can drag it with the left mouse button, or you
121 can click the left mouse button once on the piece, then once more on
122 the destination square.  To drop a new piece on a square (when
123 applicable), press the middle or the right mouse button over the
124 square and select from the pop-up menu.  In cases where you can drop
125 either a white or black piece, use the middle button (or shift+right)
126 for white and the right button (or shift+middle) for black.  When you
127 are playing a bughouse game on an Internet Chess Server, a list of the
128 off-board pieces that each player has available is shown in the window
129 title after the player's name; in addition, the piece menus show the
130 number of pieces available of each type. From version 4.3.14 on, it is
131 also possible in crazyhouse, bughouse or shogi to drag and drop pieces
132 to the board from the holdings squares displayed next to the board.
133 This latter method for dropping pieces during a game is preferred,
134 and the piece-drop menu is now deprecated (except for editing a position).
135 Although the old behavior can still be selected through a command-line
136 option, the default function of the right mouse button is to display
137 the position the chess program thinks it will end up in,
138 while moving the mouse vertically with this button pressed will step
139 through the principal variation to show how this position will be 
140 reached.
141 Lines of play displayed in the engine-output window an similarly
142 be played out on the board, by right-clicking on them.
143
144 When connected to an ICS, it is possible to call up a graphical
145 representation of players seeking a game in stead of the chess board,
146 when the latter is not in use
147 (i.e. when you are not playing or observing).
148 Left-clicking the display area will switch between this 'seek graph'
149 and the chess board.
150 Hovering the mouse pointer over a dot will show the details of the
151 seek ad in the message field above the board.
152 Left-clicking the dot will challenge that player.
153 Right-clicking a dot will 'push it to the back',
154 to reveal any dots that were hidden behind it.
155 Right-clicking off dots will refresh the graph.
156
157 Most other XBoard commands are available from the menu bar. The most
158 frequently used commands also have shortcut keys or on-screen buttons.
159 Some rarely used parameters can only be set through options on the
160 command line used to invoke XBoard.
161
162 XBoard uses a settings file, in which it can remember any changes to
163 the settings that are made through menus or command-line options,
164 so they will still apply when you restart XBoard for another session.
165 The settings can be saved into this file automatically when XBoard exits,
166 or on explicit request of the user.
167 The default name for the settings file is /etc/xboard/xboard.conf,
168 but in a standard install this file is only used as a master settings
169 file that determines the system-wide default settings,
170 and defers reading and writing of user settings to a user-specific
171 file like ~/.xboardrc in the user's home directory.
172
173 When XBoard is iconized, its graphical icon is a white knight if
174 it is White's turn to move, a black knight if it is Black's turn.  See
175 Iconize in @ref{Keys} below if you have problems getting this
176 feature to work.
177
178 @menu
179 * File Menu::       Accessing external games and positions.
180 * Mode Menu::       Selecting XBoard's mode.
181 * Action Menu::     Talking to the chess engine or ICS opponents.
182 * Step Menu::       Controlling the game.
183 * Options Menu::    User preferences.
184 * Help Menu::       Getting help.
185 * Keys::            Other shortcut keys.
186 @end menu
187
188 @node File Menu
189 @section File Menu
190 @cindex File Menu
191 @cindex Menu, File
192 @table @asis
193 @item New Game
194 @cindex New Game, Menu Item
195 Resets XBoard and the chess engine to the beginning of a new chess
196 game. The @kbd{Ctrl-N} key is a keyboard equivalent. In Internet Chess
197 Server mode, clears the current state of XBoard, then
198 resynchronizes with the ICS by sending a refresh command. If you want to
199 stop playing, observing, or examining an ICS game, use an
200 appropriate command from the Action menu, not @samp{New Game}.
201 @xref{Action Menu}.
202 @item New Shuffle Game
203 @cindex New Shuffle Game, Menu Item
204 Similar to @samp{New Game}, but allows you to specify a particular initial position 
205 (according to a standardized numbering system)
206 in chess variants which use randomized opening positions (e.g. Chess960).
207 The selected opening position will persistently be chosen on any following
208 New Game command until you use this menu to select another. Selecting
209 position number -1 will produce a newly randomized position on any new game.
210 Using this menu item in variants that normally do not shuffle their opening position
211 does cause these variants to become shuffle variants until you use the
212 @samp{New Shuffle Game} menu to explicitly switch the randomization off,
213 or select a new variant.
214 @item New Variant
215 @cindex New variant, Menu Item
216 Allows you to select a new chess variant in non-ICS mode. 
217 (In ICS play, the ICS is responsible for deciding which variant will be played,
218 and XBoard adapts automatically.)  The shifted @kbd{Alt+V} key is a 
219 keyboard equivalent. If you play with an engine, the engine must
220 be able to play the selected variant, or the command will be ignored.
221 XBoard supports all major variants, such as xiangqi, shogi, chess, chess960,
222 Capablanca Chess, shatranj, crazyhouse, bughouse.
223 (But not every board size has built-in bitmaps for un-orthodox pieces!)
224 @item Load Game
225 @cindex Load Game, Menu Item
226 Plays a game from a record file. The @kbd{Ctrl-O} key is a keyboard equivalent.
227 A pop-up dialog prompts you for the file name. If the file contains more
228 than one game, a second pop-up dialog
229 displays a list of games (with information drawn from their PGN tags, if
230 any), and you can select the one you want. Alternatively, you can load the
231 Nth game in the file directly, by typing the number @kbd{N} after the
232 file name, separated by a space.
233
234 The game file parser will accept PGN (portable game notation),
235 or in fact almost any file that contains moves in algebraic
236 notation. 
237 Notation of the form @samp{P@@f7}
238 is accepted for piece-drops in bughouse games;
239 this is a nonstandard extension to PGN.
240 If the file includes a PGN position (FEN tag), or an old-style
241 XBoard position diagram bracketed by @samp{[--} and @samp{--]}
242 before the first move, the game starts from that position. Text
243 enclosed in parentheses, square brackets, or curly braces is assumed to
244 be commentary and is displayed in a pop-up window. Any other
245 text in the file is ignored. PGN variations (enclosed in
246 parentheses) also are treated as comments;
247 however, if you rights-click them in the comment window,
248 XBoard will shelve the current line, and load the the selected variation,
249 so you can step through it.
250 You can later revert to the previous line with the @samp{Revert} command.
251 This way you can walk quite complex varation trees with XBoard.
252 (The XBoard PGN parser is currenty limited to three nested levels of variations
253 on top of the main game, however.)
254 The nonstandard PGN tag [Variant "varname"] functions similarly to
255 the -variant command-line option (see below), allowing games in certain chess
256 variants to be loaded.  
257 Note that it must appear before any FEN tag for XBoard to recognize
258 variant FENs appropriately.
259 There is also a heuristic to 
260 recognize chess variants from the Event tag, by looking for the strings
261 that the Internet Chess Servers put there when saving variant ("wild") games.
262 @item Load Next Game
263 @cindex Load Next Game, Menu Item
264 Loads the next game from the last game record file you loaded.
265 The @kbd{Alt+PgDn} key is a keyboard equivalent.
266 @item Load Previous Game
267 @cindex Load Previous Game, Menu Item
268 Loads the previous game from the last game record file you
269 loaded.  The @kbd{Alt+PgUp} key is a keyboard equivalent.
270 Not available if the last game was loaded from a pipe.
271 @item Reload Same Game
272 @cindex Reload Same Game, Menu Item
273 Reloads the last game you loaded.
274 Not available if the last game was loaded from a pipe.
275 @item Save Game
276 @cindex Save Game, Menu Item
277 Appends a record of the current game to a file.
278 The @kbd{Ctrl-S} key is a keyboard equivalent.
279 A pop-up dialog
280 prompts you for the file name. If the game did not begin with
281 the standard starting position, the game file includes the
282 starting position used. Games are saved in the PGN (portable
283 game notation) format, unless the oldSaveStyle option is true,
284 in which case they are saved in an older format that is specific
285 to XBoard. Both formats are human-readable, and both can be
286 read back by the @samp{Load Game} command.
287 Notation of the form @samp{P@@f7}
288 is accepted for piece-drops in bughouse games;
289 this is a nonstandard extension to PGN.
290 @item Copy Game
291 @cindex Copy Game, Menu Item
292 Copies a record of the current game to an internal clipboard in PGN
293 format and sets the X selection to the game text. The @kbd{Ctrl-C} 
294 key is a keyboard equivalent. The game can be
295 pasted to another application (such as a text editor or another copy
296 of XBoard) using that application's paste command.  In many X
297 applications, such as xterm and emacs, the middle mouse button can be
298 used for pasting; in XBoard, you must use the Paste Game command.
299 @item Paste Game
300 @cindex Paste Game, Menu Item
301 Interprets the current X selection as a game record and loads it, as
302 with Load Game. The @kbd{Ctrl-V} key is a keyboard equivalent.
303 @item Load Position
304 @cindex Load Position, Menu Item
305 Sets up a position from a position file.  A pop-up dialog prompts
306 you for the file name.  The shifted @kbd{Ctrl-O} key is a keyboard 
307 equivalent. If the file contains more than one saved
308 position, and you want to load the Nth one, type the number N
309 after the file name, separated by a space. Position files must
310 be in FEN (Forsythe-Edwards notation), or in the format that the
311 Save Position command writes when oldSaveStyle is turned on.
312 @item Load Next Position
313 @cindex Load Next Position, Menu Item
314 Loads the next position from the last position file you loaded.
315 The shifted @kbd{Alt+PgDn} key is a keyboard equivalent.
316 @item Load Previous Position
317 @cindex Load Previous Position, Menu Item
318 Loads the previous position from the last position file you
319 loaded. The shifted @kbd{Alt+PgUp} key is a keyboard equivalent.
320 Not available if the last position was loaded from a pipe.
321 @item Reload Same Position
322 @cindex Reload Same Position, Menu Item
323 Reloads the last position you loaded.
324 Not available if the last position was loaded from a pipe.
325 @item Save Position
326 @cindex Save Game, Menu Item
327 Appends a diagram of the current position to a file.
328 The shifted @kbd{Ctrl+S} key is a keyboard equivalent. 
329 A pop-up dialog prompts you for the file name. Positions are saved in
330 FEN (Forsythe-Edwards notation) format unless the @code{oldSaveStyle}
331 option is true, in which case they are saved in an older,
332 human-readable format that is specific to XBoard. Both formats
333 can be read back by the @samp{Load Position} command.
334 @item Copy Position
335 @cindex Copy Position, Menu Item
336 Copies the current position to an internal clipboard in FEN format and
337 sets the X selection to the position text. The shifted @kbd{Ctrl-C} key 
338 is a keyboard equivalent.  The position can be pasted
339 to another application (such as a text editor or another copy of
340 XBoard) using that application's paste command.  In many X
341 applications, such as xterm and emacs, the middle mouse button can be
342 used for pasting; in XBoard, you must use the Paste Position command.
343 @item Paste Position
344 @cindex Paste Position, Menu Item
345 Interprets the current X selection as a FEN position and loads it, as
346 with Load Position. The shifted @kbd{Ctrl-V} key is a keyboard equivalent.
347 @item Mail Move
348 @itemx Reload CMail Message
349 @cindex Mail Move, Menu Item
350 @cindex Reload CMail Message, Menu Item
351 See @ref{CMail}.
352 @item Exit
353 @cindex Exit, Menu Item
354 Exits from XBoard. The @kbd{Ctrl-Q} key is a keyboard equivalent.
355 @end table
356
357 @node Mode Menu
358 @section Mode Menu
359 @cindex Menu, Mode
360 @cindex Mode Menu
361 @table @asis
362 @item Machine White
363 @cindex Machine White, Menu Item
364 Tells the chess engine to play White. 
365 The @kbd{Ctrl-W} key is a keyboard equivalent.
366 @item Machine Black
367 @cindex Machine Black, Menu Item
368 Tells the chess engine to play Black.
369 The @kbd{Ctrl-B} key is a keyboard equivalent.
370 @item Two Machines
371 @cindex Two Machines, Menu Item
372 Plays a game between two chess engines.
373 The @kbd{Ctrl-T} key is a keyboard equivalent.
374 @item Analysis Mode
375 @cindex Analysis Mode, Menu Item
376 XBoard tells the chess engine to start analyzing the current game/position
377 and shows you the analysis as you move pieces around.
378 The @kbd{Ctrl-A} key is a keyboard equivalent.
379 Note: Some chess engines do not support Analysis mode.
380
381 To set up a position to analyze, you do the following:
382
383 1. Select Edit Position from the Mode Menu
384
385 2. Set up the position.  Use the middle and right buttons to
386 bring up the white and black piece menus.
387
388 3. When you are finished, click on either the Black or White
389 clock to tell XBoard which side moves first.
390
391 4. Select Analysis Mode from the Mode Menu to start the analysis.
392
393 The analysis function can also be used when observing games on an ICS
394 with an engine loaded (zippy mode); the engine then will analyse
395 the positions as they occur in the observed game.
396 @item Analyze File
397 @cindex Analyze File, Menu Item
398 This option lets you load a game from a file (PGN, XBoard format, etc.)
399 and analyze it. The @kbd{Ctrl-F} key is a keyboard equivalent.
400 When you select this menu item, a pop-up window appears
401 and asks for a file name to load.
402 If the file contains multiple games, another pop up appears that lets
403 you select which game you wish to analyze.
404 After a game is loaded, use the XBoard arrow buttons to step
405 forwards/backwards through the game and watch the analysis.
406 Note: Some chess engines do not support Analysis mode.
407 @item ICS Client
408 @cindex ICS Client, Menu Item
409 This is the normal mode when XBoard
410 is connected to a chess server.  If you have moved into
411 Edit Game or Edit Position mode, you can select this option to get out.
412
413 To use xboard in ICS mode, run it in the foreground with the -ics
414 option, and use the terminal you started it from to type commands and
415 receive text responses from the chess server.  See
416 @ref{Chess Servers} below for more information.
417
418 XBoard activates some special position/game editing features when you
419 use the @kbd{examine} or @kbd{bsetup} commands on ICS and you have
420 @samp{ICS Client} selected on the Mode menu.  First, you can issue the
421 ICS position-editing commands with the mouse.  Move pieces by dragging
422 with mouse button 1.  To drop a new piece on a square, press mouse
423 button 2 or 3 over the square.  This brings up a menu of white pieces
424 (button 2) or black pieces (button 3).  Additional menu choices let
425 you empty the square or clear the board.  Click on the White or Black
426 clock to set the side to play.  You cannot set the side to play or
427 drag pieces to arbitrary squares while examining on ICC, but you can
428 do so in @kbd{bsetup} mode on FICS.  In addition, the menu commands
429 @samp{Forward}, @samp{Backward}, @samp{Pause}, and @samp{Stop Examining}
430 have special functions in this mode; see below.
431 @item Edit Game
432 @cindex Edit Game, Menu Item
433 Allows you to make moves for both Black and White, and to change
434 moves after backing up with the @samp{Backward} command. The clocks do
435 not run. The @kbd{Ctrl-E} key is a keyboard equivalent.
436
437 In chess engine mode, the chess engine continues to check moves for legality
438 but does not participate in the game. You can bring the chess engine
439 into the game by selecting @samp{Machine White}, @samp{Machine Black},
440 or @samp{Two Machines}.
441
442 In ICS mode, the moves are not sent to the ICS: @samp{Edit Game} takes
443 XBoard out of ICS Client mode and lets you edit games locally.
444 If you want to edit games on ICS in a way that other ICS users
445 can see, use the ICS @kbd{examine} command or start an ICS match
446 against yourself.
447 @item Edit Position
448 @cindex Edit Position, Menu Item
449 Lets you set up an arbitrary board position.
450 The shifted @kbd{Ctrl-E} key is a keyboard equivalent.
451 Use mouse button 1 to drag pieces to new squares, or to delete a piece
452 by dragging it off the board or dragging an empty square on top of it.
453 To drop a new piece on a square, press mouse button 2 or 3 over the
454 square. This brings up a menu of white pieces (button 2) or
455 black pieces (button 3). Additional menu choices let you empty the
456 square or clear the board. You can set the side to play next by
457 clicking on the word White or Black at the top of the screen.
458 Selecting @samp{Edit Position} causes XBoard to discard
459 all remembered moves in the current game.
460
461 In ICS mode, changes made to the position by @samp{Edit Position} are
462 not sent to the ICS: @samp{Edit Position} takes XBoard out of
463 @samp{ICS Client} mode and lets you edit positions locally. If you want to
464 edit positions on ICS in a way that other ICS users can see, use
465 the ICS @kbd{examine} command, or start an ICS match against yourself.
466 (See also the ICS Client topic above.)
467 @item Training
468 @cindex Training, Menu Item
469 Training mode lets you interactively guess the moves of a game for one
470 of the players. You guess the next move of the game by playing the
471 move on the board. If the move played matches the next move of the
472 game, the move is accepted and the opponent's response is auto-played.
473 If the move played is incorrect, an error message is displayed.  You
474 can select this mode only while loading a game (that is, after
475 selecting @samp{Load Game} from the File menu).  While XBoard is in 
476 @samp{Training} mode, the navigation buttons are disabled.
477 @item Show Engine Output
478 @cindex Show Engine Output, Menu Item
479 Shows or hides a window in which the thinking output of any loaded engines
480 is displayed. The shifted @kbd{Alt+O} key is a keyboard equivalent.
481 XBoard will display lines of thinking output of the same depth ordered by score, 
482 (highest score on top), rather than in the order the engine produced them. 
483 Usually this amounts to the same, as a normal engine search will only find new PV 
484 (and emit it as thinking output) 
485 when it searches a move with a higher score than the previous variation. 
486 But when the engine is in multi-variation mode this needs not always be true, 
487 and it is more convenient for someone analyzing games to see the moves sorted by score. 
488 The order in which the engine found them is only of interest to the engine author, 
489 and can still be deduced from the time or node count printed with the line.
490 @item Show Evaluation Graph
491 @cindex Show Evaluation Graph, Menu Item
492 Shows or hides a window which displays a graph of how the engine score(s)
493 evolved as a function of the move number. 
494 The shifted @kbd{Alt+G} key is a keyboard equivalent.
495 Clicking on the graph will bring
496 the corresponding position in the board display.
497 @item Show Game List
498 @cindex Show Game List, Menu Item
499 Shows or hides the list of games generated by the last @samp{Load Game}
500 command. The shifted @kbd{Alt+L} key is a keyboard equivalent.
501 @item Show Move History
502 @cindex Show Move History, Menu Item
503 Shows or hides a list of moves of the current game.
504 The shifted @kbd{Alt+H} key is a keyboard equivalent.
505 This list allows you to move the display to any earlier position in the game
506 by clicking on the corresponding move.
507 @item Edit Tags
508 @cindex Edit Tags, Menu Item
509 Lets you edit the PGN (portable game notation)
510 tags for the current game. After editing, the tags must still conform to
511 the PGN tag syntax:
512
513 @example
514 <tag-section> ::= <tag-pair> <tag-section>
515                         <empty>
516 <tag-pair> ::= [ <tag-name> <tag-value> ]
517 <tag-name> ::= <identifier>
518 <tag-value> ::= <string>
519 @end example
520 @noindent
521 See the PGN Standard for full details. Here is an example:
522
523 @example
524 [Event "Portoroz Interzonal"]
525 [Site "Portoroz, Yugoslavia"]
526 [Date "1958.08.16"]
527 [Round "8"]
528 [White "Robert J. Fischer"]
529 [Black "Bent Larsen"]
530 [Result "1-0"]
531 @end example
532 @noindent
533 Any characters that do not match this syntax are silently ignored. Note that
534 the PGN standard requires all games to have at least the seven tags shown
535 above. Any that you omit will be filled in by XBoard
536 with @samp{?} (unknown value), or @samp{-} (inapplicable value).
537 @item Edit Comment
538 @cindex Edit Comment, Menu Item
539 Adds or modifies a comment on the current position. Comments are
540 saved by @samp{Save Game} and are displayed by @samp{Load Game},
541 @samp{Forward}, and @samp{Backward}.
542 @item ICS Input Box
543 @cindex ICS Input Box, Menu Item
544 If this option is set in ICS mode,
545 XBoard
546 creates an extra window that you can use for typing in ICS commands.
547 The input box is especially useful if you want to type in something long or do
548 some editing on your input, because output from ICS doesn't get mixed
549 in with your typing as it would in the main terminal window.
550 @item Pause
551 @cindex Pause, Menu Item
552 Pauses updates to the board, and if you are playing against a chess engine,
553 also pauses your clock. To continue, select @samp{Pause} again, and the
554 display will automatically update to the latest position.
555 The @samp{P} button and keyboard @kbd{Pause} key are equivalents.
556
557 If you select Pause when you are playing against a chess engine and
558 it is not your move, the chess engine's clock
559 will continue to run and it will eventually make a move, at which point
560 both clocks will stop. Since board updates are paused, however,
561 you will not see the move until you exit from Pause mode (or select Forward).
562 This behavior is meant to simulate adjournment with a sealed move.
563
564 If you select Pause while you are observing or examining a game on a
565 chess server, you can step backward and forward in the current history
566 of the examined game without affecting the other observers and
567 examiners, and without having your display jump forward to the latest
568 position each time a move is made. Select Pause again to reconnect
569 yourself to the current state of the game on ICS.
570
571 If you select @samp{Pause} while you are loading a game, the game stops
572 loading. You can load more moves manually by selecting @samp{Forward}, or
573 resume automatic loading by selecting @samp{Pause} again.
574 @end table
575
576 @node Action Menu
577 @section Action Menu
578 @cindex Menu, Action
579 @cindex Action, Menu
580 @table @asis
581 @item Accept
582 @cindex Accept, Menu Item
583 Accepts a pending match offer. 
584 The @kbd{F3} key is a keyboard equivalent.
585 If there is more than one offer
586 pending, you will have to type in a more specific command
587 instead of using this menu choice.
588 @item Decline
589 @cindex Decline, Menu Item
590 Declines a pending offer (match, draw, adjourn, etc.).
591 The @kbd{F4} key is a keyboard equivalent. If there
592 is more than one offer pending, you will have to type in a more
593 specific command instead of using this menu choice.
594 @item Call Flag
595 @cindex Call Flag, Menu Item
596 Calls your opponent's flag, claiming a win on time, or claiming
597 a draw if you are both out of time. 
598 The @kbd{F5} key is a keyboard equivalent.
599 You can also call your
600 opponent's flag by clicking on his clock.
601 @item Draw
602 @cindex Draw, Menu Item
603 Offers a draw to your opponent, accepts a pending draw offer
604 from your opponent, or claims a draw by repetition or the 50-move
605 rule, as appropriate. The @kbd{F6} key is a keyboard equivalent.
606 @item Adjourn
607 @cindex Adjourn, Menu Item
608 Asks your opponent to agree to adjourning the current game, or
609 agrees to a pending adjournment offer from your opponent.
610 The @kbd{F7} key is a keyboard equivalent.
611 @item Abort
612 @cindex Abort, Menu Item
613 Asks your opponent to agree to aborting the current game, or
614 agrees to a pending abort offer from your opponent.
615 The @kbd{F8} key is a keyboard equivalent. An aborted
616 game ends immediately without affecting either player's rating.
617 @item Resign
618 @cindex Resign, Menu Item
619 Resigns the game to your opponent. The @kbd{F9} key is a
620 keyboard equivalent.
621 @item Stop Observing
622 @cindex Stop Observing, Menu Item
623 Ends your participation in observing a game, by issuing the ICS
624 observe command with no arguments. ICS mode only.
625 The @kbd{F10} key is a keyboard equivalent.
626 @item Stop Examining
627 @cindex Stop Examining, Menu Item
628 Ends your participation in examining a game, by issuing the ICS
629 unexamine command. ICS mode only.
630 The @kbd{F11} key is a keyboard equivalent.
631 @item Upload to Examine
632 @cindex Upload to Examine, Menu Item
633 Create an examined game of the proper variant on the ICS,
634 and send the game there that is currenty loaded in XBoard
635 (e.g. through pasting or loading from file).
636 You must be connected to an ICS for this to work.
637 @item Adjudicate to White
638 @itemx Adjudicate to Black
639 @itemx Adjudicate Draw
640 @cindex Adjudicate to White, Menu Item
641 @cindex Adjudicate to Black, Menu Item
642 @cindex Adjudicate Draw, Menu Item
643 Terminate an ongoing game in Two-Machines mode (including match mode),
644 with as result a win for white, for black, or a draw, respectively.
645 The PGN file of the game will accompany the result string
646 by the comment "user adjudication".
647 @end table
648
649 @node Step Menu
650 @section Step Menu
651 @cindex Step Menu
652 @cindex Menu, Step
653 @table @asis
654 @item Backward
655 @cindex Backward, Menu Item
656 @cindex <, Button
657 Steps backward through a series of remembered moves.
658 The @samp{[<]} button and the @kbd{Alt+LeftArrow} key are equivalents,
659 as is turning the mouse wheel towards you.
660 In addition, pressing the Control key steps back one move, and releasing
661 it steps forward again.
662
663 In most modes, @samp{Backward} only lets you look back at old positions;
664 it does not retract moves. This is the case if you are playing against
665 a chess engine, playing or observing a game on an ICS, or loading a game.
666 If you select @samp{Backward} in any of these situations, you will not
667 be allowed to make a different move. Use @samp{Retract Move} or
668 @samp{Edit Game} if you want to change past moves.
669
670 If you are examining an ICS game, the behavior of @samp{Backward}
671 depends on whether XBoard is in Pause mode. If Pause mode is
672 off, @samp{Backward} issues the ICS backward command, which backs up
673 everyone's view of the game and allows you to make a different
674 move. If Pause mode is on, @samp{Backward} only backs up your local
675 view.
676 @item Forward
677 @cindex Forward, Menu Item
678 @cindex >, Button
679 Steps forward through a series of remembered moves (undoing the
680 effect of @samp{Backward}) or forward through a game file. The
681 @samp{[>]} button and the @kbd{Alt+RightArrow} key are equivalents,
682 as is turning the mouse wheel away from you.
683
684 If you are examining an ICS game, the behavior of Forward
685 depends on whether XBoard is in Pause mode. If Pause mode is
686 off, @samp{Forward} issues the ICS forward command, which moves
687 everyone's view of the game forward along the current line. If
688 Pause mode is on, @samp{Forward} only moves your local view forward,
689 and it will not go past the position that the game was in when
690 you paused.
691 @item Back to Start
692 @cindex Back to Start, Menu Item
693 @cindex <<, Button
694 Jumps backward to the first remembered position in the game.
695 The @samp{[<<]} button and the @kbd{Alt+Home} key are equivalents.
696
697 In most modes, Back to Start only lets you look back at old
698 positions; it does not retract moves. This is the case if you
699 are playing against a local chess engine, playing or observing a game on
700 a chess server, or loading a game. If you select @samp{Back to Start} in any
701 of these situations, you will not be allowed to make different
702 moves. Use @samp{Retract Move} or @samp{Edit Game} if you want to change past
703 moves; or use Reset to start a new game.
704
705 If you are examining an ICS game, the behavior of @samp{Back to
706 Start} depends on whether XBoard is in Pause mode. If Pause mode
707 is off, @samp{Back to Start} issues the ICS @samp{backward 999999}
708 command, which backs up everyone's view of the game to the start and
709 allows you to make different moves. If Pause mode is on, @samp{Back
710 to Start} only backs up your local view.
711 @item Forward to End
712 @cindex Forward to End, Menu Item
713 @cindex >>, Button
714 Jumps forward to the last remembered position in the game. The
715 @samp{[>>]} button and the @kbd{Alt+End} key are equivalents.
716
717 If you are examining an ICS game, the behavior of @samp{Forward to
718 End} depends on whether XBoard is in Pause mode. If Pause mode
719 is off, @samp{Forward to End} issues the ICS @samp{forward 999999}
720 command, which moves everyone's view of the game forward to the end of
721 the current line. If Pause mode is on, @samp{Forward to End} only moves
722 your local view forward, and it will not go past the position
723 that the game was in when you paused.
724 @item Revert
725 @itemx Annotate
726 @cindex Revert, Menu Item
727 @cindex Annotate, Menu Item
728 If you are examining an ICS game and Pause mode is off, issues
729 the ICS command @samp{revert}.
730 In local mode, when you were editing or analyzing a game, 
731 and have been entering a number of moves by hand, starting from 
732 a position not at the end of the game, 
733 the revert command restores the game to the variation you started from. 
734 This can be applied recursively, 
735 so that you can analyze variations on variations; 
736 each time you create a new variation by entering an alternative move, 
737 the current variation will be shelved. 
738 Revert allows you to return to the most recently shelved variation.
739 The difference between Revert and Annotate is that with the latter,
740 the variation you had been entering and are now abandoning
741 is currently added as a comment 
742 (in PGN variation syntax, i.e. between parentheses)
743 to the original move where you deviated.
744 Note that such 'variation comments' can be played out on the board again
745 (also when they were loaded from file)
746 by clicking them in the comment window.
747 The @kbd{Home} key is a keyboard equivalent.
748 @item Truncate Game
749 @cindex Truncate Game, Menu Item
750 Discards all remembered moves of the game beyond the current
751 position. Puts XBoard into @samp{Edit Game} mode if it was not there
752 already.
753 The @kbd{End} key is a keyboard equivalent.
754 @item Move Now
755 @cindex Move Now, Menu Item
756 Forces the chess engine to move immediately. Chess engine mode only.
757 The @kbd{Ctrl-M} key is a keyboard equivalent.
758 @item Retract Move
759 @cindex Retract Move, Menu Item
760 Retracts your last move. In chess engine mode, you can do this only
761 after the chess engine has replied to your move; if the chess engine is still
762 thinking, use @samp{Move Now} first. In ICS mode, @samp{Retract Move}
763 issues the command @samp{takeback 1} or @samp{takeback 2}
764 depending on whether it is your opponent's move or yours.
765 The @kbd{Ctrl-X} key is a keyboard equivalent.
766 @end table
767
768 @node Options Menu
769 @section Options Menu
770 @cindex Menu, Options
771 @cindex Options Menu
772 @table @asis
773 @item Flip View
774 @cindex Flip View, Menu Item
775 Inverts your view of the chess board for the duration of the
776 current game. Starting a new game returns the board to normal.
777 The @kbd{F2} key is a keyboard equivalent.
778 @item Adjudications
779 @cindex Adjudications, Menu Item
780 Pops up a sub-menu where you can enable or disable various adjudications
781 that XBoard can perform in engine-engine games.
782 The shifted @kbd{Alt+J} key is a keyboard equivalent.
783 You can instruct XBoard to detect and terminate the game on checkmate
784 or stalemate, even if the engines would not do so, to verify engine
785 result claims (forfeiting engines that make false claims), rather than
786 naively following the engine, to declare draw on positions
787 which can never be won for lack of mating material, (e.g. KBK),
788 or which are impossible to win unless the opponent seeks its own demise 
789 (e.g. KBKN).
790 For these adjudications to work, @samp{Test Legality} should be switched on.
791 It is also possible to instruct XBoard to enforce a 50-move or 3-fold-repeat
792 rule and automatically declare draw (after a user-adjustable number of moves
793 or repeats) even if the engines are prepared to go on.
794 It is also possible to have XBoard declare draw on games that seem to drag on 
795 forever, or adjudicate a loss if both engines agree (for 3 consecutive moves) that one
796 of them is behind more than a user-adjustable score threshold.
797 For the latter adjudication to work, XBoard should be able to properly understand
798 the engine's scores. To facilitate the latter, you can inform xboard here if
799 the engines report scores from the viewpoint of white, or from that of their own color.
800 @item General Settings
801 @cindex General Settings, Menu Item
802 Pops up a sub-menu where you can set some engine parameters common to most engines,
803 such as hash-table size, tablebase cache size, maximum number of processors
804 that SMP engines can use, and where to find the Polyglot adapter needed
805 to run UCI engines under XBoard. The feature that allows setting of these parameters on
806 engines is new since XBoard 4.3.15, so not many XBoard/WinBoard engines respond
807 to it yet, but UCI engines should.
808 It is also possible to specify a GUI opening book here, i.e. an opening
809 book that XBoard consults for any position a playing engine gets in.
810 It then forces the engine to play the book move, rather than to think up its own,
811 if that position is found in the book.
812 The book can switched on and off independently for either engine.
813 The shifted @kbd{Alt+U} key is a keyboard equivalent.
814 @item Engine #N Settings
815 @cindex Engine Settings, Menu Item
816 @cindex Engine #1 Settings, Menu Item
817 @cindex Engine #2 Settings, Menu Item
818 Pop up a menu dialog to alter the settings specific to the applicable engine.
819 (The second engine is only accessible once it has been used in Two-Machines mode.)
820 For each parameter the engine allows to be set,
821 a control element will appear in this dialog that can be used to alter the value.
822 Depending on the type of parameter (text string, number, multiple choice,
823 on/off switch, instantaneous signal) the appropriate control will appear,
824 with a description next to it.
825 XBoard has no idea what these values mean; it just passes them on to the engine.
826 How this dialog looks is completely determined by the engine,
827 and XBoard just passes it on to the user.
828 Many engines do not have any parameters that can be set by the user,
829 and in that case the dialog will be empty (except for the OK and cancel buttons).
830 UCI engines usually have many parameters. (But these are only visible with
831 a sufficiently modern version of the Polyglot adapter needed to run UCI engines,
832 e.g. Polyglot 1.4.55b.) For native XBoard engines this is less common.
833 @item Time Control
834 @cindex Time Control, Menu Item
835 Pops up a sub-menu where you can set the time-control parameters interactively.
836 Allows you to select classical or incremental time controls,
837 set the moves per session, session duration, and time increment.
838 Also allows specification of time-odds factors for one or both engines.
839 If an engine is given a time-odds factor N, all time quota it gets, 
840 be it at the beginning of a session or through the time increment or
841 fixed time per move, will be divided by N.
842 The shifted @kbd{Alt+T} key is a keyboard equivalent.
843 @item Always Queen
844 @cindex Always Queen, Menu Item
845 If this option is off, XBoard brings up a dialog
846 box whenever you move a pawn to the last rank, asking what piece
847 you want to promote it to. If the option is true, your pawns are
848 always promoted to queens. Your opponent can still under-promote.
849 The shifted @kbd{Ctrl-Q} key is a keyboard equivalent.
850 @item Animate Dragging
851 @cindex Animate Dragging, Menu Item
852 If Animate Dragging is on, while you are dragging a piece with the
853 mouse, an image of the piece follows the mouse cursor.
854 If Animate Dragging is off, there is no visual feedback while you are
855 dragging a piece, but if Animate Moving is on, the move will be
856 animated when it is complete. 
857 @item Animate Moving
858 @cindex Animate Moving, Menu Item
859 If Animate Moving is on, all piece moves are animated.  An image of the
860 piece is shown moving from the old square to the new square when the
861 move is completed (unless the move was already animated by Animate Dragging).
862 If Animate Moving is off, a moved piece instantly disappears from its
863 old square and reappears on its new square when the move is complete.
864 The shifted @kbd{Ctrl-A} key is a keyboard equivalent.
865 @item Auto Comment
866 @cindex Auto Comment, Menu Item
867 If this option is on, any remarks made on ICS while you are observing or
868 playing a game are recorded as a comment on the current move.  This includes
869 remarks made with the ICS commands @kbd{say}, @kbd{tell}, @kbd{whisper},
870 and @kbd{kibitz}.
871 Limitation: remarks that you type yourself are not recognized;
872 XBoard scans only the output from ICS, not the input you type to it.
873 @item Auto Flag
874 @cindex Auto Flag, Menu Item
875 If this option is on and one player runs out of time
876 before the other,
877 XBoard
878 will automatically call his flag, claiming a win on time.
879 The shifted @kbd{Ctrl-F} key is a keyboard equivalent.
880 In ICS mode, Auto Flag will only call your opponent's flag, not yours,
881 and the ICS may award you a draw instead of a win if you have
882 insufficient mating material.  In local chess engine mode,
883 XBoard
884 may call either player's flag and will not take material into account (?).
885 @item Auto Flip View
886 @cindex Auto Flip View, Menu Item
887 If the Auto Flip View option is on when you start a game, the board
888 will be automatically oriented so that your pawns move from the bottom
889 of the window towards the top.
890 @item Auto Observe
891 @cindex Auto Observe, Menu Item
892 If this option is on and you add a player to your @code{gnotify}
893 list on ICS, XBoard will automatically observe all of that
894 player's games, unless you are doing something else (such as
895 observing or playing a game of your own) when one starts.
896 The games are displayed 
897 from the point of view of the player on your gnotify list; that is, his
898 pawns move from the bottom of the window towards the top.
899 Exceptions:  If both players in a game are on your gnotify list, if
900 your ICS 
901 @code{highlight}
902 variable is set to 0, or if the ICS you are using does not 
903 properly support observing from Black's point of view,
904 you will see the game from White's point of view.
905 @item Auto Raise Board
906 @cindex Auto Raise Board, Menu Item
907 If this option is on, whenever a new game begins, the chessboard window
908 is deiconized (if necessary) and raised to the top of the stack of windows.
909 @item Auto Save
910 @cindex Auto Save, Menu Item
911 If this option is true, at the end of every game XBoard prompts
912 you for a file name and appends a record of the game to the file
913 you specify. 
914 Disabled if the @code{saveGameFile} command-line
915 option is set, as in that case all games are saved to the specified file.
916 @xref{Load and Save options}.
917 @item Blindfold
918 @cindex Blindfold, Menu Item
919 If this option is on, XBoard displays the board as usual but does
920 not display pieces or move highlights.  You can still move in the
921 usual way (with the mouse or by typing moves in ICS mode), even though
922 the pieces are invisible.
923 @item Flash Moves
924 @cindex Flash Moves, Menu Item
925 If this option is on, whenever a move is completed, the moved piece flashes.
926 The number of times to flash is set by the flashCount command-line
927 option; it defaults to 3 if Flash Moves is first turned on from the menu.
928
929 If you are playing a game on an ICS, the board is always
930 oriented at the start of the game so that your pawns move from
931 the bottom of the window towards the top. Otherwise, the starting
932 orientation is determined by the @code{flipView} command line option;
933 if it is false (the default), White's pawns move from bottom to top
934 at the start of each game; if it is true, Black's pawns move from
935 bottom to top. @xref{User interface options}.
936 @item Get Move List
937 @cindex Get Move List, Menu Item
938 If this option is on, whenever XBoard
939 receives the first board of a new ICS game (or a different game from
940 the one it is currently displaying), it
941 retrieves the list of past moves from the ICS.
942 You can then review the moves with the @samp{Forward} and @samp{Backward}
943 commands
944 or save them with @samp{Save Game}.  You might want to
945 turn off this option if you are observing several blitz games at once,
946 to keep from wasting time and network bandwidth fetching the move lists over
947 and over.
948 When you turn this option on from the menu, XBoard
949 immediately fetches the move list of the current game (if any).
950 @item Highlight Dragging
951 @cindex Highlight Dragging, Menu Item
952 If Highlight Dragging is on, and the option -showTargetSquares is also on
953 in the settings file, all squares a piece that is 'picked up' with the mouse
954 can legally move to are highighted with a fat colored dot in the
955 highlightColor (non-captures) or premoveHighlightColor (captures).
956 Legality testing must be on for XBoard to know how the piece moves.
957 @item Highlight Last Move
958 @cindex Highlight Last Move, Menu Item
959 If Highlight Last Move is on, after a move is made, the starting and
960 ending squares remain highlighted. In addition, after you use Backward
961 or Back to Start, the starting and ending squares of the last move to
962 be unmade are highlighted.
963 @item Move Sound
964 @cindex Move Sound, Menu Item
965 If this option is on, XBoard alerts you by playing a sound
966 after each of your opponent's moves (or after every
967 move if you are observing a game on the Internet Chess Server).
968 The sound is not played after moves you make or moves read from a
969 saved game file. By default, the
970 sound is the terminal bell, but on some systems you can change it
971 to a sound file using the soundMove option; see below.
972
973 If you turn on this option when using XBoard with the Internet
974 Chess Server, you will probably want to give the
975 @kbd{set bell 0}
976 command to the ICS, since otherwise the ICS will ring the terminal bell
977 after every move (not just yours). (The @file{.icsrc} file
978 is a good place for this; see @ref{ICS options}.)
979 @item ICS Alarm
980 @cindex ICS Alarm, Menu Item
981 When this option is on, an alarm sound is played when your clock
982 counts down to the icsAlarmTime (by default, 5 seconds) in an ICS
983 game.  For games with time controls that include an increment, the
984 alarm will sound each time the clock counts down to the icsAlarmTime.
985 By default, the alarm sound is the terminal bell, but on some systems
986 you can change it to a sound file using the soundIcsAlarm option; see
987 below.
988 @item Old Save Style
989 @cindex Old Save Style, Menu Item
990 If this option is off, XBoard saves games in PGN
991 (portable game notation) and positions in FEN (Forsythe-Edwards
992 notation).  If the option is on, a save style that is compatible
993 with older versions of XBoard is used instead.
994 The old position style is more human-readable
995 than FEN; the old game style has no particular advantages.
996 @item Periodic Updates
997 @cindex Periodic Updates, Menu Item
998 If this option is off (or if
999 you are using a chess engine that does not support periodic updates),
1000 the analysis window
1001 will only be updated when the analysis changes. If this option is
1002 on, the Analysis Window will be updated every two seconds.
1003 @item Ponder Next Move
1004 @cindex Ponder Next Move, Menu Item
1005 If this option is off, the chess engine will think only when it is on
1006 move.  If the option is on, the engine will also think while waiting
1007 for you to make your move.
1008 The shifted @kbd{Ctrl-P} key is a keyboard equivalent.
1009 @item Popup Exit Message
1010 @cindex Popup Exit Message, Menu Item
1011 If this option is on, when XBoard wants to display a message just
1012 before exiting, it brings up a modal dialog box and waits for you to
1013 click OK before exiting.  If the option is off, XBoard prints the
1014 message to standard error (the terminal) and exits immediately.
1015 @item Popup Move Errors
1016 @cindex Popup Move Errors, Menu Item
1017 If this option is off, when you make an error in moving (such as
1018 attempting an illegal move or moving the wrong color piece), the
1019 error message is displayed in the message area.  If the option is
1020 on, move errors are displayed in small pop-up windows like other errors.
1021 You can dismiss an error pop-up either by clicking its OK button or by
1022 clicking anywhere on the board, including down-clicking to start a move.
1023 @item Premove
1024 @cindex Premove, Menu Item
1025 If this option is on while playing a game on an ICS, you can register
1026 your next planned move before it is your turn.  Move the piece with
1027 the mouse in the ordinary way, and the starting and ending squares
1028 will be highlighted with a special color (red by default).  When it is
1029 your turn, if your registered move is legal, XBoard will send it to
1030 ICS immediately; if not, it will be ignored and you can make a
1031 different move.  If you change your mind about your premove, either
1032 make a different move, or double-click on any piece to cancel the move
1033 entirely.
1034 @item Quiet Play
1035 @cindex Quiet Play, Menu Item
1036 If this option is on, XBoard will automatically issue an ICS
1037 @kbd{set shout 0}
1038 command whenever you start a game and a
1039 @kbd{set shout 1}
1040 command whenever you finish one.  Thus, you will not be distracted
1041 by shouts from other ICS users while playing.
1042 @item Show Coords
1043 @cindex Show Coords, Menu Item
1044 If this option is on, XBoard displays algebraic coordinates
1045 along the board's left and bottom edges.
1046 @item Hide Thinking
1047 @cindex Hide Thinking, Menu Item
1048 If this option is off, the chess engine's notion of the score and best
1049 line of play from the current position is displayed as it is
1050 thinking. The score indicates how many pawns ahead (or if negative,
1051 behind) the chess engine thinks it is. In matches between two
1052 machines, the score is prefixed by @samp{W} or @samp{B} to indicate
1053 whether it is showing White's thinking or Black's, and only the thinking
1054 of the engine that is on move is shown.
1055 The shifted @kbd{Ctrl-H} key is a keyboard equivalent.
1056 @item Test Legality
1057 @cindex Test Legality, Menu Item
1058 If this option is on, XBoard tests whether the moves you try to make
1059 with the mouse are legal and refuses to let you make an illegal move.
1060 The shifted @kbd{Ctrl-L} key is a keyboard equivalent.
1061 Moves loaded from a file with @samp{Load Game} are also checked.  If
1062 the option is off, all moves are accepted, but if a local chess engine
1063 or the ICS is active, they will still reject illegal moves.  Turning
1064 off this option is useful if you are playing a chess variant with
1065 rules that XBoard does not understand.  (Bughouse, suicide, and wild
1066 variants where the king may castle after starting on the d file are
1067 generally supported with Test Legality on.)
1068 @item Save Settings Now
1069 @cindex Save Settings Now, Menu Item
1070 Selecting this menu item causes the current XBoard settings to be
1071 written to the settings file, so they will also apply in future sessions.
1072 Note that some settings are 'volatile', and are not saved,
1073 because XBoard considers it too unlikely that you want those to apply
1074 next time.
1075 In particular this applies to the Chess program names, and all options
1076 giving information on those Chess programs (such as their directory,
1077 if they have their own opening book, if they are UCI or native XBoard),
1078 or the variant you are playing.
1079 Such options would still be understood when they appear in the settings
1080 file in case they were put there with the aid of a text editor, but they
1081 would disappear from the file as soon as you save the settings.
1082 @item Save Settings on Exit
1083 @cindex Save Settings on Exit, Menu Item
1084 Setting this option has no immediate effect, but causes the settings
1085 to be saved when you quit XBoard. What happens then is otherwise 
1086 identical to what happens when you use select "Save Settings Now",
1087 see there.
1088 @end table
1089
1090 @node Help Menu
1091 @section Help Menu
1092 @cindex Menu, Help
1093 @cindex Help Menu
1094 @table @asis
1095 @item Info XBoard
1096 @cindex Info XBoard, Menu Item
1097 Displays the XBoard documentation in info format.  For this feature to
1098 work, you must have the GNU info program installed on your system, and
1099 the file @file{xboard.info} must either be present in the current
1100 working directory, or have been installed by the @samp{make install}
1101 command when you built XBoard.
1102 @item Man XBoard
1103 @cindex Man XBoard, Menu Item
1104 Displays the XBoard documentation in man page format.
1105 The @kbd{F1} key is a keyboard equivalent.  For this
1106 feature to work, the file @file{xboard.6} must have been installed by
1107 the @samp{make install} command when you built XBoard, and the
1108 directory it was placed in must be on the search path for your
1109 system's @samp{man} command.
1110 @item Hint
1111 @cindex Hint, Menu Item
1112 Displays a move hint from the chess engine.
1113 @item Book
1114 @cindex Book, Menu Item
1115 Displays a list of possible moves from the chess engine's opening
1116 book.  The exact format depends on what chess engine you are using.
1117 With GNU Chess 4, the first column gives moves, the second column
1118 gives one possible response for each move, and the third column shows
1119 the number of lines in the book that include the move from the first
1120 column. If you select this option and nothing happens, the chess
1121 engine is out of its book or does not support this feature.
1122 @item About XBoard
1123 @cindex About XBoard, Menu Item
1124 Shows the current XBoard version number.
1125 @end table
1126
1127 @node Keys
1128 @section Other Shortcut Keys
1129 @cindex Keys
1130 @cindex Shortcut keys
1131 @table @asis
1132 @item Iconize
1133 Pressing the @kbd{-} key iconizes XBoard. The graphical
1134 icon displays a white knight if it is White's move, or a black knight
1135 if it is Black's move. If your X window manager displays only text
1136 icons, not graphical ones, check its documentation; there is probably
1137 a way to enable graphical icons.  If you get black and white reversed,
1138 we would like to hear about it; see @ref{Problems} below for
1139 instructions on how to report this problem.
1140 @end table
1141
1142 You can add or remove shortcut keys using the X resources
1143 @code{form.translations}. Here is an example of what would go in your
1144 @file{.Xresources} file:
1145
1146 @example
1147 XBoard*form.translations: \
1148   Shift<Key>?: AboutGameProc() \n\
1149   <Key>y: AcceptProc() \n\
1150   <Key>n: DeclineProc() \n\
1151   <Key>i: NothingProc()
1152 @end example
1153 @noindent
1154 Binding a key to @code{NothingProc} makes it do nothing, thus removing
1155 it as a shortcut key. The XBoard commands that can be bound to keys
1156 are:
1157
1158 @example
1159 AbortProc, AboutGameProc, AboutProc, AcceptProc, AdjournProc,
1160 AlwaysQueenProc, AnalysisModeProc, AnalyzeFileProc,
1161 AnimateDraggingProc, AnimateMovingProc, AutobsProc, AutoflagProc,
1162 AutoflipProc, AutoraiseProc, AutosaveProc, BackwardProc,
1163 BlindfoldProc, BookProc, CallFlagProc, CopyGameProc, CopyPositionProc,
1164 DebugProc, DeclineProc, DrawProc, EditCommentProc, EditGameProc,
1165 EditPositionProc, EditTagsProc, EnterKeyProc, FlashMovesProc,
1166 FlipViewProc, ForwardProc, GetMoveListProc, HighlightLastMoveProc,
1167 HintProc, Iconify, IcsAlarmProc, IcsClientProc, IcsInputBoxProc,
1168 InfoProc, LoadGameProc, LoadNextGameProc, LoadNextPositionProc,
1169 LoadPositionProc, LoadPrevGameProc, LoadPrevPositionProc,
1170 LoadSelectedProc, MachineBlackProc, MachineWhiteProc, MailMoveProc,
1171 ManProc, MoveNowProc, MoveSoundProc, NothingProc, OldSaveStyleProc,
1172 PasteGameProc, PastePositionProc, PauseProc, PeriodicUpdatesProc,
1173 PonderNextMoveProc, PopupExitMessageProc, PopupMoveErrorsProc,
1174 PremoveProc, QuietPlayProc, QuitProc, ReloadCmailMsgProc,
1175 ReloadGameProc, ReloadPositionProc, RematchProc, ResetProc,
1176 ResignProc, RetractMoveProc, RevertProc, SaveGameProc,
1177 SavePositionProc, ShowCoordsProc, ShowGameListProc, ShowThinkingProc,
1178 StopExaminingProc, StopObservingProc, TestLegalityProc, ToEndProc,
1179 ToStartProc, TrainingProc, TruncateGameProc, and TwoMachinesProc.
1180 @end example
1181
1182 @node Options
1183 @chapter Options
1184 @cindex Options
1185 @cindex Options
1186
1187 This section documents the command-line options to XBoard.  You can
1188 set these options in two ways: by typing them on the shell command
1189 line you use to start XBoard, or by setting them as X resources
1190 (typically in your @file{.Xresources} file).  Many of the options
1191 cannot be changed while XBoard is running; others set the initial
1192 state of items that can be changed with the @ref{Options} menu.
1193
1194 Most of the options have both a long name and a short name. To turn a
1195 boolean option on or off from the command line, either give its long
1196 name followed by the value true or false
1197 (@samp{-longOptionName true}), or give just the short name to turn the
1198 option on (@samp{-opt}), or the short name preceded by @samp{x} to
1199 turn the option off (@samp{-xopt}). For options that take strings or
1200 numbers as values, you can use the long or short option names
1201 interchangeably.
1202
1203 Each option corresponds to an X resource with the same name, so
1204 if you like, you can set options in your @file{.Xresources} file
1205 or in a file named @file{XBoard} in your home directory.
1206 For options that have two names, the longer one is the name of
1207 the corresponding X resource; the short name is not recognized.
1208 To turn a boolean option on or off as an
1209 X resource, give its long name followed by the value
1210 true or false (@samp{XBoard*longOptionName: true}).
1211
1212 @menu
1213 * Chess engine options::        Controlling the chess engine.
1214 * UCI + WB Engine Settings::    Setting some very common engine parameters
1215 * ICS options::                 Connecting to and using ICS.
1216 * Load and Save options::       Input/output options.
1217 * User interface options::      Look and feel options.
1218 * Adjudication Options::        Control adjudication of engine-engine games.
1219 * Other options::               Miscellaneous.
1220 @end menu
1221
1222 @node Chess engine options
1223 @section Chess Engine Options
1224 @cindex options, Chess engine
1225 @cindex Chess engine options
1226 @table @asis
1227 @item -tc or -timeControl minutes[:seconds]
1228 @cindex tc, option
1229 @cindex timeControl, option
1230 Each player begins with his clock set to the @code{timeControl} period.
1231 Default: 5 minutes.
1232 The additional options @code{movesPerSession} and @code{timeIncrement}
1233 are mutually exclusive.  
1234 @item -mps or -movesPerSession moves
1235 @cindex mps, option
1236 @cindex movesPerSession, option
1237 When both players have made @code{movesPerSession} moves, a
1238 new @code{timeControl} period is added to both clocks.  Default: 40 moves.
1239 @item -inc or -timeIncrement seconds
1240 @cindex inc, option
1241 @cindex timeIncrement, option
1242 If this option is specified, @code{movesPerSession} is ignored.
1243 Instead, after each player's move, @code{timeIncrement} seconds are
1244 added to his clock.  
1245 Use @samp{-inc 0} if you want to require the entire
1246 game to be played in one @code{timeControl} period, with no increment.
1247 Default: -1, which specifies @code{movesPerSession} mode.
1248 @item -clock/-xclock or -clockMode true/false
1249 @cindex clock, option
1250 @cindex clockMode, option
1251 Determines whether or not to display the chess clocks. If clockMode is
1252 false, the clocks are not shown, but the side that is to play next
1253 is still highlighted. Also, unless @code{searchTime}
1254 is set, the chess engine still keeps track of the clock time and uses it to
1255 determine how fast to make its moves.
1256 @item -st or -searchTime minutes[:seconds]
1257 @cindex st, option
1258 @cindex searchTime, option
1259 Tells the chess engine to spend at most the given amount of time
1260 searching for each of its moves. Without this option, the chess engine
1261 chooses its search time based on the number of moves and amount
1262 of time remaining until the next time control.
1263 Setting this option also sets clockMode to false.
1264 @item -depth or -searchDepth number
1265 @cindex sd, option
1266 @cindex searchDepth, option
1267 Tells the chess engine to look ahead at most the given number of moves
1268 when searching for a move to make. Without this option, the chess
1269 engine chooses its search depth based on the number of moves and
1270 amount of time remaining until the next time control.  With the option,
1271 the engine will cut off its search early if it reaches the specified depth.
1272 @item -firstNPS number
1273 @itemx -secondNPS number
1274 @cindex firstNPS, option
1275 @cindex secondNPS, option
1276 Tells the chess engine to use an internal time standard based on its node count, 
1277 rather then wall-clock time, to make its timing decisions. 
1278 The time in virtual seconds should be obtained by dividing the node count 
1279 through the given number, like the number was a rate in nodes per second. 
1280 Xboard will manage the clocks in accordance with this, relying on the number 
1281 of nodes reported by the engine in its thinking output. If the given number equals zero, 
1282 it can obviously not be used to convert nodes to seconds, and the time reported 
1283 by the engine is used to decrement the XBoard clock in stead. The engine is supposed to 
1284 report in CPU time it uses, rather than wall-clock time, in this mode. This option 
1285 can provide fairer conditions for engine-engine matches on heavily loaded machines, 
1286 or with very fast games (where the wall clock is too inaccurate). 
1287 @code{showThinking} must be on for this option to work. Default: -1 (off).
1288 Not many engines might support this yet!
1289 @item -firstTimeOdds factor
1290 @itemx -secondTimeOdds factor
1291 @cindex firstTimeOdds, option
1292 @cindex secondTimeOdds, option
1293 Reduces the time given to the mentioned engine by the given factor. 
1294 If pondering is off, the effect is indistinguishable from what would happen 
1295 if the engine was running on an n-times slower machine. Default: 1.
1296 @item -timeOddsMode mode
1297 @cindex timeOddsMode, option
1298 This option determines how the case is handled where both engines have a time-odds handicap. 
1299 If mode=1, the engine that gets the most time will always get the nominal time, 
1300 as specified by the time-control options, and its opponent's time is renormalized accordingly. 
1301 If mode=0, both play with reduced time. Default: 0.
1302 @item -hideThinkingFromHuman true/false
1303 Controls the Hide Thinking option. @xref{Options Menu}. Default: true.
1304 (Replaces the Show-Thinking option of older xboard versions.)
1305 @item -thinking/-xthinking or -showThinking true/false
1306 @cindex thinking, option
1307 @cindex showThinking, option
1308 Forces the engine to send thinking output to xboard. 
1309 Used to be the only way to control if thinking output was displayed 
1310 in older xboard versions,
1311 but as the thinking output in xboard 4.3 is also used for several other
1312 purposes (adjudication, storing in PGN file) the display of it is now controlled
1313 by the new option Hide Thinking. @xref{Options Menu}. Default: false.
1314 (But if xboard needs the thinking output for some purpose,
1315 it makes the engine send it despite the setting of this option.)
1316 @item -ponder/-xponder or -ponderNextMove true/false
1317 @cindex ponder, option
1318 @cindex ponderNextMove, option
1319 Sets the Ponder Next Move menu option. @xref{Options Menu}. Default: true.
1320 @item -smpCores number
1321 Specifies the maximum number of CPUs an SMP engine is allowed to use.
1322 Only works for engines that support the XBoard/WinBoard-protocol cores feature.
1323 @item -mg or -matchGames n
1324 @cindex mg, option
1325 @cindex matchGames, option
1326 Automatically runs an n-game match between two chess engines,
1327 with alternating colors.
1328 If the @code{loadGameFile} or @code{loadPositionFile} option is set,
1329 XBoard
1330 starts each game with the given opening moves or the given position;
1331 otherwise, the games start with the standard initial chess position.
1332 If the @code{saveGameFile} option is set, a move record for the
1333 match is appended to the specified file. If the @code{savePositionFile}
1334 option is set, the final position reached in each game of the match is appended
1335 to the specified file. When the match is over, XBoard
1336 displays the match score and exits. Default: 0 (do not run a match).
1337 @item -mm/-xmm or -matchMode true/false
1338 @cindex mm, option
1339 @cindex matchMode, option
1340 Setting @code{matchMode} to true is equivalent to setting
1341 @code{matchGames} to 1.
1342 @item -sameColorGames n
1343 @cindex sameColorGames, option
1344 Automatically runs an n-game match between two chess engines,
1345 without alternating colors.
1346 Otherwise the same applies as for the @samp{-matchGames} option,
1347 over which it takes precedence if both are specified. (See there.)
1348 Default: 0 (do not run a match).
1349 @item -fcp or -firstChessProgram program
1350 @cindex fcp, option
1351 @cindex firstChessProgram, option
1352 Name of first chess engine.
1353 Default: @file{Fairy-Max}.
1354 @item -scp or -secondChessProgram program
1355 @cindex scp, option
1356 @cindex secondChessProgram, option
1357 Name of second chess engine, if needed.
1358 A second chess engine is started only in Two Machines (match) mode.
1359 Default: @file{Fairy-Max}.
1360 @item -fb/-xfb or -firstPlaysBlack true/false
1361 @cindex fb, option
1362 @cindex firstPlaysBlack, option
1363 In games between two chess engines, firstChessProgram normally plays
1364 white.  If this option is true, firstChessProgram plays black.  In a
1365 multi-game match, this option affects the colors only for the first
1366 game; they still alternate in subsequent games.
1367 @item -fh or -firstHost host
1368 @itemx -sh or -secondHost host
1369 @cindex fh, option
1370 @cindex firstHost, option
1371 @cindex sh, option
1372 @cindex secondHost, option
1373 Hosts on which the chess engines are to run. The default for
1374 each is @file{localhost}. If you specify another host, XBoard
1375 uses @file{rsh} to run the chess engine there. (You can substitute a
1376 different remote shell program for rsh using the @code{remoteShell}
1377 option described below.)
1378 @item -fd or -firstDirectory dir
1379 @itemx -sd or -secondDirectory dir
1380 @cindex fd, option
1381 @cindex firstDirectory, option
1382 @cindex sd, option
1383 @cindex secondDirectory, option
1384 Working directories in which the chess engines are to be run.
1385 The default is "", which means to run the chess engine
1386 in the same working directory as XBoard
1387 itself.  (See the CHESSDIR environment variable.)
1388 This option is effective only when the chess engine is being run
1389 on the local host; it does not work if the engine is run remotely
1390 using the -fh or -sh option.
1391 @item -initString string
1392 @itemx -secondInitString string
1393 @cindex initString, option
1394 @cindex secondInitString, option
1395 The string that is sent to initialize each chess engine for a new game.
1396 Default:
1397
1398 @example
1399 new
1400 random
1401 @end example
1402 @noindent
1403 Setting this option from the command line is tricky, because you must
1404 type in real newline characters, including one at the very end.
1405 In most shells you can do this by
1406 entering a @samp{\} character followed by a newline. It is easier to set
1407 the option from your @file{.Xresources} file; in that case you can
1408 include the character sequence @samp{\n} in the string, and it will
1409 be converted to a newline.
1410
1411 If you change this option, don't remove the @samp{new} 
1412 command; it is required by all chess engines to
1413 start a new game.
1414
1415 You can remove the @samp{random} command if you like; including it
1416 causes GNU Chess 4 to randomize its move selection slightly so that it
1417 doesn't play the same moves in every game.  Even without
1418 @samp{random}, GNU Chess 4 randomizes its choice of moves from its
1419 opening book.  Many other chess engines ignore this command entirely
1420 and always (or never) randomize.
1421
1422 You can also try adding other commands to the initString; see the
1423 documentation of the chess engine you are using for details.
1424 @item -firstComputerString string
1425 @itemx -secondComputerString string
1426 @cindex firstComputerString, option
1427 @cindex secondComputerString, option
1428 The string that is sent to the chess engine if its opponent is another
1429 computer chess engine.  The default is @samp{computer\n}.  Probably the
1430 only useful alternative is the empty string (@samp{}), which keeps the
1431 engine from knowing that it is playing another computer.
1432 @item -reuse/-xreuse or -reuseFirst true/false
1433 @itemx -reuse2/-xreuse2 or -reuseSecond true/false
1434 @cindex reuse, option
1435 @cindex reuseFirst, option
1436 @cindex reuse2, option
1437 @cindex reuseSecond, option
1438 If the option is false,
1439 XBoard kills off the chess engine after every game and starts
1440 it again for the next game.  
1441 If the option is true (the default), 
1442 XBoard starts the chess engine only once
1443 and uses it repeatedly to play multiple games.
1444 Some old chess engines may not work properly when
1445 reuse is turned on, but otherwise games will start faster if it is left on.
1446 @item -firstProtocolVersion version-number
1447 @itemx -secondProtocolVersion version-number
1448 @cindex firstProtocolVersion, option
1449 @cindex secondProtocolVersion, option
1450 This option specifies which version of the chess engine communication
1451 protocol to use.  By default, version-number is 2.  In version 1, the
1452 "protover" command is not sent to the engine; since version 1 is a
1453 subset of version 2, nothing else changes.  Other values for
1454 version-number are not supported.
1455 @item -firstScoreAbs true/false
1456 @itemx -secondScoreAbs true/false
1457 @cindex firstScoreAbs, option
1458 @cindex secondScoreAbs, option
1459 If this option is set, the score reported by the engine is taken to be 
1460 that in favor of white, even when the engine plays black. 
1461 Important when XBoard uses the score for adjudications, or in PGN reporting. 
1462 @item -niceEngines priority
1463 @cindex niceEngines, option
1464 This option allows you to lower the priority of the engine processes, 
1465 so that the generally insatiable hunger for CPU time of chess engines does not interfere so much 
1466 with smooth operation of XBoard (or the rest of your system). 
1467 Negative values could increase the engine priority, which is not recommended.
1468 @item -firstOptions string
1469 @itemx -secondOptions string
1470 @cindex firstOptions, option
1471 @cindex secondOptions, option
1472 The given string is a comma-separated list of (option name=option value) pairs, 
1473 like the following example: "style=Karpov,blunder rate=0". 
1474 If an option announced by the engine at startup through the feature commands of the XBoard/WinBoard protocol 
1475 matches one of the option names (i.e. "style" or "blunder rate"), 
1476 it would be set to the given value (i.e. "Karpov" or 0) 
1477 through a corresponding option command to the engine. 
1478 This provided that the type of the value (text or numeric) matches as well.
1479 @item -firstNeedsNoncompliantFEN string
1480 @itemx -secondNeedsNoncompliantFEN string
1481 @cindex firstNeedsNoncompliantFEN, option
1482 @cindex secondNeedsNoncompliantFEN, option
1483 The castling rights and e.p. fields of the FEN sent to the mentioned engine 
1484 with the setboard command will be replaced by the given string. This can for 
1485 instance be used to run engines that do not understand Chess960 FENs in 
1486 variant fischerandom, to make them at least understand the opening position, 
1487 through setting the string to "KQkq -". (Note you also have to give the e.p. field!) 
1488 Other possible applications are to provide work-arounds for engines that want to see 
1489 castling and e.p. fields in variants that do not have castling or e.p. 
1490 (shatranj, courier, xiangqi, shogi) so that XBoard would normally omit them 
1491 (string = "- -"), or to add variant-specific fields that are not yet supported by XBoard 
1492 (e.g. to indicate the number of checks in 3check).
1493 @item -shuffleOpenings
1494 @cindex shuffleOpenings, option
1495 Forces shuffling of the opening setup in variants that normally have a fixed initial position.
1496 Shufflings are symmetric for black and white, and exempt King and Rooks in variants
1497 with normal castling.
1498 Remains in force until a new variant is selected.
1499 @end table
1500
1501 @node UCI + WB Engine Settings
1502 @section UCI + WB Engine Settings
1503 @cindex Engine Settings
1504 @cindex Settings, Engine
1505 @table @asis
1506 @item -fUCI or -firstIsUCI true/false
1507 @itemx -sUCI or -secondIsUCI true/false
1508 @cindex fUCI, option
1509 @cindex sUCI, option
1510 @cindex firstIsUCI, option
1511 @cindex secondIsUCI, option
1512 Indicates if the mentioned engine executable file is an UCI engine, 
1513 and should be run with the aid of the Polyglot adapter rather than directly. 
1514 Xboard will then pass the other UCI options and engine name to Polyglot 
1515 through a .ini temporary file created for the purpose.
1516 @item -PolyglotDir filename
1517 @cindex PolyglotDir, option
1518 Gives the name of the directory in which the Polyglot adapter for UCI engines expects its files.
1519 Default: "/usr/local/share/polyglot".
1520 @item -usePolyglotBook true/false
1521 @cindex usePolyglotBook, option
1522 Specifies if the Polyglot book should be used.
1523 @item -PolyglotBook filename
1524 @cindex PolyglotBook, option
1525 Gives the filename of the opening book that Polyglot should use. 
1526 From XBoard 4.3.15 on, native XBoard/WinBoard engines will also use the opening book specified here, 
1527 provided the @code{usePolyglotBook} option is set to true,
1528 and the option @code{firstHasOwnBookUCI} or @code{secondHasOwnBookUCI} applying to the engine
1529 is set to false.
1530 The engine will be kept in force mode as long as the current position is in book, 
1531 and XBoard will select the book moves for it. Default "".
1532 @item -fNoOwnBookUCI or -firstXBook or -firstHasOwnBookUCI true/false
1533 @itemx -sNoOwnBookUCI or -secondXBook or -secondHasOwnBookUCI true/false
1534 @cindex fNoOwnBookUCI, option
1535 @cindex sNoOwnBookUCI, option
1536 @cindex firstHasOwnBookUCI, option
1537 @cindex secondHasOwnBookUCI, option
1538 @cindex firstXBook, option
1539 @cindex secondXBook, option
1540 Indicates if the mentioned engine has its own opening book it should play from,
1541 rather than using the external book through XBoard. Default: false.
1542 @item -defaultHashSize n
1543 @cindex defaultHashSize, option
1544 Sets the size of the hash table to n MegaBytes. Together with the EGTB cache size 
1545 this number is also used to calculate the memory setting of XBoard/WinBoard engines, 
1546 for those that support the memory feature of the XBoard/WinBoard protocol. Default: 64.
1547 @item -defaultCacheSizeEGTB n
1548 @cindex defaultCacheSizeEGTB, option
1549 Sets the size of the EGTB cache to n MegaBytes. Together with the hash-table size 
1550 this number is also used to calculate the memory setting of XBoard/WinBoard engines, 
1551 for those that support the memory feature of the XBoard/WinBoard protocol. Default: 4.
1552 @item -defaultPathEGTB filename
1553 @cindex defaultPathEGTB, option
1554 Gives the name of the directory where the end-game tablebases are installed, for UCI engines.
1555 Default: "/usr/local/share/egtb".
1556 @item -egtFormats string
1557 @cindex egtFormats, option
1558 Specifies which end-game tables are installed on the computer, and where. 
1559 The argument is a comma-separated list of format specifications, 
1560 each specification consisting of a format name, a colon, and a directory path name, 
1561 e.g. "nalimov:/usr/local/share/egtb". 
1562 If the name part matches that of a format that the engine requests through a feature command, 
1563 xboard will relay the path name for this format to the engine through an egtpath command. 
1564 One egtpath command for each matching format will be sent. 
1565 Popular formats are "nalimov" DTM tablebases and "scorpio" bitbases.
1566 Default: "".
1567 @end table
1568
1569 @node ICS options
1570 @section ICS options
1571 @cindex ICS options
1572 @cindex Options, ICS
1573 @table @asis
1574 @item -ics/-xics or -internetChessServerMode true/false
1575 @cindex ics, option
1576 @cindex internetChessServerMode, option
1577 Connect with an Internet Chess Server to play chess against its
1578 other users, observe games they are playing, or review games
1579 that have recently finished. Default: false.
1580 @item -icshost or -internetChessServerHost host
1581 @cindex icshost, option
1582 @cindex internetChessServerHost, option
1583 The Internet host name or address of the chess server to connect
1584 to when in ICS mode. Default: @code{chessclub.com}.
1585 Another popular chess server to try is @code{freechess.org}.
1586 If your site doesn't have a working Internet name server, try
1587 specifying the host address in numeric form. 
1588 You may also need
1589 to specify the numeric address when using the icshelper option
1590 with timestamp or timeseal (see below).
1591 @item -icsport or -internetChessServerPort port-number
1592 @cindex icsport, option
1593 @cindex internetChessServerPort, option
1594 The port number to use when connecting to a chess server in ICS
1595 mode. Default: 5000.
1596 @item -icshelper or -internetChessServerHelper prog-name
1597 @cindex icshelper, option
1598 @cindex internetChessServerHelper, option
1599 An external helper program used to communicate with the chess server.
1600 You would set it to "timestamp" for ICC (chessclub.com) or
1601 "timeseal" for FICS (freechess.org), after
1602 obtaining the correct version of timestamp or timeseal for your
1603 computer.  See "help timestamp" on ICC and "help timeseal" on FICS.
1604 This option is shorthand for @code{-useTelnet -telnetProgram program}.
1605 @item -telnet/-xtelnet or -useTelnet true/false
1606 @cindex telnet, option
1607 @cindex useTelnet, option
1608 This option is poorly named; it should be called useHelper.
1609 If set to true, it instructs XBoard to run an external
1610 program to communicate with the Internet Chess Server. 
1611 The program to use is given by the telnetProgram option.
1612 If the option is
1613 false (the default), XBoard opens a TCP socket and uses its own
1614 internal implementation of the telnet protocol to communicate with the
1615 ICS. @xref{Firewalls}.
1616 @item -telnetProgram prog-name
1617 @cindex telnetProgram, option
1618 This option is poorly named; it should be called helperProgram.
1619 It gives the name of the telnet program to be used with
1620 the @code{gateway} and @code{useTelnet} options.  The default is
1621 @file{telnet}. The telnet program is invoked with the value of
1622 @code{internetChessServerHost} as its first argument and the value
1623 of @code{internetChessServerPort} as its second argument.
1624 @xref{Firewalls}.
1625 @item -gateway host-name
1626 @cindex gateway, option
1627 If this option is set to a host name, XBoard communicates with the
1628 Internet Chess Server by using @file{rsh} to run
1629 the @code{telnetProgram} on the given host,
1630 instead of using its own internal implementation
1631 of the telnet protocol. You can substitute a different remote shell
1632 program for @file{rsh} using the @code{remoteShell} option described below.
1633 @xref{Firewalls}.
1634 @item -internetChessServerCommPort or -icscomm dev-name
1635 @cindex internetChessServerCommPort, option
1636 @cindex icscomm, option
1637 If this option is set, XBoard communicates with the ICS through
1638 the given character I/O device instead of opening a TCP connection.
1639 Use this option if your system does not have any kind of
1640 Internet connection itself (not even a SLIP or PPP connection),
1641 but you do have dial-up access (or a hardwired terminal line) to
1642 an Internet service provider from which you can telnet to the ICS.
1643
1644 The support for this option in XBoard is minimal. You need to
1645 set all communication parameters and tty modes before you enter
1646 XBoard.
1647
1648 Use a script something like this:
1649
1650 @example
1651 stty raw -echo 9600 > /dev/tty00
1652 xboard -ics -icscomm /dev/tty00
1653 @end example
1654
1655 Here replace @samp{/dev/tty00} with the name of the device that your
1656 modem is connected to. You might have to add several more
1657 options to these stty commands. See the man pages for @file{stty}
1658 and @code{tty} if you run into problems. Also, on many systems stty
1659 works on its standard input instead of standard output, so you
1660 have to use @samp{<} instead of @samp{>}.
1661
1662 If you are using linux, try starting with the script below.
1663 Change it as necessary for your installation.
1664
1665 @example
1666 #!/bin/sh -f
1667 # configure modem and fire up XBoard
1668
1669 # configure modem
1670 (
1671   stty 2400 ; stty raw ; stty hupcl ; stty -clocal
1672   stty ignbrk ; stty ignpar ; stty ixon ; stty ixoff
1673   stty -iexten ; stty -echo
1674 ) < /dev/modem
1675 xboard -ics -icscomm /dev/modem
1676 @end example
1677 @noindent
1678 After you start XBoard in this way, type whatever commands are
1679 necessary to dial out to your Internet provider and log in.
1680 Then telnet to ICS, using a command like
1681 @kbd{telnet chessclub.com 5000}.
1682 Important: See the paragraph below about extra echoes, 
1683 in @ref{Limitations}.
1684 @item -icslogon or -internetChessServerLogonScript file-name
1685 @cindex icslogon, option
1686 @cindex internetChessServerLogonScript, option
1687 @cindex .icsrc
1688 Whenever XBoard connects to the Internet Chess Server,
1689 if it finds a file with the name given in this option, it feeds the
1690 file's contents to the ICS as commands. The default file name
1691 is @file{.icsrc}.
1692 Usually the first two lines of the file should be
1693 your ICS user name and password.
1694 The file can be either in $CHESSDIR, in XBoard's working
1695 directory if CHESSDIR is not set, or in your home directory.
1696 @item -msLoginDelay delay
1697 @cindex msLoginDelay, option
1698 If you experience trouble logging on to an ICS when using the
1699 @code{-icslogon} option, inserting some delay between characters
1700 of the logon script may help. This option adds @code{delay}
1701 milliseconds of delay between characters. Good values to try
1702 are 100 and 250.
1703 @item -icsinput/-xicsinput or -internetChessServerInputBox true/false
1704 @cindex icsinput, option
1705 @cindex internetChessServerInputBox, option
1706 Sets the ICS Input Box menu option. @xref{Mode Menu}. Default: false.
1707 @item -autocomm/-xautocomm or -autoComment true/false
1708 @cindex autocomm, option
1709 @cindex autoComment, option
1710 Sets the Auto Comment menu option. @xref{Options Menu}. Default: false.
1711 @item -autoflag/-xautoflag or -autoCallFlag true/false
1712 @cindex autoflag, option
1713 @cindex autoCallFlag, option
1714 Sets the Auto Flag menu option.  @xref{Options Menu}. Default: false.
1715 @item -autobs/-xautobs or -autoObserve true/false
1716 @cindex autobs, option
1717 @cindex autoObserve, option
1718 Sets the Auto Observe menu option.  @xref{Options Menu}. Default: false.
1719 @item -autoKibitz
1720 @cindex autoKibitz, option
1721 Enables kibitzing of the engines last thinking output (depth, score, time, speed, PV) 
1722 before it moved
1723 to the ICS, in zippy mode. The option @code{showThinking} must be switched on for 
1724 this option to work.
1725 Also diverts similar kibitz information of an opponent engine that is playing you 
1726 through the ICS to the engine-output window, as if the engine was playing locally.
1727 @item -seekGraph true/false or -sg
1728 @cindex seekGraph, option
1729 @cindex sg, option
1730 Enables displaying of the seek graph by left-clicking the board when
1731 you are logged on to an ICS and currently idle.
1732 The seek graph show all players currently seeking games on the ICS,
1733 plotted according to their rating and the time control of the game they seek,
1734 in three different colors (for rated, unrated and wild games).
1735 Computer ads are displayed as squares, human ads are dots.
1736 Default: false.
1737 @item -autoRefresh true/false
1738 @cindex autoRefresh, option
1739 Enables automatic updating of the seek graph,
1740 by having the ICS send a running update of all newly placed
1741 and removed seek ads.
1742 This consumes a substantial amount of communication bandwidth,
1743 and is only supported for FICS and ICC.
1744 Default: false.
1745 @item -backgroundObserve true/false
1746 @cindex backgroundObserve, option
1747 When true, boards sent to you by the ICS from other games while you are playing
1748 (e.g. because you are observing them)
1749 will not be automatically displayed.
1750 Only a summary of time left and material of both players will appear
1751 in the message field above the board.
1752 XBoard will remember the last board it has received this way,
1753 and will display it in stead of the position in your own game
1754 when you press the right mouse button.
1755 No other information is stored on such games observed in the background;
1756 you cannot save such a game later, or step through its moves.
1757 This feature is provided solely for the benefit of bughouse players,
1758 to enable them to peek at their partner's game without the need
1759 to logon twice.
1760 Default: false.
1761 @item -dualBoard true/false
1762 @cindex dualBoard, option
1763 In combination with -backgroundObserve true, this option will display
1764 the board of the background game side by side with that of your own game,
1765 so you can have it in view permanently.
1766 Any board or holdings info coming in will be displayed on the secondary
1767 board immediately.
1768 This feature is still experimental and largely unfinished.
1769 There is no animation or highlighting of moves on the secondary board.
1770 Default: false.
1771 @item -oneClickMove true/false
1772 @cindex oneClickMove, option
1773 When set, this option allows you to enter moves by only clicking the to-
1774 or from-square, when only a single legal move to or from that square
1775 is possible.
1776 Double-clicking a piece (or clicking an already selected piece)
1777 will instruct that piece to make the only capture it can legally do.
1778 Defaut: false.
1779 @item -moves/-xmoves or -getMoveList true/false
1780 @cindex moves, option
1781 @cindex getMoveList, option
1782 Sets the Get Move List menu option.  @xref{Options Menu}.  Default: true.
1783 @item -alarm/-xalarm or -icsAlarm true/false
1784 @cindex alarm, option
1785 @cindex icsAlarm, option
1786 Sets the ICS Alarm menu option.  @xref{Options Menu}. Default: true.
1787 @item -icsAlarmTime ms
1788 @cindex icsAlarmTime, option
1789 Sets the time in milliseconds for the ICS Alarm menu option.
1790 @xref{Options Menu}. Default: 5000.
1791 @item lowTimeWarning true/false
1792 @cindex lowTimeWarning, option
1793 Controls a color change of the board as a warning your time is running out.
1794 @xref{Options Menu}. Default: false.
1795 @item -pre/-xpre \fRor\fB -premove true/false
1796 @cindex pre, option
1797 @cindex premove, option
1798 Sets the Premove menu option. @xref{Options Menu}. Default: true.
1799 @item -quiet/-xquiet or -quietPlay true/false
1800 @cindex quiet, option
1801 @cindex quietPlay, option
1802 Sets the Quiet Play menu option.  @xref{Options Menu}.  Default: false.
1803 @item -colorizeMessages or -colorize
1804 @cindex Colors
1805 @cindex colorize, option
1806 Setting colorizeMessages
1807 to true tells XBoard to colorize the messages received from
1808 the ICS.  Colorization works only if your xterm 
1809 supports ISO 6429 escape sequences for changing text colors.
1810 @item -colorShout foreground,background,bold
1811 @itemx -colorSShout foreground,background,bold
1812 @itemx -colorChannel1 foreground,background,bold
1813 @itemx -colorChannel foreground,background,bold
1814 @itemx -colorKibitz foreground,background,bold
1815 @itemx -colorTell foreground,background,bold
1816 @itemx -colorChallege foreground,background,bold
1817 @itemx -colorRequest foreground,background,bold
1818 @itemx -colorSeek foreground,background,bold
1819 @itemx -colorNormal foreground,background,bold
1820 @cindex Colors
1821 @cindex colorShout, option
1822 @cindex colorSShout, option
1823 @cindex colorChannel1, option
1824 @cindex colorChannel, option
1825 @cindex colorKibitz, option
1826 @cindex colorTell, option
1827 @cindex colorChallenge, option
1828 @cindex colorRequest, option
1829 @cindex colorSeek, option
1830 @cindex colorNormal, option
1831 These options set the colors used when colorizing ICS messages.
1832 All ICS messages are grouped into one of these categories:
1833 shout, sshout, channel 1, other channel, kibitz, tell, challenge, 
1834 request (including abort, adjourn, draw, pause, and takeback), or
1835 normal (all other messages).  
1836
1837 Each foreground or background argument can be one of the following:
1838 black, red, green, yellow, blue, magenta, cyan, white, or default.
1839 Here ``default'' means the default foreground or background color of
1840 your xterm.  Bold can be 1 or 0.  If background is omitted, ``default''
1841 is assumed; if bold is omitted, 0 is assumed.
1842
1843 Here is an example of how to set the colors in your @file{.Xresources} file.
1844 The colors shown here are the default values; you will get
1845 them if you turn @code{-colorize} on without specifying your own colors.
1846
1847 @example
1848 xboard*colorizeMessages: true   
1849 xboard*colorShout: green
1850 xboard*colorSShout: green, black, 1
1851 xboard*colorChannel1: cyan
1852 xboard*colorChannel: cyan, black, 1
1853 xboard*colorKibitz: magenta, black, 1
1854 xboard*colorTell: yellow, black, 1
1855 xboard*colorChallenge: red, black, 1
1856 xboard*colorRequest: red
1857 xboard*colorSeek: blue
1858 xboard*colorNormal: default
1859 @end example
1860 @item -soundProgram progname
1861 @cindex soundProgram, option
1862 @cindex Sounds
1863 If this option is set to a sound-playing program that is installed and
1864 working on your system, XBoard can play sound files when certain
1865 events occur, listed below.  The default program name is "play".  If
1866 any of the sound options is set to "$", the event rings the terminal
1867 bell by sending a ^G character to standard output, instead of playing
1868 a sound file.  If an option is set to the empty string "", no sound is
1869 played for that event.
1870 @item -soundShout filename
1871 @itemx -soundSShout filename
1872 @itemx -soundChannel filename
1873 @itemx -soundKibitz filename
1874 @itemx -soundTell filename
1875 @itemx -soundChallenge filename
1876 @itemx -soundRequest filename
1877 @itemx -soundSeek filename
1878 @cindex soundShout, option
1879 @cindex soundSShout, option
1880 @cindex soundChannel, option
1881 @cindex soundKibitz, option
1882 @cindex soundTell, option
1883 @cindex soundChallenge, option
1884 @cindex soundRequest, option
1885 @cindex soundSeek, option
1886 These sounds are triggered in the same way as the colorization events
1887 described above.  They all default to "", no sound.  They are played
1888 only if the colorizeMessages is on.
1889 @item -soundMove filename
1890 @cindex soundMove, option
1891 This sound is used by the Move Sound menu option.  Default: "$".
1892 @item -soundIcsAlarm filename
1893 @cindex soundIcsAlarm, option
1894 This sound is used by the ICS Alarm menu option.  Default: "$".
1895 @item -soundIcsWin filename
1896 @cindex soundIcsWin, option
1897 This sound is played when you win an ICS game.  Default: "" (no sound).
1898 @item -soundIcsLoss filename
1899 @cindex soundIcsLoss, option
1900 This sound is played when you lose an ICS game.  Default: "" (no sound).
1901 @item -soundIcsDraw filename
1902 @cindex soundIcsDraw, option
1903 This sound is played when you draw an ICS game.  Default: "" (no sound).
1904 @item -soundIcsUnfinished filename
1905 @cindex soundIcsUnfinished, option
1906 This sound is played when an ICS game that you are participating in is
1907 aborted, adjourned, or otherwise ends inconclusively.  Default: "" (no
1908 sound).
1909
1910 Here is an example of how to set the sounds in your @file{.Xresources} file:
1911
1912 @example
1913 xboard*soundShout: shout.wav
1914 xboard*soundSShout: sshout.wav
1915 xboard*soundChannel1: channel1.wav
1916 xboard*soundChannel: channel.wav
1917 xboard*soundKibitz: kibitz.wav
1918 xboard*soundTell: tell.wav
1919 xboard*soundChallenge: challenge.wav
1920 xboard*soundRequest: request.wav
1921 xboard*soundSeek: seek.wav
1922 xboard*soundMove: move.wav
1923 xboard*soundIcsWin: win.wav
1924 xboard*soundIcsLoss: lose.wav
1925 xboard*soundIcsDraw: draw.wav
1926 xboard*soundIcsUnfinished: unfinished.wav
1927 xboard*soundIcsAlarm: alarm.wav
1928 @end example
1929 @item -dropMenu true|false
1930 @cindex dropMenu, option
1931 This option allows you to emulate old behavior, 
1932 where the right mouse button brings up the (now deprecated) drop menu 
1933 rather than displaying the position at the end of the principal variation. 
1934 Default: False.
1935 @end table
1936
1937 @node Load and Save options
1938 @section Load and Save options
1939 @cindex Options, Load and Save
1940 @cindex Load and Save options
1941 @table @asis
1942 @item -lgf or -loadGameFile file
1943 @itemx -lgi or -loadGameIndex index
1944 @cindex lgf, option
1945 @cindex loadGameFile, option
1946 @cindex lgi, option
1947 @cindex loadGameIndex, option
1948 If the @code{loadGameFile} option is set, XBoard loads the specified
1949 game file at startup. The file name @file{-} specifies the standard
1950 input. If there is more than one game in the file, XBoard
1951 pops up a menu of the available games, with entries based on their PGN 
1952 (Portable Game Notation) tags.
1953 If the @code{loadGameIndex} option is set to @samp{N}, the menu is suppressed
1954 and the N th game found in the file is loaded immediately.
1955 The menu is also suppressed if @code{matchMode} is enabled or if the game file
1956 is a pipe; in these cases the first game in the file is loaded immediately.
1957 Use the @file{pxboard} shell script provided with XBoard if you
1958 want to pipe in files containing multiple games and still see the menu.
1959 If the loadGameIndex specifies an index -1, this triggers auto-increment
1960 of the index in @code{matchMode}, which means that after every game the
1961 index is incremented by one, causing each game of the match to be played
1962 from the next game in the file. Similarly, specifying an index value of -2
1963 causes the index to be incremented every two games, so that each game
1964 in the file is used twice (with reversed colors).
1965 The @code{rewindIndex} option causes the index to be reset to the
1966 first game of the file when it has reached a specified value.
1967 @item -rewindIndex n
1968 Causes a position file or game file to be rewound to its beginning after n
1969 positions or games in auto-increment @code{matchMode}. 
1970 See @code{loadPositionIndex} and @code{loadGameIndex}.
1971 default: 0 (no rewind).
1972 @item -td or -timeDelay seconds
1973 @cindex td, option
1974 @cindex timeDelay, option
1975 Time delay between moves during @samp{Load Game}. Fractional seconds
1976 are allowed; try @samp{-td 0.4}. A time delay value of -1 tells
1977 XBoard not to step through game files automatically. Default: 1
1978 second.
1979 @item -sgf or -saveGameFile file
1980 @cindex sgf, option
1981 @cindex saveGameFile, option
1982 If this option is set, XBoard appends a record of every game
1983 played to the specified file. The file name @file{-} specifies the
1984 standard output.
1985 @item -autosave/-xautosave or -autoSaveGames true/false
1986 @cindex autosave, option
1987 @cindex autoSaveGames, option
1988 Sets the Auto Save menu option.  @xref{Options Menu}.  Default: false.
1989 Ignored if @code{saveGameFile} is set.
1990 @item -lpf or -loadPositionFile file
1991 @itemx -lpi or -loadPositionIndex index
1992 @cindex lpf, option
1993 @cindex loadPositionFile, option
1994 @cindex lpi, option
1995 @cindex loadPositionIndex, option
1996 If the @code{loadPositionFile} option is set, XBoard loads the
1997 specified position file at startup. The file name @file{-} specifies the
1998 standard input. If the @code{loadPositionIndex} option is set to N,
1999 the Nth position found in the file is loaded; otherwise the
2000 first position is loaded.
2001 If the loadPositionIndex specifies an index -1, this triggers auto-increment
2002 of the index in @code{matchMode}, which means that after every game the
2003 index is incremented by one, causing each game of the match to be played
2004 from the next position in the file. Similarly, specifying an index value of -2
2005 causes the index to be incremented every two games, so that each position
2006 in the file is used twice (with the engines playing opposite colors).
2007 The @code{rewindIndex} option causes the index to be reset to the
2008 first position of the file when it has reached a specified value.
2009 @item -spf or -savePositionFile file
2010 @cindex spf, option
2011 @cindex savePositionFile, option
2012 If this option is set, XBoard appends the final position reached
2013 in every game played to the specified file. The file name @file{-}
2014 specifies the standard output.
2015 @item -pgnExtendedInfo true/false
2016 @cindex pgnExtendedInfo, option`
2017 If this option is set, XBoard saves depth, score and time used for each 
2018 move that the engine found as a comment in the PGN file.
2019 Default: false.
2020 @item -pgnEventHeader string
2021 @cindex pgnEventHeader, option`
2022 Sets the name used in the PGN event tag to string. 
2023 Default: "Computer Chess Game".
2024 @item -saveOutOfBookInfo true/false
2025 @cindex saveOutOfBookInfo, option`
2026 Include the information on how the engine(s) game out of its opening book 
2027 in a special 'annotator' tag with the PGN file.
2028 @item -oldsave/-xoldsave or -oldSaveStyle true/false
2029 @cindex oldsave, option
2030 @cindex oldSaveStyle, option
2031 Sets the Old Save Style menu option.  @xref{Options Menu}.  Default: false.
2032 @item -gameListTags string
2033 @cindex gameListTags, option
2034 The character string lists the PGN tags that should be printed in the
2035 Game List, and their order. The meaning of the codes is e=event,
2036 s=site, d=date, o=round, p=players, r=result, w=white Elo, b=black Elo,
2037 t=time control, v=variant, a=out-of-book info, c=result comment.
2038 Default: "eprd"
2039 @item -ini or -settingsFile filename
2040 @itemx -saveSettingsFile filename
2041 @itemx @@filename
2042 @cindex saveSettingsFile, option
2043 @cindex SettingsFile, option
2044 @cindex init, option
2045 @cindex at sign, option
2046 When XBoard encounters an option -settingsFile (or -ini for short),
2047 or @@filename, it tries to read the mentioned file,
2048 and substitutes the contents of it (presumaby more command-line options)
2049 in place of the option.
2050 In the case of -ini or -settingsFile, the name of a successfully read
2051 settings file is also remembered as the file to use for saving settings
2052 (automatically on exit, or on user command).
2053 An option of the form @@filename does not affect saving.
2054 The option -saveSettingsFile does specify a name of the file to use
2055 for saving, without reading any options from it, and is thus also effective
2056 when the file did not exist yet.
2057 So the settings will be saved to the file specified in the last
2058 -saveSettingsFile or succesfull -settingsFile / -ini command,
2059 if any, and in /etc/xboard/xboard.conf otherwise.
2060 Usualy the latter is only accessible for the system administrator, though, 
2061 and will be used to contain system-wide default setings, amongst which
2062 a -saveSettingsFile and -settingsFile options to specify a settings file
2063 accessible to the individual user, such as ~/.xboardrc in the user's
2064 home directory.
2065 @end table
2066
2067 @node User interface options
2068 @section User interface options
2069 @cindex User interface options
2070 @cindex Options, User interface
2071 @table @asis
2072 @item -display
2073 @itemx -geometry
2074 @itemx -iconic
2075 @cindex display, option
2076 @cindex geometry, option
2077 @cindex iconic, option
2078 These and most other standard Xt options are accepted.
2079 @item -noGUI
2080 @cindex noGUI, option
2081 Suppresses all GUI functions of XBoard 
2082 (to speed up automated ultra-fast engine-engine games, which you don\92t want to watch). 
2083 There will be no board or clock updates, no printing of moves, 
2084 and no update of the icon on the task bar in this mode.
2085 @item -movesound/-xmovesound or -ringBellAfterMoves true/false
2086 @cindex movesound, option
2087 @cindex bell, option
2088 @cindex ringBellAfterMoves, option
2089 Sets the Move Sound menu option.  @xref{Options Menu}.  Default: false.
2090 For compatibility with old XBoard versions, -bell/-xbell are also 
2091 accepted as abbreviations for this option.
2092 @item -exit/-xexit or -popupExitMessage true/false
2093 @cindex exit, option
2094 @cindex popupExitMessage, option
2095 Sets the Popup Exit Message menu option.  @xref{Options Menu}. Default: true.
2096 @item -popup/-xpopup or -popupMoveErrors true/false
2097 @cindex popup, option
2098 @cindex popupMoveErrors, option
2099 Sets the Popup Move Errors menu option.  @xref{Options Menu}. Default: false.
2100 @item -queen/-xqueen or -alwaysPromoteToQueen true/false
2101 @cindex queen, option
2102 @cindex alwaysPromoteToQueen, option
2103 Sets the Always Queen menu option.  @xref{Options Menu}.  Default: false.
2104 @item -legal/-xlegal or -testLegality true/false
2105 @cindex legal, option
2106 @cindex testLegality, option
2107 Sets the Test Legality menu option.  @xref{Options Menu}.  Default: true.
2108 @item -size or -boardSize (sizeName | n1,n2,n3,n4,n5,n6,n7)
2109 @cindex size, option
2110 @cindex boardSize, option
2111 @cindex board size
2112 Determines how large the board will be, by selecting the pixel size
2113 of the pieces and setting a few related parameters.
2114 The sizeName can be one of: Titanic, giving 129x129 pixel pieces,
2115 Colossal 116x116, Giant 108x108, Huge 95x95, Big 87x87, Large 80x80, Bulky 72x72,
2116 Medium 64x64, Moderate 58x58, Average 54x54, Middling 49x49, Mediocre
2117 45x45, Small 40x40, Slim 37x37, Petite 33x33, Dinky 29x29, Teeny 25x25,
2118 or Tiny 21x21.
2119 Orthodox pieces of all these sizes are built into XBoard.
2120 Other sizes can
2121 be used if you have them; see the pixmapDirectory and bitmapDirectory
2122 options.
2123 Complete sets of un-orthodox pieces are only provided in sizes
2124 Bulky, Middling and (to a lesser extent) Petite;
2125 Archbishop, Marshall and Amazon are also available in all sizes between
2126 Bulky and Petite.
2127 When no bitmap is available, the piece will be displayed as Amazon or King.
2128 The default depends on the size of your screen; it is approximately the
2129 largest size that will fit without clipping.
2130
2131 You can select other sizes or vary other layout parameters by providing
2132 a list of comma-separated values (with no spaces) as the argument.
2133 You do not need to provide all the values; for any you omit from the
2134 end of the list, defaults are taken from the nearest built-in size.
2135 The value @code{n1} gives the piece size, @code{n2} the width of the
2136 black border
2137 between squares, @code{n3} the desired size for the 
2138 clockFont, @code{n4} the desired size for the coordFont,
2139 @code{n5} the desired size for the default font,
2140 @code{n6} the smallLayout flag (0 or 1), 
2141 and @code{n7} the tinyLayout flag (0 or 1).  
2142 All dimensions are in pixels.
2143 If the border between squares is eliminated (0 width), the various
2144 highlight options will not work, as there is nowhere to draw the highlight.
2145 If smallLayout is 1 and @code{titleInWindow} is true, 
2146 the window layout is rearranged to make more room for the title.
2147 If tinyLayout is 1, the labels on the menu bar are abbreviated
2148 to one character each and the buttons in the button bar are made narrower.
2149 @item -coords/-xcoords or -showCoords true/false
2150 @cindex coords, option
2151 @cindex showCoords, option
2152 Sets the Show Coords menu option.  @xref{Options Menu}.  Default: false.
2153 The @code{coordFont} option specifies what font to use.
2154 @item -autoraise/-xautoraise or -autoRaiseBoard true/false
2155 @cindex autoraise, option
2156 @cindex autoRaiseBoard, option
2157 Sets the Auto Raise Board menu option.  @xref{Options Menu}.  Default: true.
2158 @item -autoflip/-xautoflip or -autoFlipView true/false
2159 @cindex autoflip, option
2160 @cindex autoFlipView, option
2161 Sets the Auto Flip View menu option.  @xref{Options Menu}.  Default: true.
2162 @item -flip/-xflip or -flipView true/false
2163 @cindex flip, option
2164 @cindex flipView, option
2165 If Auto Flip View is not set, or if you are observing but not participating
2166 in a game, then the positioning of the board at the start of each game
2167 depends on the flipView option.  If flipView is false (the default),
2168 the board is positioned so that the white pawns move from the bottom to the
2169 top; if true, the black pawns move from the bottom to the top.
2170 In any case, the Flip menu option (see @ref{Options Menu})
2171 can be used to flip the board after
2172 the game starts.
2173 @item -title/-xtitle or -titleInWindow true/false
2174 @cindex title, option
2175 @cindex titleInWindow, option
2176 If this option is true, XBoard displays player names (for ICS
2177 games) and game file names (for @samp{Load Game}) inside its main
2178 window. If the option is false (the default), this information is
2179 displayed only in the window banner. You probably won't want to
2180 set this option unless the information is not showing up in the
2181 banner, as happens with a few X window managers.
2182 @item -buttons/-xbuttons or -showButtonBar True/False
2183 @cindex buttons, option
2184 @cindex showButtonBar, option
2185 If this option is False, xboard omits the [<<] [<] [P] [>] [>>] button
2186 bar from the window, allowing the message line to be wider.  You can
2187 still get the functions of these buttons using the menus or their keyboard
2188 shortcuts.  Default: true.
2189 @item -mono/-xmono or -monoMode true/false
2190 @cindex mono, option
2191 @cindex monoMode, option
2192 Determines whether XBoard displays its pieces and squares with
2193 two colors (true) or four (false). You shouldn't have to
2194 specify @code{monoMode}; XBoard will determine if it is necessary.
2195 @item -showTargetSquares true/false
2196 @cindex showTargetSquares, option
2197 Determines whether XBoard can highlight the squares a piece has
2198 legal moves to, when you grab that piece with the mouse.
2199 If this option is set, this feature can be controlled through
2200 the Highlight Dragging menu item.
2201 @item -flashCount count
2202 @itemx -flashRate rate
2203 @itemx -flash/-xflash
2204 @cindex flashCount, option
2205 @cindex flashRate, option
2206 @cindex flash, option
2207 @cindex xflash, option
2208 These options enable flashing of pieces when they
2209 land on their destination square.
2210 @code{flashCount}
2211 tells XBoard how many times to flash a piece after it
2212 lands on its destination square.
2213 @code{flashRate}
2214 controls the rate of flashing (flashes/sec).
2215 Abbreviations:
2216 @code{flash}
2217 sets flashCount to 3.
2218 @code{xflash}
2219 sets flashCount to 0.
2220 Defaults:  flashCount=0 (no flashing), flashRate=5.
2221 @item -highlight/-xhighlight or -highlightLastMove true/false
2222 @cindex highlight, option
2223 @cindex highlightLastMove, option
2224 Sets the Highlight Last Move menu option. @xref{Options Menu}. Default: false.
2225 @item -blind/-xblind or -blindfold true/false
2226 @cindex blind, option
2227 @cindex blindfold, option
2228 Sets the Blindfold menu option.  @xref{Options Menu}.  Default: false.
2229 @item -clockFont font
2230 @cindex clockFont, option
2231 @cindex Font, clock
2232 The font used for the clocks. If the option value is a pattern
2233 that does not specify the font size, XBoard tries to choose an
2234 appropriate font for the board size being used.
2235 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
2236 @item -coordFont font
2237 @cindex coordFont, option
2238 @cindex Font, coordinates
2239 The font used for rank and file coordinate labels if @code{showCoords}
2240 is true. If the option value is a pattern that does not specify
2241 the font size, XBoard tries to choose an appropriate font for
2242 the board size being used.
2243 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
2244 @item -font font
2245 @cindex font, option
2246 @cindex Font
2247 The font used for popup dialogs, menus, comments, etc.
2248 If the option value is a pattern that does not specify
2249 the font size, XBoard tries to choose an appropriate font for
2250 the board size being used.
2251 Default: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*.
2252 @item -fontSizeTolerance tol
2253 @cindex fontSizeTolerance, option
2254 In the font selection algorithm, a nonscalable font will be preferred
2255 over a scalable font if the nonscalable font's size differs
2256 by @code{tol} pixels
2257 or less from the desired size.  A value of -1 will force
2258 a scalable font to always be used if available; a value of 0 will
2259 use a nonscalable font only if it is exactly the right size; 
2260 a large value (say 1000) will force a nonscalable font to always be
2261 used if available.  Default: 4.
2262 @item -bm or -bitmapDirectory dir
2263 @itemx -pixmap or -pixmapDirectory dir
2264 @cindex bm, option
2265 @cindex bitmapDirectory, option
2266 @cindex pixmap, option
2267 @cindex pixmapDirectory, option
2268 These options control what piece images xboard uses.  The XBoard
2269 distribution includes one set of pixmap pieces in xpm format, in the
2270 directory @file{pixmaps}, and one set of bitmap pieces in xbm format,
2271 in the directory @file{bitmaps}.  Pixmap
2272 pieces give a better appearance on the screen: the white pieces have
2273 dark borders, and the black pieces have opaque internal details.  With
2274 bitmaps, neither piece color has a border, and the internal details
2275 are transparent; you see the square color or other background color
2276 through them.
2277
2278 If XBoard is configured and compiled on a system that includes libXpm,
2279 the X pixmap library, the xpm pixmap pieces are compiled in as the
2280 default.  A different xpm piece set can be selected at runtime with
2281 the @code{pixmapDirectory} option, or a bitmap piece set can be selected
2282 with the @code{bitmapDirectory} option.
2283
2284 If XBoard is configured and compiled on a system that does not include
2285 libXpm (or the @code{--disable-xpm} option is given to the configure
2286 program), the bitmap pieces are compiled in as the default.  It is not
2287 possible to use xpm pieces in this case, but pixmap pieces in another
2288 format called "xim" can be used by giving the @code{pixmapDirectory} option.
2289 Or again, a different bitmap piece set can be selected with the
2290 @code{bitmapDirectory} option.
2291
2292 Files in the @code{bitmapDirectory} must be named as follows:
2293 The first character of a piece bitmap name gives the piece it 
2294 represents (@samp{p}, @samp{n}, @samp{b}, @samp{r}, @samp{q}, or @samp{k}),
2295 the next characters give the size in pixels, the
2296 following character indicates whether the piece is
2297 solid or outline (@samp{s} or @samp{o}),
2298 and the extension is @samp{.bm}.
2299 For example, a solid 80x80 knight would be named @file{n80s.bm}.
2300 The outline bitmaps are used only in monochrome mode.
2301 If bitmap pieces are compiled in and the bitmapDirectory is missing
2302 some files, the compiled in pieces are used instead.
2303
2304 If the bitmapDirectory option is given,
2305 it is also possible to replace xboard's icons and menu checkmark,
2306 by supplying files named @file{icon_white.bm}, @file{icon_black.bm}, and
2307 @file{checkmark.bm}.
2308
2309 For more information about pixmap pieces and how to get additional
2310 sets, see @ref{zic2xpm} below.
2311 @item -whitePieceColor color
2312 @itemx -blackPieceColor color
2313 @itemx -lightSquareColor color
2314 @itemx -darkSquareColor color
2315 @itemx -highlightSquareColor color
2316 @itemx -lowTimeWarningColor color
2317 @cindex Colors
2318 @cindex whitePieceColor, option
2319 @cindex blackPieceColor, option
2320 @cindex lightSquareColor, option
2321 @cindex darkSquareColor, option
2322 @cindex highlightSquareColor, option
2323 @cindex lowTimeWarningColor, option
2324 Colors to use for the pieces, squares, and square highlights.
2325 Defaults:
2326
2327 @example
2328 -whitePieceColor       #FFFFCC
2329 -blackPieceColor       #202020
2330 -lightSquareColor      #C8C365
2331 -darkSquareColor       #77A26D
2332 -highlightSquareColor  #FFFF00
2333 -premoveHighlightColor #FF0000
2334 -lowTimeWarningColor   #FF0000
2335 @end example
2336
2337 On a grayscale monitor you might prefer:
2338
2339 @example
2340 -whitePieceColor       gray100
2341 -blackPieceColor       gray0
2342 -lightSquareColor      gray80
2343 -darkSquareColor       gray60
2344 -highlightSquareColor  gray100
2345 -premoveHighlightColor gray70
2346 -lowTimeWarningColor   gray70
2347 @end example
2348 @item -drag/-xdrag or -animateDragging true/false
2349 @cindex drag, option
2350 @cindex animateDragging, option
2351 Sets the Animate Dragging menu option. @xref{Options Menu}.  Default: true.
2352 @item -animate/-xanimate or -animateMoving true/false
2353 @cindex animate, option
2354 @cindex animateMoving, option
2355 Sets the Animate Moving menu option. @xref{Options Menu}.  Default: true.
2356 @item -animateSpeed n
2357 @cindex -animateSpeed, option
2358 Number of milliseconds delay between each animation frame when Animate
2359 Moves is on.
2360 @item -autoDisplayComment true/false
2361 @itemx -autoDisplayTags true/false
2362 @cindex -autoDisplayComment, option
2363 @cindex -autoDisplayTags, option
2364 If set to true, these options cause the window with the move comments,
2365 and the window with PGN tags, respectively, to pop up automatically when
2366 such tags or comments are encountered during the replaying a stored or
2367 loaded game.  Default: true.
2368 @item -pasteSelection true/false
2369 @cindex -pasteSelection, option
2370 If this option is set to true, the Paste Position and Paste Game
2371 options paste from the currently selected text.  If false, they paste
2372 from the clipboard.  Default: false.
2373 @end table
2374
2375 @node Adjudication Options
2376 @section Adjudication Options
2377 @cindex Options, adjudication
2378 @table @asis
2379 @item -adjudicateLossThreshold n
2380 @cindex adjudicateLossThreshold, option
2381 If the given value is non-zero, XBoard adjudicates the game as a loss 
2382 if both engines agree for a duration of 6 consecutive ply that the score 
2383 is below the given score threshold for that engine. Make sure the score 
2384 is interpreted properly by XBoard, 
2385 using @code{-firstScoreAbs} and @code{-secondScoreAbs} if needed. 
2386 Default: 0 (no adjudication)
2387 @item -adjudicateDrawMoves n
2388 @cindex adjudicateDrawMoves, option
2389 If the given value is non-zero, XBoard adjudicates the game as a draw 
2390 if after the given number of moves it was not yet decided. Default: 0 (no adjudication)
2391 @item -checkMates true/false
2392 @cindex checkMates, option
2393 If this option is set, XBoard detects all checkmates and stalemates, 
2394 and ends the game as soon as they occur. 
2395 Legality-testing must be switched on for this option to work.
2396 Default: true
2397 @item -testClaims true/false
2398 @cindex testClaims, option
2399 If this option is set, XBoard verifies all result claims made by engines, 
2400 and those who send false claims will forfeit the game because of it. 
2401 Legality-testing must be switched on for this option to work. Default: true
2402 @item -materialDraws true/false
2403 @cindex materialDraws, option
2404 If this option is set, XBoard adjudicates games as draws when there is 
2405 no sufficient material left to inflict a checkmate. 
2406 This applies to KBKB with like bishops (any number, actually), and to KBK, KNK and KK. 
2407 Legality-testing must be switched on for this option to work. Default: true
2408 @item -trivialDraws true/false
2409 @cindex trivialDraws, option
2410 If this option is set, XBoard adjudicates games as draws that cannot be 
2411 usually won without opponent cooperation. This applies to KBKB with unlike bishops, 
2412 and to KBKN, KNKN, KNNK, KRKR and KQKQ. The draw is called after 6 ply into these end-games, 
2413 to allow quick mates that can occur in some exceptional positions to be found by the engines. 
2414 KQKQ does not really belong in this category, and might be taken out in the future. 
2415 (When bitbase-based adjudications are implemented.) 
2416 Legality-testing must be on for this option to work. Default: false
2417 @item -ruleMoves n
2418 @cindex ruleMoves, option
2419 If the given value is non-zero, XBoard adjudicates the game as a draw after the given 
2420 number of consecutive reversible moves. Engine draw claims are always accepted after 50 moves, 
2421 irrespective of the given value of n.
2422 @item -repeatsToDraw n
2423 If the given value is non-zero, xboard adjudicates the game as a draw if a position 
2424 is repeated the given number of times. Engines draw claims are always accepted after 3 repeats, 
2425 (on the 3rd occurrence, actually), irrespective of the value of n. 
2426 Beware that positions that have different castling or en-passant rights do not count 
2427 as repeats, XBoard is fully e.p. and castling aware!
2428 @end table
2429
2430 @node Other options
2431 @section Other options
2432 @cindex Options, miscellaneous
2433 @table @asis
2434 @item -ncp/-xncp or -noChessProgram true/false
2435 @cindex ncp, option
2436 @cindex noChessProgram, option
2437 If this option is true, XBoard acts as a passive chessboard; it
2438 does not start a chess engine at all. Turning on this option
2439 also turns off clockMode. Default: false.
2440 @item -mode or -initialMode modename
2441 @cindex mode, option
2442 @cindex initalMode, option
2443 If this option is given, XBoard selects the given modename
2444 from the Mode menu after starting and (if applicable) processing the
2445 loadGameFile or loadPositionFile option. Default: "" (no selection). 
2446 Other supported values are 
2447 MachineWhite, MachineBlack, TwoMachines, Analysis, 
2448 AnalyzeFile, EditGame, EditPosition, and Training.
2449 @item -variant varname
2450 @cindex variant, option
2451 Activates preliminary, partial support for playing chess variants
2452 against a local engine or editing variant games.  This flag is not
2453 needed in ICS mode.  Recognized variant names are:
2454
2455 @example
2456 normal        Normal chess
2457 wildcastle    Shuffle chess, king can castle from d file
2458 nocastle      Shuffle chess, no castling allowed
2459 fischerandom  Fischer Random shuffle chess
2460 bughouse      Bughouse, ICC/FICS rules
2461 crazyhouse    Crazyhouse, ICC/FICS rules
2462 losers        Lose all pieces or get mated (ICC wild 17)
2463 suicide       Lose all pieces including king (FICS)
2464 giveaway      Try to have no legal moves (ICC wild 26)
2465 twokings      Weird ICC wild 9
2466 kriegspiel    Opponent's pieces are invisible
2467 atomic        Capturing piece explodes (ICC wild 27)
2468 3check        Win by giving check 3 times (ICC wild 25)
2469 shatranj      An ancient precursor of chess (ICC wild 28)
2470 xiangqi       Chinese Chess (on a 9x10 board)
2471 shogi         Japanese Chess (on a 9x9 board & piece drops) 
2472 capablanca    Capablanca Chess (10x8 board, with Archbishop 
2473               and Chancellor pieces)
2474 gothic        similar, with a better initial position
2475 caparandom    An FRC-like version of Capablanca Chess (10x8) 
2476 janus         A game with two Archbishops (10x8 board)
2477 courier       Medieval intermediate between shatranj and 
2478               modern Chess (on 12x8 board) 
2479 falcon        Patented 10x8 variant with two Falcon pieces
2480 berolina      Pawns capture straight ahead, and move diagonal 
2481 cylinder      Pieces wrap around the board edge
2482 knightmate    King moves as Knight, and vice versa 
2483 super         Superchess (shuffle variant with 4 exo-pieces)
2484 makruk        Thai Chess (shatranj-like, P promotes on 6th rank)
2485 fairy         A catchall variant in which all piece types 
2486               known to XBoard can participate (8x8)
2487 unknown       Catchall for other unknown variants
2488 @end example
2489
2490 NOT ALL BOARDSIZES PROVIDE A COMPLETE SET OF BUILT-IN BITMAPS FOR ALL
2491 UN-ORTHODOX PIECES, though. Only in @code{boardSize} middling and bulky
2492 all 22 piece types are provided, while -boardSize petite has most
2493 of them. Archbishop, Chancellor and Amazon are supported in every
2494 size from petite to bulky. Kings or Amazons are substituted for
2495 missing bitmaps. You can still play variants needing un-orthodox
2496 pieces in other board sizes providing your own bitmaps through the
2497 @code{bitmapDirectory} or @code{pixmapDirectory} options.
2498
2499 In the shuffle variants, XBoard now does shuffle the pieces, although
2500 you can still do it by hand using Edit Position.  Some variants are
2501 supported only in ICS mode, including bughouse, and
2502 kriegspiel.  The winning/drawing conditions in crazyhouse (off-board
2503 interposition on mate) are not fully understood, but losers, suicide, 
2504 giveaway, atomic, and 3check should be OK.
2505 Berolina and cylinder chess can only be played with legality testing off.
2506 In crazyhouse, XBoard now does keep
2507 track of off-board pieces.  In shatranj it does implement the baring
2508 rule when mate detection is switched on.
2509 @item -boardHeight N
2510 @cindex boardHeight, option
2511 Allows you to set a non-standard number of board ranks in any variant. 
2512 If the height is given as -1, the default height for the variant is used.
2513 Default: -1
2514 @item -boardWidth N
2515 @cindex boardWidth, option
2516 Allows you to set a non-standard number of board files in any variant. 
2517 If the width is given as -1, the default width for the variant is used. 
2518 With a non-standard width, the initial position will always be an empty board, 
2519 as the usual opening array will not fit.
2520 Default: -1
2521 @item -holdingsSize N
2522 @cindex holdingsSize, option
2523 Allows you to set a non-standard size for the holdings in any variant. 
2524 If the size is given as -1, the default holdings size for the variant is used. 
2525 The first N piece types will go into the holdings on capture, and you will be 
2526 able to drop them on the board in stead of making a normal move. If size equals 0, 
2527 there will be no holdings.
2528 Default: -1
2529 @item -defaultFrcPosition N
2530 @cindex defaultFrcPosition, option
2531 Specifies the number of the opening position in shuffle games like Chess960. 
2532 A value of -1 means the position is randomly generated by XBoard
2533 at the beginning of every game.
2534 Default: -1
2535 @item -pieceToSquareTable string
2536 @cindex pieceToSquareTable, option
2537 The characters that are used to represent the piece types XBoard knows in FEN 
2538 diagrams and SAN moves. The string argument has to have an even length 
2539 (or it will be ignored), as white and black pieces have to be given separately 
2540 (in that order). The last letter for each color will be the King. 
2541 The letters before that will be PNBRQ and then a whole host of fairy pieces 
2542 in an order that has not fully crystallized yet (currently FEACWMOHIJGDVSLU, 
2543 F=Ferz, Elephant, A=Archbishop, C=Chancellor, W=Wazir, M=Commoner, O=Cannon, 
2544 H=Nightrider). You should list at least all pieces that occur in the variant 
2545 you are playing. If you have less than 44 characters in the string, the pieces 
2546 not mentioned will get assigned a period, and you will not be able to distinguish 
2547 them in FENs. You can also explicitly assign pieces a period, in which case they 
2548 will not be counted in deciding which captured pieces can go into the holdings.
2549 A tilde '~' as a piece name does mean this piece is used to represent a promoted 
2550 Pawn in crazyhouse-like games, i.e. on capture it turns back onto a Pawn. 
2551 A '+' similarly indicates the piece is a shogi-style promoted piece, that should 
2552 revert to its non-promoted version on capture (rather than to a Pawn).
2553 Note that promoted pieces are represented by pieces 11 further in the list.
2554 You should not have to use this option often: each variant has its own default 
2555 setting for the piece representation in FEN, which should be sufficient in normal use.
2556 Default: ""
2557 @item -debug/-xdebug or -debugMode true/false
2558 @cindex debug, option
2559 @cindex debugMode, option
2560 Turns on debugging printout.
2561 @item -debugFile filename or -nameOfDebugFile filename
2562 @cindex debugFile, option
2563 @cindex nameOfDebugFile, option
2564 Sets the name of the file to which XBoard saves debug information 
2565 (including all communication to and from the engines).
2566 @item -engineDebugOutput number
2567 @cindex engineDebugOutput, option
2568 Specifies how XBoard should handle unsolicited output from the engine, 
2569 with respect to saving it in the debug file. 
2570 The output is further (hopefully) ignored. 
2571 If number=0, XBoard refrains from writing such spurious output to the debug file. 
2572 If number=1, all engine output is written faithfully to the debug file. 
2573 If number=2, any protocol-violating line is prefixed with a '#' character, 
2574 as the engine itself should have done if it wanted to submit info for inclusion in the debug file.
2575 This option is provided for the benefit of applications that use the debug file 
2576 as a source of information, such as the broadcaster of live games TLCV / TLCS. 
2577 Such applications can be protected from spurious engine output that might otherwise confuse them.
2578 @item -rsh or -remoteShell shell-name
2579 @cindex rsh, option
2580 @cindex remoteShell, option
2581 Name of the command used to run programs remotely. The default
2582 is @file{rsh} or @file{remsh}, determined when XBoard is
2583 configured and compiled.
2584 @item -ruser or -remoteUser user-name
2585 @cindex ruser, option
2586 @cindex remoteUser, option
2587 User name on the remote system when running programs with the
2588 @code{remoteShell}. The default is your local user name.
2589 @item -userName username
2590 @cindex userName, option
2591 Name under which the Human player will be listed in the PGN file. 
2592 Default is the login name on your local computer.
2593 @item -delayBeforeQuit number
2594 @itemx -delayAfterQuit number
2595 @cindex delayBeforeQuit, option
2596 @cindex delayAfterQuit, option
2597 These options specify how long XBoard has to wait before sending a termination signal to rogue engine processes, that do not want to react to the 'quit' command. The second one determines the pause after killing the engine, to make sure it dies.
2598
2599 @end table
2600
2601 @node Chess Servers
2602 @chapter Chess Servers
2603 @cindex ICS
2604 @cindex ICS, addresses
2605 @cindex Internet Chess Server
2606 An @dfn{Internet Chess Server}, or @dfn{ICS}, is a place on the
2607 Internet where people can get together to play chess, watch other
2608 people's games, or just chat.  You can use either @code{telnet} or a
2609 client program like XBoard to connect to the server.  There are
2610 thousands of registered users on the different ICS hosts, and it is
2611 not unusual to meet 200 on both chessclub.com and freechess.org.
2612
2613 Most people can just type @kbd{xboard -ics} to start XBoard as an ICS
2614 client.  Invoking XBoard in this way connects you to the Internet
2615 Chess Club (ICC), a commercial ICS.  You can log in there as a guest
2616 even if you do not have a paid account.  To connect to the largest
2617 Free ICS (FICS), use the command @kbd{xboard -ics -icshost freechess.org}
2618 instead, or substitute a different host name to connect to your
2619 favorite ICS.
2620 For a full description of command-line options that control 
2621 the connection to ICS and change the default values of ICS options, see
2622 @ref{ICS options}.  
2623
2624 While you are running XBoard as an ICS client,
2625 you use the terminal window that you started XBoard from
2626 as a place to type in commands and read information that is
2627 not available on the chessboard.
2628
2629 The first time you need to use the terminal is to enter your login name
2630 and password, if you are a registered player. (You don't need to do
2631 this manually; the @code{icsLogon} option can do it for you.
2632 @pxref{ICS options}.)  If you are not registered, 
2633 enter @kbd{g} as your name, and the server will pick a
2634 unique guest name for you.
2635
2636 Some useful ICS commands
2637 include
2638 @table @kbd
2639 @item help <topic>
2640 @cindex help, ICS command
2641 to get help on the given <topic>. To get a list of possible topics type
2642 @dfn{help} without topic.  Try the help command before you ask other
2643 people on the server for help.
2644
2645 For example @kbd{help register} tells you how to become a registered
2646 ICS player.
2647 @item who <flags>
2648 @cindex who, ICS command
2649 to see a list of people who are logged on.  Administrators
2650 (people you should talk to if you have a problem) are marked
2651 with the character @samp{*}, an asterisk. The <flags> allow you to
2652 display only selected players: For example, @kbd{who of} shows a
2653 list of players who are interested in playing but do not have
2654 an opponent.
2655 @item games
2656 @cindex games, ICS command
2657 to see what games are being played
2658 @item match <player> [<mins>] [<inc>]
2659 to challenge another player to a game. Both opponents get <mins> minutes
2660 for the game, and <inc> seconds will be added after each move.
2661 If another player challenges you, the server asks if you want to
2662 accept the challenge; use the @kbd{accept} or @kbd{decline} commands
2663 to answer.
2664 @item accept
2665 @itemx decline
2666 @cindex accept, ICS command
2667 @cindex decline, ICS command
2668 to accept or decline another player's offer. 
2669 The offer may be to start a new game, or to agree to a 
2670 @kbd{draw}, @kbd{adjourn} or @kbd{abort} the current game. @xref{Action Menu}.
2671
2672 If you have more than one pending offer (for example, if more than one player
2673 is challenging you, or if your opponent offers both a draw and to adjourn the
2674 game), you have to supply additional information, by typing something
2675 like @kbd{accept <player>}, @kbd{accept draw}, or @kbd{draw}.
2676 @item draw
2677 @itemx adjourn
2678 @itemx abort
2679 @cindex draw, ICS command
2680 @cindex adjourn, ICS command
2681 @cindex abort, ICS command
2682 asks your opponent to terminate a game by mutual agreement. Adjourned
2683 games can be continued later. 
2684 Your opponent can either @kbd{decline} your offer or accept it (by typing the
2685 same command or typing @kbd{accept}).  In some cases these commands work
2686 immediately, without asking your opponent to agree.  For example, you can
2687 abort the game unilaterally if your opponent is out of time, and you can claim
2688 a draw by repetition or the 50-move rule if available simply by typing 
2689 @kbd{draw}.
2690 @item finger <player>
2691 @cindex finger, ICS command
2692 to get information about the given <player>. (Default: yourself.)
2693 @item vars
2694 @cindex vars, ICS command
2695 to get a list of personal settings
2696 @item set <var> <value>
2697 @cindex set, ICS command
2698 to modify these settings
2699 @item observe <player>
2700 @cindex observe, ICS command
2701 to observe an ongoing game of the given <player>.
2702 @item examine
2703 @itemx oldmoves
2704 @cindex examine, ICS command
2705 @cindex oldmoves, ICS command
2706 to review a recently completed game
2707 @end table
2708
2709 Some special XBoard features are activated when you are
2710 in examine mode on ICS.  See the descriptions of the menu commands
2711 @samp{Forward}, @samp{Backward}, @samp{Pause}, @samp{ICS Client}, 
2712 and @samp{Stop Examining} on the @ref{Step Menu}, @ref{Mode Menu}, and
2713 @ref{Options Menu}.
2714
2715 @node Firewalls
2716 @chapter Firewalls
2717 By default, XBoard communicates with an Internet Chess Server
2718 by opening a TCP socket directly from the machine it is running on
2719 to the ICS. If there is a firewall between your machine and the ICS,
2720 this won't work. Here are some recipes for getting around common
2721 kinds of firewalls using special options to XBoard.
2722 Important: See the paragraph in the below about extra echoes, in
2723 @ref{Limitations}.
2724
2725 Suppose that you can't telnet directly to ICS, but you can telnet
2726 to a firewall host, log in, and then telnet from there to ICS.
2727 Let's say the firewall is called @samp{firewall.example.com}. Set
2728 command-line options as follows:
2729
2730 @example
2731 xboard -ics -icshost firewall.example.com -icsport 23
2732 @end example
2733 @noindent
2734 Or in your @file{.Xresources} file:
2735
2736 @example
2737 XBoard*internetChessServerHost: firewall.example.com
2738 XBoard*internetChessServerPort: 23
2739 @end example
2740 @noindent
2741 Then when you run XBoard in ICS mode, you will be prompted
2742 to log in to the firewall host. This works because port 23 is the
2743 standard telnet login service. Do so, then telnet to ICS, using a
2744 command like @samp{telnet chessclub.com 5000}, or whatever command
2745 the firewall provides for telnetting to port 5000.
2746
2747 If your firewall lets you telnet (or rlogin) to remote hosts but
2748 doesn't let you telnet to port 5000, you may be able to connect to the
2749 chess server on port 23 instead, which is the port the telnet program
2750 uses by default.  Some chess servers support this (including
2751 chessclub.com and freechess.org), while some do not.
2752
2753 If your chess server does not allow connections on port 23 and your
2754 firewall does not allow you to connect to other ports, you may be able
2755 to connect by hopping through another host outside the firewall that
2756 you have an account on.  For instance, suppose you have a shell
2757 account at @samp{foo.edu}. Follow the recipe above, but instead of
2758 typing @samp{telnet chessclub.com 5000} to the firewall, type
2759 @samp{telnet foo.edu} (or @samp{rlogin foo.edu}), log in there, and
2760 then type @samp{telnet chessclub.com 5000}.
2761
2762 Suppose that you can't telnet directly to ICS, but you can use rsh
2763 to run programs on a firewall host, and that host can telnet to ICS.
2764 Let's say the firewall is called @samp{rsh.example.com}. Set
2765 command-line options as follows:
2766
2767 @example
2768 xboard -ics -gateway rsh.example.com -icshost chessclub.com
2769 @end example
2770
2771 @noindent
2772 Or in your @file{.Xresources} file:
2773
2774 @example
2775 XBoard*gateway: rsh.example.com
2776 XBoard*internetChessServerHost: chessclub.com
2777 @end example
2778
2779 Then when you run XBoard in ICS mode, it will connect to
2780 the ICS by using @file{rsh} to run the command
2781 @samp{telnet chessclub.com 5000} on host @samp{rsh.example.com}.
2782
2783 Suppose that you can telnet anywhere you want, but you have to
2784 run a special program called @file{ptelnet} to do so.
2785
2786 First, we'll consider the easy case, in which
2787 @samp{ptelnet chessclub.com 5000} gets you to the chess server.
2788 In this case set command line options as follows:
2789
2790 @example
2791 xboard -ics -telnet -telnetProgram ptelnet
2792 @end example
2793
2794 @noindent
2795 Or in your @file{.Xresources} file:
2796
2797 @example
2798 XBoard*useTelnet: true
2799 XBoard*telnetProgram: ptelnet
2800 @end example
2801
2802 @noindent
2803 Then when you run XBoard in ICS mode, it will issue the
2804 command @samp{ptelnet chessclub.com 5000} to connect to the ICS.
2805
2806 Next, suppose that @samp{ptelnet chessclub.com 5000} doesn't work;
2807 that is, your @file{ptelnet} program doesn't let you connect to
2808 alternative ports. As noted above, your chess server may allow you to
2809 connect on port 23 instead.  In that case, just add the option
2810 @samp{-icsport ""} to the above command, or add
2811 @samp{XBoard*internetChessServerPort:} to your @file{.Xresources} file.
2812 But if your chess server doesn't let you connect on port 23, you will have
2813 to find some other host outside the firewall and hop through it. For
2814 instance, suppose you have a shell account at @samp{foo.edu}. Set
2815 command line options as follows:
2816
2817 @example
2818 xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport ""
2819 @end example
2820
2821 @noindent
2822 Or in your @file{.Xresources} file:
2823
2824 @example
2825 XBoard*useTelnet: true
2826 XBoard*telnetProgram: ptelnet
2827 XBoard*internetChessServerHost: foo.edu
2828 XBoard*internetChessServerPort:
2829 @end example
2830
2831 @noindent
2832 Then when you run XBoard in ICS mode, it will issue the
2833 command @samp{ptelnet foo.edu} to connect to your account at
2834 @samp{foo.edu}. Log in there, then type @samp{telnet chessclub.com 5000}.
2835
2836 ICC timestamp and FICS timeseal do not work through some
2837 firewalls.  You can use them only if your firewall gives a clean TCP
2838 connection with a full 8-bit wide path.  If your firewall allows you
2839 to get out only by running a special telnet program, you can't use
2840 timestamp or timeseal across it.  But if you have access to a
2841 computer just outside your firewall, and you have much lower netlag
2842 when talking to that computer than to the ICS, it might be worthwhile
2843 running timestamp there.  Follow the instructions above for hopping
2844 through a host outside the firewall (foo.edu in the example),
2845 but run timestamp or timeseal on that host instead of telnet.
2846
2847 Suppose that you have a SOCKS firewall that will give you a clean
2848 8-bit wide TCP connection to the chess server, but only after you
2849 authenticate yourself via the SOCKS protocol.  In that case, you could
2850 make a socksified version of XBoard and run that.  If you are using
2851 timestamp or timeseal, you will to socksify it, not XBoard; this may
2852 be difficult seeing that ICC and FICS do not provide source code for
2853 these programs.  Socksification is beyond the scope of this document,
2854 but see the SOCKS Web site at http://www.socks.permeo.com/.
2855 If you are missing SOCKS, try http://www.funbureau.com/.
2856
2857 @node Environment
2858 @chapter Environment variables
2859 @cindex Environment variables
2860 @cindex CHESSDIR
2861 Game and position files are found in a directory named by the
2862 @code{CHESSDIR} environment variable. If this variable is not set, the
2863 current working directory is used. If @code{CHESSDIR} is set,
2864 XBoard actually changes its working directory to
2865 @code{$CHESSDIR}, so any files written by the chess engine
2866 will be placed there too.
2867
2868 @node Limitations
2869 @chapter Limitations and known bugs
2870 @cindex Limitations
2871 @cindex Bugs
2872 There is no way for two people running copies of XBoard to play
2873 each other without going through an Internet Chess Server.
2874
2875 Under some circumstances, your ICS password may be echoed when you log on.
2876
2877 If you are connecting to the ICS by running telnet on an Internet
2878 provider or firewall host, you may find that each line you type is
2879 echoed back an extra time after you hit @key{Enter}. If your Internet
2880 provider is a Unix system, you can probably turn its echo off by
2881 typing @kbd{stty -echo} after you log in, and/or typing
2882 @key{^E}@key{Enter} (Ctrl+E followed by the Enter key) to the telnet
2883 program after you have logged into ICS.  It is a good idea to do this
2884 if you can, because the extra echo can occasionally confuse XBoard's
2885 parsing routines.
2886
2887 The game parser recognizes only algebraic notation.
2888
2889 Many of the following points used to be limitations in XBoard 4.2.7 and earlier, 
2890 but are now fixed:
2891 The internal move legality tester in XBoard 4.3.xx does look at the game history, 
2892 and is fully aware of castling or en-passant-capture rights. It permits castling with 
2893 the king on the d file because this is possible in some "wild 1" games on ICS. 
2894 The piece-drop menu does not check piece drops in bughouse to see if you actually hold 
2895 the piece you are trying to drop. But this way of dropping pieces should be considered 
2896 an obsolete feature, now that pieces can be dropped by dragging them from the holdings 
2897 to the board. Anyway, if you would attempt an illegal move when using a chess engine or the ICS, 
2898 XBoard will accept the error message that comes back, undo the move, and let you try another.
2899 FEN positions saved by XBoard do include correct information about whether castling or 
2900 en passant are legal, and also handle the 50-move counter.
2901 The mate detector does not understand that non-contact mate is not really mate in bughouse. 
2902 The only problem this causes while playing is minor: a "#" (mate indicator) character will 
2903 show up after a non-contact mating move in the move list. XBoard will not assume the game 
2904 is over at that point, not even when the option Detect Mates is on.
2905 Edit Game mode always uses the rules of the selected variant, 
2906 which can be a variant that uses piece drops.  
2907 You can load and edit games that contain piece drops. 
2908 The (obsolete) piece menus are not active, 
2909 but you can perform piece drops by dragging pieces from the holdings.
2910 Edit Position mode does not allow you to edit the crazyhouse holdings properly. 
2911 You cannot drag pieces to the holding, and using the popup menu to put pieces 
2912 there does not adapt the holding counts and leads to an inconsistent state. 
2913 Set up crazyhouse positions by loading / pasting a bFEN, from there you can set the holdings.
2914 Fischer Random castling is fully understood. 
2915 You can enter castlings by dragging the King on top of your Rook. 
2916 You can probably also play Fischer Random successfully on ICS by typing 
2917 castling moves into the ICS Interaction window.
2918
2919 The menus may not work if your keyboard is in Caps Lock or Num Lock mode.
2920 This seems to be a problem with the Athena menu widget,
2921 not an XBoard bug.
2922
2923 Also see the ToDo file included with the distribution for many other
2924 possible bugs, limitations, and ideas for improvement that have been
2925 suggested.
2926 @node Problems
2927 @chapter Reporting problems
2928 @cindex Bugs
2929 @cindex Bug reports
2930 @cindex Reporting bugs
2931 @cindex Problems
2932 @cindex Reporting problems
2933
2934 You can report bugs and problems with XBoard using
2935 the bug tracker at @code{https://savannah.gnu.org/projects/xboard/}
2936 or by sending mail to @code{<bug-xboard@@gnu.org>}.  It can also
2937 be useful to report or discuss bugs in the WinBoard Forum at
2938 @code{http://www.open-aurec.com/wbforum/}, 
2939 WinBoard development section.
2940
2941 Please use the @file{script} program to start a typescript, run 
2942 XBoard with the @samp{-debug} option, and include the typescript
2943 output in your message.
2944 Also tell us what kind of machine and what operating system version
2945 you are using.  The command @samp{uname -a} will often tell you this.
2946
2947 If you improve XBoard, please send a message about your changes,
2948 and we will get in touch with you about merging them in
2949 to the main line of development.
2950
2951 @node Contributors
2952 @chapter Authors and contributors
2953 @cindex Authors
2954 @cindex Contributors
2955
2956 Chris Sears and Dan Sears wrote the original XBoard.  They were
2957 responsible for versions 1.0 through 1.2.  The color scheme was taken
2958 from Wayne Christopher's @code{XChess} program.
2959
2960 Tim Mann was primarily responsible for XBoard versions 1.3 through
2961 4.2.7, and for WinBoard (a port of XBoard to Microsoft Win32) from its
2962 inception through version 4.2.7.
2963
2964 John Chanak contributed the initial implementation of ICS mode.  Evan
2965 Welsh wrote @code{CMail}, and Patrick Surry helped in designing,
2966 testing, and documenting it.  Elmar Bartel contributed the new piece
2967 bitmaps introduced in version 3.2.  Jochen Wiedmann converted the
2968 documentation to texinfo.  Frank McIngvale added click/click moving,
2969 the Analysis modes, piece flashing, ZIICS import, and ICS text
2970 colorization to XBoard.  Hugh Fisher added animated piece movement to
2971 XBoard, and Henrik Gram added it to WinBoard.  Mark Williams
2972 contributed the initial (WinBoard-only) implementation of many new
2973 features added to both XBoard and WinBoard in version 4.1.0, including
2974 copy/paste, premove, icsAlarm, autoFlipView, training mode, auto
2975 raise, and blindfold.  Ben Nye contributed X copy/paste code for
2976 XBoard.
2977
2978 In a fork from version 4.2.7, Alessandro Scotti added many elements to
2979 the user interface of WinBoard, including the board textures and
2980 font-based rendering, the evaluation-graph, move-history and
2981 engine-output window.  He was also responsible for adding the UCI
2982 support.
2983
2984 H. G. Muller continued this fork of the project, producing version
2985 4.3.  He made WinBoard castling- and e.p.-aware, added variant support
2986 with adjustable board sizes, the crazyhouse holdings, and the fairy
2987 pieces.  In addition he added most of the adjudication options, made
2988 WinBoard more robust in dealing with buggy and crashing engines, and
2989 extended time control with a time-odds and node-count-based modes.
2990 Most of the options that initially were WinBoard only have now been
2991 back-ported to XBoard.
2992
2993 Michel van den Bergh provided the code for reading Polyglot opening books.
2994
2995 Meanwhile, some work continued on the GNU XBoard project maintained at
2996 savannah.gnu.org, but version 4.2.8 was never released.  Daniel
2997 Mehrmann was responsible for much of this work.
2998
2999 Most recently, Arun Persaud worked with H. G. Muller to merge all
3000 the features of the never-released XBoard/WinBoard 4.2.8 of the GNU
3001 XBoard project and the never-released 4.3.16 from H. G.'s fork into a
3002 unified XBoard/WinBoard 4.4, which is now available both from the
3003 savannah.gnu.org web site and the WinBoard forum.
3004
3005 @node CMail
3006 @chapter CMail
3007 @cindex cmail
3008 The @file{cmail} program can help you play chess by email with opponents of
3009 your choice using XBoard as an interface.
3010
3011 You will usually run @file{cmail} without giving any options.
3012
3013 @menu
3014 * CMail options::    Invoking CMail.
3015 * CMail game::       Starting a CMail game.
3016 * CMail answer::     Answering a move.
3017 * CMail multi::      Multiple games in one message.
3018 * CMail completion:: Completing a game.
3019 * CMail trouble::    Known CMail problems.
3020 @end menu
3021
3022 @node CMail options
3023 @section CMail options
3024 @table @asis
3025 @item -h
3026 Displays @file{cmail} usage information.
3027 @item -c
3028 Shows the conditions of the GNU General Public License.
3029 @xref{Copying}.
3030 @item -w
3031 Shows the warranty notice of the GNU General Public License.
3032 @xref{Copying}.
3033 @item -v
3034 @itemx -xv
3035 Provides or inhibits verbose output from @file{cmail} and XBoard,
3036 useful for debugging. The
3037 @code{-xv}
3038 form also inhibits the cmail introduction message.
3039 @item -mail
3040 @itemx -xmail
3041 Invokes or inhibits the sending of a mail message containing the move.
3042 @item -xboard
3043 @itemx -xxboard
3044 Invokes or inhibits the running of XBoard on the game file.
3045 @item -reuse
3046 @itemx -xreuse
3047 Invokes or inhibits the reuse of an existing XBoard to display the
3048 current game.
3049 @item -remail
3050 Resends the last mail message for that game. This inhibits running
3051 XBoard.
3052 @item -game <name>
3053 The name of the game to be processed.
3054 @item -wgames <number>
3055 @itemx -bgames <number>
3056 @itemx -games <number>
3057 Number of games to start as White, as Black or in total. Default is 1 as
3058 white and none as black. If only one color is specified then none of the
3059 other color is assumed. If no color is specified then equal numbers of
3060 White and Black games are started, with the extra game being as White if an
3061 odd number of total games is specified.
3062 @item -me <short name>
3063 @itemx -opp <short name>
3064 A one-word alias for yourself or your opponent.
3065 @item -wname <full name>
3066 @itemx -bname <full name>
3067 @itemx -name <full name>
3068 @itemx -oppname <full name>
3069 The full name of White, Black, yourself or your opponent.
3070 @item -wna <net address>
3071 @itemx -bna <net address>
3072 @itemx -na <net address>
3073 @itemx -oppna <net address>
3074 The email address of White, Black, yourself or your opponent.
3075 @item -dir <directory>
3076 The directory in which @file{cmail} keeps its files. This defaults to the
3077 environment variable @code{$CMAIL_DIR} or failing that, @code{$CHESSDIR},
3078 @file{$HOME/Chess} or @file{~/Chess}. It will be created if it does not exist.
3079 @item -arcdir <directory>
3080 The directory in which @file{cmail} archives completed games. Defaults to
3081 the environment variable @code{$CMAIL_ARCDIR} or, in its absence, the same
3082 directory as cmail keeps its working files (above).
3083 @item -mailprog <mail program>
3084 The program used by cmail to send email messages. This defaults to the
3085 environment variable @code{$CMAIL_MAILPROG} or failing that
3086 @file{/usr/ucb/Mail}, @file{/usr/ucb/mail} or @file{Mail}. You will need
3087 to set this variable if none of the above paths fit your system.
3088 @item -logFile <file>
3089 A file in which to dump verbose debugging messages that are invoked with
3090 the @samp{-v}
3091 option.
3092 @item -event <event>
3093 The PGN Event tag (default @samp{Email correspondence game}).
3094 @item -site <site>
3095 The PGN Site tag (default @samp{NET}).
3096 @item -round <round>
3097 The PGN Round tag (default @samp{-}, not applicable).
3098 @item -mode <mode>
3099 The PGN Mode tag (default @samp{EM}, Electronic Mail).
3100 @item Other options
3101 Any option flags not listed above are passed through to XBoard.
3102 Invoking XBoard through CMail changes the default values of two XBoard
3103 options: The default value for @samp{-noChessProgram} is changed to
3104 true; that is, by default no chess engine is started.  The default
3105 value for @samp{-timeDelay} is changed to 0; that is, by default
3106 XBoard immediately goes to the end of the game as played so far,
3107 rather than stepping through the moves one by one.  You can still set
3108 these options to whatever values you prefer by supplying them on
3109 CMail's command line.  @xref{Options}.
3110 @end table
3111
3112 @node CMail game
3113 @section Starting a CMail Game
3114 Type @file{cmail} from a shell to start a game as white. After an opening
3115 message, you will be prompted for a game name, which is optional---if you
3116 simply press @key{Enter}, the game name will take the form
3117 @samp{you-VS-opponent}. You will next be prompted for the short name
3118 of your opponent. If you haven't played this person before, you will also
3119 be prompted for his/her email address. @file{cmail} will then invoke
3120 XBoard in the background. Make your first move and select
3121 @samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. If all is well,
3122 @file{cmail} will mail a copy of the move to your opponent. If you select
3123 @samp{Exit} without having selected @samp{Mail Move} then no move will be
3124 made.
3125
3126 @node CMail answer
3127 @section Answering a Move
3128 When you receive a message from an opponent containing a move in one of
3129 your games, simply pipe the message through @file{cmail}. In some mailers
3130 this is as simple as typing @kbd{| cmail} when viewing the message, while in
3131 others you may have to save the message to a file and do @kbd{cmail < file}
3132 at the command line. In either case @file{cmail} will display the game using
3133 XBoard. If you didn't exit XBoard when you made your first move
3134 then @file{cmail} will do its best to use the existing XBoard instead
3135 of starting a new one. As before, simply make a move and select
3136 @samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. @file{cmail}
3137 will try to use the
3138 XBoard that was most recently used to display the current game. This
3139 means that many games can be in progress simultaneously, each with its own
3140 active XBoard.
3141
3142 If you want to look at the history or explore a variation, go ahead, but
3143 you must return to the current position before XBoard will allow you
3144 to mail a move. If you edit the game's history you must select
3145 @samp{Reload Same Game} from the @samp{File} menu to get back to the original
3146 position, then make the move you want and select @samp{Mail Move}.
3147 As before, if you decide you aren't ready to make a move just yet you can
3148 either select @samp{Exit} without sending a move or just leave
3149 XBoard running until you are ready.
3150
3151 @node CMail multi
3152 @section Multi-Game Messages
3153
3154 It is possible to have a @file{cmail} message carry more than one game.
3155 This feature was implemented to handle IECG (International Email Chess
3156 Group) matches, where a match consists of one game as white and one as black,
3157 with moves transmitted simultaneously. In case there are more general uses,
3158 @file{cmail} itself places no limit on the number of black/white games
3159 contained in a message; however, XBoard does.
3160
3161 @node CMail completion
3162 @section Completing a Game
3163 Because XBoard can detect checkmate and stalemate, @file{cmail}
3164 handles game termination sensibly. As well as resignation, the
3165 @samp{Action} menu allows draws to be offered and accepted for
3166 @file{cmail} games.
3167
3168 For multi-game messages, only unfinished and just-finished games will be
3169 included in email messages. When all the games are finished, they are
3170 archived in the user's archive directory, and similarly in the opponent's
3171 when he or she pipes the final message through @file{cmail}. The archive
3172 file name includes the date the game was started.
3173
3174 @node CMail trouble
3175 @section Known CMail Problems
3176 It's possible that a strange conjunction of conditions may occasionally
3177 mean that @file{cmail} has trouble reactivating an existing
3178 XBoard. If this should happen, simply trying it again should work.
3179 If not, remove the file that stores the XBoard's PID
3180 (@file{game.pid}) or use the @samp{-xreuse} option to force
3181 @file{cmail} to start a new XBoard.
3182
3183 Versions of @file{cmail} after 2.16 no longer understand the old file format
3184 that XBoard used to use and so cannot be used to correspond with
3185 anyone using an older version.
3186
3187 Versions of @file{cmail} older than 2.11 do not handle multi-game messages,
3188 so multi-game correspondence is not possible with opponents using an older
3189 version.
3190
3191 @node Other programs
3192 @chapter Other programs you can use with XBoard
3193 @cindex Other programs
3194
3195 Here are some other programs you can use with XBoard
3196
3197 @menu
3198 * GNU Chess::        The GNU Chess engine.
3199 * Fairy-Max::        The Fairy-Max chess engine.
3200 * HoiChess::         The HoiChess chess engine.
3201 * Crafty::           The Crafty chess engine.
3202 * zic2xpm::          The program used to import chess sets from ZIICS.
3203 @end menu
3204
3205 @node GNU Chess
3206 @section GNU Chess
3207
3208 The GNU Chess engine is available from:
3209
3210 ftp://ftp.gnu.org/gnu/gnuchess/
3211
3212 You can use XBoard to play a game against GNU Chess, or to
3213 interface GNU Chess to an ICS.
3214
3215 @node Fairy-Max
3216 @section Fairy-Max
3217
3218 Fairy-Max is a derivative from the once World's smallest Chess program micro-Max,
3219 which measures only about 100 lines of source code.
3220 The main difference with micro-Max is that Fairy-Max loads its move-generator
3221 tables from a file, so that the rules for piece movement can be easily configured
3222 to implement unorthodox pieces.
3223 Fairy-Max can therefore play a large number of variants, normal Chess being one of those.
3224 In addition it plays Knightmate, Capablanca and Gothic Chess, Shatranj, Courier Chess,
3225 Cylinder chess, Berolina Chess, while the user can easily define new variants.
3226 It can be obtained from:
3227
3228 http://home.hccnet.nl/h.g.muller/dwnldpage.html
3229
3230 @node HoiChess
3231 @section HoiChess
3232
3233 HoiChess is a not-so-very-strong Chess engine, which comes with a derivative HoiXiangqi,
3234 able to play Chinese Chess. It can be obtained from the standard Linux repositories
3235 through:
3236
3237 sudo apt-get install hoichess
3238
3239 @node Crafty
3240 @section Crafty
3241
3242 Crafty is a chess engine written by Bob Hyatt.
3243 You can use XBoard to play a game against Crafty, hook Crafty up
3244 to an ICS, or use Crafty to interactively analyze games and positions
3245 for you.
3246
3247 Crafty is a strong, rapidly evolving chess program. This rapid
3248 pace of development is good, because it means Crafty is always
3249 getting better.  This can sometimes cause problems with
3250 backwards compatibility, but usually the latest version of Crafty
3251 will work well with the latest version of XBoard.
3252 Crafty can be obtained from its author's FTP site:
3253 ftp://ftp.cis.uab.edu/hyatt/.
3254
3255 To use Crafty with XBoard, give the -fcp and -fd options as follows, where
3256 <crafty's directory> is the directory in which you installed Crafty
3257 and placed its book and other support files.
3258
3259 @node zic2xpm
3260 @section zic2xpm
3261
3262 The ``zic2xpm'' program is used to import chess sets from the ZIICS(*)
3263 program into XBoard. ``zic2xpm'' is part of the XBoard distribution.
3264 ZIICS is available from:
3265
3266 ftp://ftp.freechess.org/pub/chess/DOS/ziics131.exe
3267
3268 To import ZIICS pieces, do this:
3269 @table @asis
3270 @item 1. Unzip ziics131.exe into a directory:
3271
3272 @example
3273 unzip -L ziics131.exe -d ~/ziics
3274 @end example
3275 @item 2. Use zic2xpm to convert a set of pieces to XBoard format.
3276
3277 For example, let's say you want to use the
3278 FRITZ4 set. These files are named ``fritz4.*'' in the ZIICS distribution.
3279
3280 @example
3281 mkdir ~/fritz4
3282 cd ~/fritz4
3283 zic2xpm ~/ziics/fritz4.*
3284 @end example
3285 @item 3. Give XBoard the ``-pixmap'' option when starting up, e.g.:
3286
3287 @example
3288 xboard -pixmap ~/fritz4
3289 @end example
3290
3291 Alternatively, you can add this line to your @file{.Xresources} file:
3292
3293 @example
3294 xboard*pixmapDirectory: ~/fritz4
3295 @end example
3296 @end table
3297
3298 (*) ZIICS is a separate copyrighted work of Andy McFarland.
3299 The ``ZIICS pieces'' are copyrighted works of their respective
3300 creators. Files produced by ``zic2xpm'' are for PERSONAL USE ONLY
3301 and may NOT be redistributed without explicit permission from
3302 the original creator(s) of the pieces.
3303
3304 @ifnottex
3305 @node Copyright
3306 @unnumbered Copyright
3307 @include copyright.texi
3308 @end ifnottex
3309
3310 @node Copying
3311 @unnumbered GNU GENERAL PUBLIC LICENSE
3312 @include gpl.texinfo
3313
3314 @c noman
3315 @node Index
3316 @unnumbered Index
3317
3318 @printindex cp
3319 @contents
3320 @c end noman
3321
3322 @bye