2 .TH xboard 6 "$Date$" "GNU"
5 xboard \- X user interface for GNU Chess, Crafty, the Internet Chess Server (ICS),
6 and electronic mail correspondence chess.
13 .B xboard -fcp crafty -fd \fIcrafty's-directory\fB [options]
16 .B xboard -ics -icshost hostname [options]
18 To play email chess: See
22 .B xboard -ncp [options]
29 is a graphical chessboard that can serve as a
30 user interface to the GNU Chess and Crafty chess engines, the
31 Internet Chess Servers,
32 electronic mail correspondence chess, or your own collection of saved games.
34 As an interface to GNU Chess or Crafty,
36 lets you play a game against the machine,
37 set up arbitrary positions,
38 force variations, or watch
39 a game between two machines.
41 As an interface to Crafty,
43 also lets you interactively analyze your stored games
44 or set up and analyze arbitrary positions.
46 As an interface to the Internet Chess Server (ICS),
48 lets you play against other ICS users,
49 observe games they are playing, or review
50 games that have recently finished.
51 Most of the "wild" chess variants on ICS are supported,
54 As an interface to electronic mail correspondence chess,
58 program. See its manual page for instructions.
62 as a chessboard to play through games.
63 It will read and write game files and allow you to play
64 through variations manually.
65 You can use it to browse games off the net
66 or review games you have saved.
67 These features are available at all times; if you want to use
68 them without starting a chess engine or connecting to the ICS,
69 you can do so with the command
72 To view games from a netnews reader like
76 use the news reader's Save command and specify "|pxboard"
78 file name. This pipes the article to
80 a simple shell script that saves the article to a temporary file and runs
82 in the background. See the script itself for more information.
84 To move a piece, either drag it with the left mouse button,
85 or click the left mouse button once on the piece, then once more on
86 the destination square.
87 To drop a new piece on a square (when applicable),
88 press button 2 or 3 over the square and select from the popup menu.
92 is iconized, its graphical icon is a white knight if it is White's turn to
93 move, a black knight if it is Black's turn. See
95 below if you have problems getting this feature to work.
96 .SH MENU COMMANDS, BUTTONS, AND KEYS
100 commands are available on menus. The most frequently used
101 commands also have shortcut keys or on-screen buttons.
107 and the chess engine to the beginning of a new chess game.
108 The "r" key is a keyboard equivalent.
109 In Internet Chess Server mode, clears the current state of
111 then resynchronizes with ICS by sending a
114 If you want to stop playing, observing, or examining a game
115 on ICS, use an appropriate command from the
116 Action menu, not Reset.
119 Plays a game from a record file.
120 The "g" key is a keyboard equivalent.
121 A popup dialog prompts you for the file name.
122 If the file contains more than one game, a second popup dialog displays
123 a list of games (with information drawn from their PGN tags, if any), and you
124 can select the one you want.
125 Alternatively, you can load the
127 game in the file directly from the file name dialog, by typing the number
129 after the file name, separated by a space.
131 The game file parser will accept PGN (portable game notation), or
132 in fact almost any file that contains moves in algebraic notation.
133 Notation of the form "P@f7" is accepted for piece-drops in bughouse games;
134 this is a nonstandard extension to PGN.
135 If the file includes a PGN position (FEN tag), or an old-style
138 bracketed by "[--" and "--]" before the
139 first move, the game starts from that position.
140 Text enclosed in parentheses, square brackets, or curly braces
141 is assumed to be commentary and is displayed in a pop-up window.
142 Any other text in the file is ignored. PGN variations (enclosed in
143 parentheses) are treated as comments;
145 is not able to walk variation trees.
146 The nonstandard PGN tag [Variant "varname"] functions similarly to
147 the -variant command-line option (see below), allowing games in certain chess
148 variants to be loaded. There is also a heuristic to
149 recognize chess variants from the Event tag, by looking for the strings
150 that the Internet Chess Servers put there when saving variant ("wild") games.
153 Loads the next game from the last game record file you loaded.
154 The shifted "N" key is a keyboard equivalent.
156 .B Load Previous Game
157 Loads the previous game from the last game record file you loaded.
158 The shifted "P" key is a keyboard equivalent.
159 Not available if the last game was loaded from a pipe.
162 Reloads the last game you loaded.
163 Not available if the last game was loaded from a pipe.
166 Appends a record of the current game to a file.
167 A popup dialog prompts you for the file name.
168 If the game did not begin with the standard starting position,
169 the game file includes the starting position used.
170 Games are saved in the PGN (portable game notation) format,
171 unless the oldSaveStyle option is
172 True, in which case they are saved in an older format that is specific to
174 Both formats are human-readable, and both can be read back by the Load Game
176 Notation of the form "P@f7" is generated for piece-drops in bughouse games;
177 this is a nonstandard extension to PGN.
180 Copies a record of the current game to an internal clipboard in PGN
181 format and sets the X selection to the game text. The game can be
182 pasted to another application (such as a text editor or another copy
183 of xboard) using that application's paste command. In many X
184 applications, such as xterm and emacs, the middle mouse button can be
185 used for pasting; in xboard, you must use the Paste Game command.
188 Interprets the current X selection as a game record and loads it, as
192 Sets up a position from a position file.
193 A popup dialog prompts you for the file name.
194 If the file contains more than one saved position, and you want
199 after the file name, separated by a space.
200 Position files must be in FEN (Forsythe-Edwards notation), or in the format
201 that the Save Position command writes when oldSaveStyle is turned on.
203 .B Load Next Position
204 Loads the next position from the last position file you loaded.
206 .B Load Previous Position
207 Loads the previous position from the last position file you loaded.
208 Not available if the last position was loaded from a pipe.
210 .B Reload Same Position
211 Reloads the last position you loaded.
212 Not available if the last position was loaded from a pipe.
215 Appends a diagram of the current position to a file.
216 A popup dialog prompts you for the file name.
217 Positions are saved in FEN (Forsythe-Edwards notation) format unless
218 the oldSaveStyle option is True, in which case they are saved in an older,
219 human-readable format that is specific to
221 Both formats can be read back by the Load Position command.
224 Copies the current position to an internal clipboard in FEN format and
225 sets the X selection to the position text. The position can be pasted
226 to another application (such as a text editor or another copy of
227 xboard) using that application's paste command. In many X
228 applications, such as xterm and emacs, the middle mouse button can be
229 used for pasting; in xboard, you must use the Paste Position command.
232 Interprets the current X selection as a FEN position and loads it, as
238 .B Reload CMail Message
239 See the manual page for
246 The shifted "Q" key is a keyboard equivalent.
250 Tells the chess engine to play White.
253 Tells the chess engine to play Black.
256 Plays a game between two chess engines.
259 Puts XBoard in analysis mode on the current edited position or game.
260 This mode requires that you use a chess engine that supports analysis,
261 such as Crafty; GNU Chess will not work.
262 See the manual section
264 for more information on getting and installing Crafty.
267 This mode lets you load a game from a file (PGN, etc.) and use a chess engine
268 to interactively analyze it.
269 This mode requires that you use a chess engine that supports analysis,
270 such as Crafty; GNU Chess will not work.
271 See the manual section
273 for more information on getting and installing Crafty.
276 This is the normal mode when
278 is connected to a chess server. If you have moved into
279 Edit Game or Edit Position mode, you can select this option to get out.
281 To use xboard in ICS mode, run it in the foreground with the -ics
283 terminal you started it from to type commands and receive text responses
284 from the chess server. Useful ICS commands include
286 to see who is logged on,
288 to see what games are being played,
290 to challenge another player to a game,
292 to observe an ongoing game,
296 to review a recently completed game,
302 features are activated when you are in
306 mode on ICS. See the descriptions of the menu commands
307 Forward, Backward, Pause, ICS Client, and Stop Examining below.
308 You can also issue the ICS position-editing commands with the mouse.
309 Move pieces by dragging with mouse button 1.
310 To drop a new piece on a square, press mouse button 2 or 3
311 over the square. This brings up a menu of white pieces (button 2) or black
312 pieces (button 3). Additional menu choices let you empty the square or
313 clear the board. Click on the White or Black clock to set the side to play.
314 You cannot set the side to play or drag pieces to arbitrary squares while
315 examining on ICC, but you can do so in bsetup mode on FICS.
317 If you are playing a bughouse game on the ICS, you can drop an offboard piece
318 by pressing mouse button 2 or 3 over an empty square to bring up a piece menu.
319 It makes no difference which button you use. A list of the offboard pieces
320 each player has available is shown in the window title after the player's name.
323 Allows you to make moves for both Black and White, and
324 to change moves after backing up with the Backward command.
325 The clocks do not run.
327 In chess engine mode, the chess engine continues to check moves for
328 legality but does not participate in the game. You can bring the
329 chess engine back into the game by selecting Machine White, Machine Black,
332 In ICS mode, the moves are not sent to the ICS:
335 out of ICS Client mode and lets you edit games locally.
337 games on ICS in a way that other ICS users can see,
340 command or start an ICS match against yourself.
343 Lets you set up an arbitrary board position.
344 Use mouse button 1 to drag pieces to new squares, or to
345 delete a piece by dragging it off the board or dragging an empty square
346 on top of it. To drop a new piece on a square, press mouse button 2 or 3
347 over the square. This brings up a menu of white pieces (button 2) or black
348 pieces (button 3). Additional menu choices let you empty the square or
349 clear the board. You can set the side to play next
350 by clicking on the White or Black indicator at the top of the screen.
351 Selecting Edit Position causes
353 to discard all remembered moves in the current game.
355 In ICS mode, changes made to the position by Edit Position
356 are not sent to the ICS: Edit Position takes
358 out of ICS Client mode and lets you edit positions locally.
360 positions on ICS in a way that other ICS users can see,
363 command, or start an ICS match against yourself.
364 (See also the ICS Client topic above.)
367 Training mode lets you interactively guess the moves of a game for one
368 of the players. You guess the next move of the game by playing the
369 move on the board. If the move played matches the next move of the
370 game, the move is accepted and the opponent's response is autoplayed.
371 If the move played is incorrect, an error message is displayed. You
372 can select this mode only while loading a game (that is, after
373 selecting Load Game from the File menu). While xboard is in Training
374 mode, the navigation buttons are disabled.
377 Shows or hides the list of games generated by the last Load Game command.
380 Lets you edit the PGN (portable game notation)
381 tags for the current game. After editing, the tags must still conform to
385 <tag-section> ::= <tag-pair> <tag-section>
387 <tag-pair> ::= [ <tag-name> <tag-value> ]
388 <tag-name> ::= <identifier>
389 <tag-value> ::= <string>
392 See the PGN Standard for full details. Here is an example:
395 [Event "Portoroz Interzonal"]
396 [Site "Portoroz, Yugoslavia"]
399 [White "Robert J. Fischer"]
400 [Black "Bent Larsen"]
404 Any characters that do not match this syntax are silently ignored. Note that
405 the PGN standard requires all games to have at least the seven tags shown
406 above. Any that you omit will be filled in by
408 with "?" (unknown value), or "-" (inapplicable value).
411 Adds or modifies a comment on the current position. Comments are
412 saved by Save Game and are displayed by Load Game, Forward, and Backward.
415 If this mode is on in ICS mode,
417 creates an extra window that you can use for typing in ICS commands.
418 The input box is especially useful if you want to type in something long or do
419 some editing on your input, because output from ICS doesn't get mixed
420 in with your typing as it would in the main terminal window.
423 Pauses updates to the board, and if you are playing
424 against a local chess engine, also pauses your clock.
425 To continue, select Pause again, and the display will automatically
426 update to the latest position.
427 The [P] button and keyboard "p" key are equivalents.
429 If you select Pause when you are playing against a local chess engine and
430 it is not your move, the engine's clock
431 will continue to run and it will eventually make a move, at which point
432 both clocks will stop. Since board updates are paused, however,
433 you will not see the move until you exit from Pause mode (or select Forward).
434 This behavior is meant to simulate adjournment with a sealed move.
436 If you select Pause while you are in
438 mode on ICS, you can step
439 backward and forward in the current history of the examined game without
440 affecting the other observers and examiners. Select Pause again to reconnect
441 yourself to the current state of the game on ICS.
443 If you select Pause while you are loading a game, the
445 You can load more moves manually by selecting Forward, or resume automatic
446 loading by selecting Pause again.
450 Accepts a pending ICS match offer.
451 If there is more than one offer pending, you will have to type in a more
452 specific command instead of using this menu choice.
455 Declines a pending ICS offer (match, draw, adjourn, etc.).
456 If there is more than one offer pending, you will have to type in a more
457 specific command instead of using this menu choice.
460 Calls your opponent's flag, claiming a win on time, or claiming a draw
461 if you are both out of time. You can also call your opponent's flag
462 by clicking on his clock or by pressing the keyboard "t" key.
465 Offers a draw to your opponent, accepts a pending draw offer
466 from your opponent, or claims a draw by repetition or the 50-move
467 rule, as appropriate. The "d" key is a keyboard equivalent.
470 Asks your opponent to agree to adjourning the current game, or
471 agrees to a pending adjournment offer from your opponent.
474 Asks your opponent to agree to aborting the current game, or
475 agrees to a pending abort offer from your opponent.
476 An aborted ICS game ends immediately without affecting either player's rating.
479 Resigns the game to your opponent. The shifted "R" key is a keyboard
483 Ends your participation in observing a game, by issuing the ICS
485 command with no arguments.
488 Ends your participation in examining a game, by issuing the ICS
494 Steps backward through a series of remembered moves.
495 The [<] button and the "b" key are equivalents.
496 In addition, pressing the Control key steps back one move, and releasing
497 it steps forward again.
499 In most modes, Backward only lets you look back at
500 old positions; it does not retract moves.
501 This is the case if you are playing against a local chess engine, playing or
502 observing a game on the ICS, or loading a game. If you select Backward in any
503 of these situations, you will not be allowed to make a different move.
504 Use Retract Move or Edit Game if you want to change past moves.
506 If you are examining a game on ICS, the behavior of
507 Backward depends on whether
510 If Pause mode is off, Backward issues the ICS
513 backs up everyone's view of the game and allows you to make a different move.
514 If Pause mode is on, Backward only backs up your local view.
517 Steps forward through a series of remembered moves (undoing the effect of
518 Backward) or forward through a game file.
519 The [>] button and the f key are equivalents.
521 If you are examining a game on ICS, the behavior of
522 Forward depends on whether
525 If Pause mode is off, Forward issues the ICS
528 moves everyone's view of the game forward along the current line.
529 If Pause mode is on, Forward only moves your local view forward, and it
530 will not go past the position that the game was in when you paused.
533 Jumps backward to the first remembered position in the game.
534 The [<<] button and the shifted "B" key are equivalents.
536 In most modes, Back to Start only lets you look back at
537 old positions; it does not retract moves.
538 This is the case if you are playing against a local chess engine, playing or
539 observing a game on the ICS, or loading a game. If you select Back to
541 of these situations, you will not be allowed to make different moves.
542 Use Retract Move or Edit Game if you want to change past moves; or
543 use Reset to start a new game.
545 If you are examining a game on ICS, the behavior of
546 Back to Start depends on whether
549 If Pause mode is off, Back to Start issues the ICS
552 backs up everyone's view of the game to the start and allows you to make
554 If Pause mode is on, Back to Start only backs up your local view.
557 Jumps forward to the last remembered position in the game.
558 The [>>] button and the shifted "F" key are equivalents.
560 If you are examining a game on ICS, the behavior of
561 Forward to End depends on whether
564 If Pause mode is off, Forward to End issues the ICS
566 command, which moves everyone's view of the game forward to the end
568 If Pause mode is on, Forward to End only moves your local view forward, and it
569 will not go past the position that the game was in when you paused.
572 If you are examining a game on ICS and Pause mode is off,
573 issues the ICS command
577 Discards all remembered moves of the game beyond the current position.
580 into Edit Game mode if it was not there already.
583 Forces the chess engine to move immediately. May not work with all
587 Retracts your last move.
588 When playing a local chess engine, you can do this only after the
589 engine has replied to your move; if it is still thinking, use Move Now first.
590 In ICS mode, Retract Move issues the command
594 depending on whether it is your opponent's move or yours.
598 If this option is off,
600 brings up a dialog box whenever you move a pawn to the last rank,
601 asking what piece you want to promote it to.
602 If the option is on, your pawns are always promoted to
603 queens. Your opponent can still underpromote.
606 If Animate Dragging is on, while you are dragging a piece with the
607 mouse, an image of the piece follows the mouse cursor.
608 If Animate Dragging is off, there is no visual feedback while you are
609 dragging a piece, but if Animate Moving is on, the move will be
610 animated when it is complete.
613 If Animate Moving is on, all piece moves are animated. An image of the
614 piece is shown moving from the old square to the new square when the
615 move is completed (unless the move was already animated by Animate Dragging).
616 If Animate Moving is off, a moved piece instantly disappears from its
617 old square and reappears on its new square when the move is complete.
620 If this option is on, any remarks made on ICS while you are observing or
621 playing a game are recorded as a comment on the current move. This includes
622 remarks made with the ICS commands
623 .I say, tell, whisper,
626 Limitation: remarks that you type yourself are not recognized;
628 scans only the output from ICS, not the input you type to it.
631 If this option is on and one player runs out of time
634 will automatically call his flag, claiming a win on time.
635 In ICS mode, Auto Flag will only call your opponent's flag, not yours,
636 and the ICS may award you a draw instead of a win if you have
637 insufficient mating material. In local chess engine mode,
639 may call either player's flag and will not take material into account.
642 If the Auto Flip View option is on when you start a game, the board
643 will be automatically oriented so that your pawns move from the bottom
644 of the window towards the top.
647 If this option is on and you add a player to your
651 will automatically observe all of that player's games, unless you are
652 doing something else (such as observing or playing a game of your own) when
654 The games are displayed
655 from the point of view of the player on your gnotify list; that is, his
656 pawns move from the bottom of the window towards the top.
657 Exceptions: If both players in a game are on your gnotify list, if
660 variable is set to 0, or if the ICS you are using does not
661 properly support observing from Black's point of view,
662 you will see the game from White's point of view.
665 If this option is on, whenever a new game begins, the chessboard window
666 is deiconized (if necessary) and raised to the top of the stack of windows.
669 If this option is on, at the end of every game
671 prompts you for a file name and appends a record
672 of the game to the file you specify. Disabled if the saveGameFile
673 option is set, as in that case all games are saved to the specified file.
676 If this option is on, xboard displays the board as usual but does
677 not display pieces or move highlights. You can still move in the
678 usual way (with the mouse or by typing moves in ICS mode), even though
679 the pieces are invisible.
682 If this option is on, whenever a move is completed, the moved piece flashes.
683 The number of times to flash is set by the flashCount command-line
684 option; it defaults to 3 if Flash Moves is first turned on from the menu.
687 Inverts your view of the chess board for the duration of the current
688 game. Starting a new game returns the board to normal.
689 The "v" key is a keyboard equivalent.
692 playing a game on the ICS, the board is always
693 oriented at the start of the game so that your
694 pawns move from the bottom of the window towards the top.
695 Otherwise, the starting orientation is determined by the flipView command line
696 option; if it is False (the default), White's pawns move from bottom
697 to top at the start of each game; if it is True, Black's pawns move
701 If this option is on, whenever
703 receives the first board of a new ICS game (or a different ICS game from
704 the one it is currently displaying), it
705 retrieves the list of past moves from the ICS.
706 You can then review the moves with the Forward and Backward commands
707 or save them with Save Game. You might want to
708 turn off this option if you are observing several blitz games at once,
709 to keep from wasting time and network bandwidth fetching the move lists over
711 When you turn this option on from the menu,
713 immediately fetches the move list of the current game (if any).
715 .B Highlight Last Move
716 If Highlight Last Move is on, after a move is made, the starting and
717 ending squares remain highlighted. In addition, after you use Backward
718 or Back to Start, the starting and ending squares of the last move to
719 be unmade are highlighted.
722 If this option is on,
724 alerts you by playing a sound after each
725 of your opponent's moves (or after every move if
726 you are observing a game on the Internet Chess Server).
727 The sound is not played after moves you make
728 or moves read from a saved game file. By default, the
729 sound is the terminal bell, but on some systems you can change it
730 to a sound file using the soundMove option; see below.
732 If you turn on this option when using
734 with the Internet Chess Server, you will probably want to
737 command to the ICS, since otherwise the ICS
738 will ring the terminal bell after every move.
741 When this option is on, an alarm sound is played when your clock
742 counts down to the icsAlarmTime (by default, 5 seconds) in an ICS
743 game. For games with time controls that include an increment, the
744 alarm will sound each time the clock counts down to the icsAlarmTime.
745 By default, the alarm sound is the terminal bell, but on some systems
746 you can change it to a sound file using the soundIcsAlarm option; see
750 If this option is off,
752 saves games in PGN (portable game notation) and positions in FEN
753 (Forsythe-Edwards notation). If the option is on,
754 a save style that is compatible with older versions of
756 is used instead. The old position style is more human-readable than
757 FEN; the old game style has no particular advantages.
760 If this option is off (or if
761 you are using a chess engine that does not support periodic updates),
763 will be updated only when the analysis changes. If this option is
764 on, the Analysis Window will be updated every two seconds.
767 If this option is off, the chess engine will think only when it is on
768 move. If the option is on, the engine will also think while waiting
769 for you to make your move.
771 .B Popup Exit Message
772 If this option is on, when xboard wants to display a message just
773 before exiting, it brings up a modal dialog box and waits for you to
774 click OK before exiting. If the option is off, xboard prints the
775 message to standard error (the terminal) and exits immediately.
778 If this option is off, when you make an error in moving (such as
779 attempting an illegal move or moving the wrong color piece), the
780 error message is displayed in the message area. If the option is
781 on, move errors are displayed in small popup windows like other errors.
782 You can dismiss an error popup either by clicking its OK button or by
783 clicking anywhere on the board, including downclicking to start a move.
786 If this option is on while playing a game on ICS, you can register
787 your next planned move before it is your turn. Move the piece with
788 the mouse in the ordinary way, and the starting and ending squares
789 will be highlighted with a special color (red by default). When it is
790 your turn, if your registered move is legal, xboard will send it to
791 ICS immediately; if not, it will be ignored and you can make a
792 different move. If you change your mind about your premove, either
793 make a different move, or double-click on any piece to cancel the move
797 If this option is on,
799 will automatically issue an ICS
801 command whenever you start an ICS
804 command whenever you finish one. Thus you
805 will not be distracted by shouts from other ICS users while playing.
808 If this option is on,
810 displays algebraic coordinates along the board's left and bottom edges.
813 If this option is on, the chess engine's notion of the score and best
815 from the current position is displayed as it is thinking. The score indicates
816 how many pawns ahead (or if negative, behind) the engine thinks it is.
817 When GNU Chess is thinking on your time, this thinking is not shown if GNU
818 Chess was compiled with the -DQUIETBACKGROUND option.
819 In matches between two machines, the score is prefixed by W or B to indicate
820 whether the display is of White's thinking or Black's, and thinking on the
821 opponent's time is never shown.
824 If this option is on, xboard
825 tests whether moves you try to make with the mouse are legal, and
826 refuses to let you make an illegal move. Moves loaded from a file
827 with Load Game are also checked.
828 If the option is off, all moves are accepted, but
829 if a local chess engine or the ICS is active,
830 they will still reject illegal moves. Turning off this option is
831 useful if you are playing a chess variant with rules that
833 does not understand. (Bughouse, suicide, and wild variants where
834 the king may castle after starting on the d file are generally
835 supported with Test Legality on.)
840 info file in a new window. For this feature to work,
841 you must have the GNU info program installed on your system,
842 and the file xboard.info must either be present in the current
843 working directory, or have been installed by
846 command when you built
850 Displays this man page in a new window. For this feature to work,
851 the file xboard.6 must have been installed by
854 command when you built
857 directory it was placed in must be on the search path for your system's
862 Displays a move hint from the local chess engine.
865 Displays a list of possible moves from the local chess engine's opening book.
866 The first column gives moves, the second column gives one possible response
867 for each move, and the third column shows the number of lines in the
868 book that include the move from the first column. If you select this option
869 and nothing happens, the chess engine is out of its book or does not
870 support this command.
876 .SH Other shortcut keys
879 Pressing the i or c key iconizes
881 The graphical icon displays a white knight if it is White's move, or a
882 black knight if it is Black's move. If your X window manager displays only
883 text icons, not graphical ones, check its documentation; there is probably a
884 way to enable graphical icons. If you are running the Motif window manager
886 add these lines to your \&.Xdefaults file and restart mwm:
889 Mwm*iconDecoration: activelabel label image
890 Mwm*XBoard*iconImageBackground: White
891 Mwm*XBoard*iconImageForeground: Black
894 The first line above enables graphical icons in
896 you don't need it if you already have them.
897 The next two lines force the white knights to come out white and the black
898 knights black. Unfortunately these resources can't be set from inside
900 you have to set them in your \&.Xdefaults.
902 You can add or remove
906 .IR form.translations .
907 Here is an example of what would go in your \&.Xdefaults file:
910 XBoard*form.translations: \\
911 Shift<Key>?: AboutGameProc() \\n \\
912 <Key>y: AcceptProc() \\n \\
913 <Key>n: DeclineProc() \\n \\
914 <Key>i: NothingProc()
917 Binding a key to NothingProc makes it do nothing, thus removing it as a
921 functions that can be bound to keys are:
924 AbortProc, AboutGameProc, AboutProc, AcceptProc,
925 AdjournProc, AlwaysQueenProc, AnalysisModeProc,
926 AnalyzeFileProc, AnimateDraggingProc, AnimateMovingProc,
927 AutobsProc, AutoflagProc, AutoflipProc, AutoraiseProc,
928 AutosaveProc, BackwardProc, BlindfoldProc, BookProc,
929 CallFlagProc, CopyGameProc, CopyPositionProc, DebugProc,
930 DeclineProc, DrawProc, EditCommentProc, EditGameProc,
931 EditPositionProc, EditTagsProc, EnterKeyProc,
932 FlashMovesProc, FlipViewProc, ForwardProc,
933 GetMoveListProc, HighlightLastMoveProc, HintProc,
934 Iconify, IcsAlarmProc, IcsAlarmProc, IcsClientProc,
935 IcsInputBoxProc, InfoProc, LoadGameProc,
936 LoadNextGameProc, LoadNextPositionProc, LoadPositionProc,
937 LoadPrevGameProc, LoadPrevPositionProc, LoadSelectedProc,
938 MachineBlackProc, MachineWhiteProc, MailMoveProc,
939 ManProc, MoveNowProc, MoveSoundProc, NothingProc,
940 OldSaveStyleProc, PasteGameProc, PastePositionProc,
941 PauseProc, PeriodicUpdatesProc, PonderNextMoveProc,
942 PopupExitMessageProc, PopupMoveErrorsProc, PremoveProc,
943 QuietPlayProc, QuitProc, ReloadCmailMsgProc,
944 ReloadGameProc, ReloadPositionProc, RematchProc,
945 ResetProc, ResignProc, RetractMoveProc, RevertProc,
946 SaveGameProc, SavePositionProc, ShowCoordsProc,
947 ShowGameListProc, ShowThinkingProc, StopExaminingProc,
948 StopObservingProc, TestLegalityProc, ToEndProc,
949 ToStartProc, TrainingProc, TruncateGameProc, and
954 This section documents the command-line options to
956 You can set these options in two ways: by typing them on the shell
957 command line you use to start
959 or by setting them as X resources (typically in your \&.Xdefaults file).
960 Many of the options cannot be changed while
962 is running; others set the initial state of items
963 that can be changed with the Options menu.
966 options have both a long name and a short name.
967 To turn a boolean option on or off from the command line, either give
968 its long name followed by the value True or False
969 .RI ( -longOptionName
971 just the short name to turn the option on
973 or the short name preceded by "x" to turn the option off
975 For options that take strings or numbers as values, you can use the long or
976 short option names interchangeably.
978 Each option corresponds to an X resource
979 with the same name, so if you like, you can set options in your
981 file or in a file named XBoard in your home directory.
982 For options that have two names, the longer
983 one is the name of the corresponding X resource; the short name is not
985 To turn a boolean option on or off as an X resource,
986 give its long name followed by the value True or False
987 .RI (XBoard* longOptionName :
989 .SH Chess Engine Options
990 All of these options apply to both the GNU Chess and Crafty
993 .B -tc \fRor\fB -timeControl minutes[:seconds]
994 Each player begins with his clock set to the timeControl period.
996 The additional options movesPerSession and timeIncrement are mutually
999 .B -mps \fRor\fB -movesPerSession moves
1000 When both players have made movesPerSession moves, a
1001 new timeControl period is added to both clocks. Default: 40 moves.
1003 .B -inc \fRor\fB -timeIncrement seconds
1004 If this option is specified, movesPerSession is ignored.
1005 Instead, after each player's move, timeIncrement seconds are
1007 Use -timeIncrement 0 if you want to require the entire
1008 game to be played in one timeControl period, with no increment.
1009 Default: -1, which specifies movesPerSession mode.
1011 .B -clock/-xclock \fRor\fB -clockMode True/False
1012 Determines whether or not to display the chess clocks.
1013 If clockMode is False, the clocks are not shown, but the
1014 side that is to play next is still highlighted. Also, unless
1015 searchTime is set, the chess engine still keeps track of the
1016 clock time and uses it to determine how fast to make its moves.
1018 .B -st \fRor\fB -searchTime minutes[:seconds]
1019 Tells the chess engine to spend at most the given amount of time searching
1020 for each of its moves. Without this option, the engine chooses
1021 its search time based on the number of moves and amount of time
1022 remaining until the next time control.
1023 Setting this option also sets clockMode to False.
1025 .B -depth \fRor\fB -searchDepth number
1026 Tells the chess engine
1027 to look ahead at most the given number of moves when searching
1028 for a move to make. Without this option, the engine chooses
1029 its search depth based on the number of moves and amount of time
1030 remaining until the next time control.
1032 the engine will cut off its search early if it reaches the specified depth.
1034 .B -thinking/-xthinking \fRor\fB -showThinking True/False
1035 Sets the Show Thinking menu option. Default: False.
1037 .B -ponder/-xponder \fRor\fB -ponderNextMove True/False
1038 Sets the Ponder Next Move menu option. Default: True.
1040 .B -mg \fRor\fB -matchGames n
1041 Automatically runs an \fIn\fP-game match between two chess engines,
1042 with alternating colors.
1043 If the loadGameFile or loadPositionFile option is set,
1045 starts each game with the given opening moves or the given position;
1046 otherwise, the games start with the standard initial chess position.
1048 option is set, a move record for the match
1049 is appended to the specified file.
1050 If the savePositionFile
1051 option is set, the final position reached in each game of the match
1052 is appended to the specified file.
1053 When the match is over,
1055 displays the match score and exits. Default: 0 (do not run a match).
1057 .B -mm/-xmm \fRor\fB -matchMode True/False
1058 Provided for backward compatibility.
1059 If true and matchGames is 0, sets matchGames to 1.
1061 .B -fcp \fRor\fB -firstChessProgram program
1062 Name of first chess engine.
1066 .B -scp \fRor\fB -secondChessProgram program
1067 Name of second chess engine.
1068 A second chess engine is started only in Two Machines (match) mode.
1072 .B -fb/-xfb \fRor\fB -firstPlaysBlack True/False
1073 In games between two chess engines, firstChessProgram normally
1074 plays white. (This is a change from earlier versions of
1076 If this option is True, firstChessProgram plays black.
1077 In a multi-game match, this option affects the colors only for
1078 the first game; they still alternate in subsequent games.
1080 .B -fh \fRor\fB -firstHost host
1083 .B -sh \fRor\fB -secondHost host
1084 Hosts on which the chess engines are to be run.
1085 The default for each is
1087 If you specify another host,
1091 to run the chess engine there.
1092 (You can substitute a different remote shell program for rsh using the
1093 remoteShell option described below.)
1096 .B -fd \fRor\fB -firstDirectory dir
1099 .B -sd \fRor\fB -secondDirectory dir
1100 Working directories in which the chess engines are to be run.
1101 The default for both is "", which means to run the chess engine
1102 in the same working directory as
1104 itself. (See the CHESSDIR environment variable.)
1105 This option is effective only when the chess engine is being run
1106 on the local host; it does not work if the engine is run remotely
1107 using the -fh or -sh option.
1110 .B -initString string
1113 .B -secondInitString string
1114 The string that is sent to initialize each chess engine for a new game.
1120 Setting this option from the command line is tricky,
1121 because you must type in real newline characters, including one at the end.
1122 In most shells you can
1123 do this by entering a "\\" character followed by a newline.
1124 It is easier to set the option from your \&.Xdefaults file;
1125 in that case you can include the character sequence "\\n" in the string, and
1126 it will be converted to a newline.
1128 If you change this option, don't remove the
1130 command; it is required by all chess engines to start a new game.
1135 like; including it causes GNU Chess to randomize its move selection slightly so
1136 that it doesn't play the same moves in every game.
1140 randomizes its choice of moves from its opening book. Crafty
1141 ignores this command; it randomizes by default.
1143 You can also try adding other commands to the initString;
1144 see the GNU Chess or Crafty documentation for details.
1147 .B -firstComputerString string
1150 .B -secondComputerString string
1151 The string that is sent to the chess engine if its opponent is another
1152 computer chess engine. The default is "computer\\n". Probably the
1153 only useful alternative is the empty string (""), which keeps the
1154 engine from knowing that it is playing another computer.
1157 .B -reuse/-xreuse \fRor\fB -reuseFirst True/False
1160 .B -reuse2/-xreuse2 \fRor\fB -reuseSecond True/False
1161 If the option is False,
1163 kills off the chess engine after every game and starts it again
1165 If the option is True (the default),
1167 starts the chess engine only once
1168 and uses it repeatedly to play multiple games.
1169 Some chess engines may not work properly when
1170 reuse is turned on, such as versions of Crafty earlier than 12.0,
1171 but otherwise new games will start faster if it is left on.
1174 .B -firstProtocolVersion version-number
1177 .B -secondProtocolVersion version-number
1178 This option specifies which version of the chess engine communication
1179 protocol to use. By default, version-number is 2. In version 1, the
1180 "protover" command is not sent to the engine; since version 1 is a
1181 subset of version 2, nothing else changes. Other values for
1182 version-number are not supported.
1184 .SH Internet Chess Server Options
1186 .B -ics/-xics \fRor\fB -internetChessServerMode True/False
1187 Connect with an Internet Chess Server to play chess against
1188 its other users, observe games they are playing, or
1189 review games that have recently finished. Default: False.
1191 .B -icshost \fRor\fB -internetChessServerHost host
1192 The Internet host name or address of the chess server to connect
1193 to when in ICS mode.
1194 Default: chessclub.com.
1199 source distribution for a list of other addresses to try.
1200 If your site doesn't have a working Internet name server, try
1201 specifying the host address in numeric form. You may also need
1202 to specify the numeric address when using the icshelper option
1203 with timestamp or timeseal (see below).
1205 chessclub.com is 207.99.5.190 and freechess.org (formerly fics.onenet.net)
1208 .B -icsport \fRor\fB -internetChessServerPort port-number
1209 The port number to use when connecting to a chess server in ICS mode.
1212 .B -icshelper \fRor\fB -internetChessServerHelper prog-name
1213 An external helper program used to communicate with the chess server.
1214 You would set it to "timestamp" for ICC (chessclub.com) or
1215 "timeseal" for FICS (freechess.org, eics.daimi.aau.dk, etc.), after
1216 obtaining the correct version of timestamp or timeseal for your
1217 computer. See "help timestamp" on ICC and "help timeseal" on FICS.
1218 This option is shorthand for "-useTelnet -telnetProgram program".
1220 .B -telnet/-xtelnet \fRor\fB -useTelnet True/False
1221 This option is poorly named; it should be called useHelper.
1222 If set to True, it instructs
1224 to run an external program to communicate with the Internet Chess
1225 Server. The program to use is given by the telnetProgram option.
1226 If the option is False (the default),
1228 opens a TCP socket and uses its own internal implementation
1229 of the telnet protocol to communicate with the ICS.
1230 See the FIREWALLS section
1231 below for an explanation of when this option is useful.
1233 .B -telnetProgram prog-name
1234 This option is poorly named; it should be called helperProgram.
1235 It gives the name of the telnet program to be used with the
1236 gateway and useTelnet options. The default is
1239 is invoked with the value of internetChessServerHost as its first argument
1240 and the value of internetChessServerPort as its second argument.
1241 See the FIREWALLS section below for an explanation of when this option is
1244 .B -gateway host-name
1245 If this option is set to a host name,
1247 communicates with the Internet Chess Server by using
1249 to run the telnetProgram
1250 on the given host, instead of using its own internal implementation
1251 of the telnet protocol.
1252 You can substitute a different remote shell program for rsh with the
1253 remoteShell option described below.
1254 See the FIREWALLS section below for an explanation of when this option is
1257 .B -internetChessServerCommPort \fRor\fB -icscomm dev-name
1258 If this option is set,
1260 communicates with the ICS through the given character I/O device
1261 instead of opening a TCP connection.
1262 Use this option if your system
1263 does not have any kind of Internet connection itself (not
1264 even a SLIP or PPP connection), but you do have dialup access
1265 (or a hardwired terminal line) to an Internet
1266 service provider from which you can telnet to the ICS.
1268 The support for this option in
1270 is minimal. You need to set all communication parameters and tty modes
1274 Use a script something like this:
1277 stty raw -echo 9600 > /dev/tty00
1278 xboard -ics -icscomm /dev/tty00
1283 with the name of the device that your
1284 modem is connected to.
1285 You might have to add several more options to these stty commands. See the
1290 if you run into problems. Also, on many systems
1291 stty works on its standard input instead of standard output, so you
1292 have to use "<" instead of ">".
1294 If you are using linux, try starting with the script below. Change it as
1295 necessary for your installation.
1298 ##################################################
1300 # configure modem and fire up xboard
1303 ( stty 2400 ; stty raw ; stty hupcl ; stty -clocal
1304 stty ignbrk ; stty ignpar ; stty ixon ; stty ixoff
1305 stty -iexten ; stty -echo ) < /dev/modem
1307 xboard -ics -icscomm /dev/modem
1308 ##################################################
1313 in this way, type whatever commands are necessary to dial out to
1314 your Internet provider and log in.
1315 Then telnet to ICS, using a command like
1316 .IR "telnet chessclub.com 5000" .
1317 Important: See the paragraph in the LIMITATIONS section below
1320 .B -icslogon \fRor\fB -internetChessServerLogonScript file-name
1323 connects to the Internet Chess Server, if it finds a file with
1324 the name given in this option,
1325 it feeds the file's contents to the ICS as commands.
1326 The default file name is
1328 Usually the first two lines of the file should be your ICS user name
1330 The file can be either in $CHESSDIR, in
1332 working directory if CHESSDIR is not set, or in your home directory.
1334 .B -msLoginDelay delay
1335 If you experience trouble logging onto an ICS using the
1337 option, inserting some delay between characters of the login
1338 script may help. This option inserts
1340 milliseconds of delay per character. Good values to
1341 try are 100 and 250.
1343 .B -icsinput/-xicsinput \fRor\fB -internetChessServerInputBox True/False
1344 Sets ICS Input Box on the mode menu. Default: False.
1346 .B -autocomm/-xautocomm \fRor\fB -autoComment True/False
1347 Sets the Auto Comment menu option. Default: False.
1349 .B -autoflag/-xautoflag \fRor\fB -autoCallFlag True/False
1350 Sets the Auto Flag menu option. Default: False.
1352 .B -autobs/-xautobs \fRor\fB -autoObserve True/False
1353 Sets the Auto Observe menu option. Default: False.
1355 .B -moves/-xmoves \fRor\fB -getMoveList True/False
1356 Sets the Get Move List menu option. Default: True.
1358 .B -alarm/-xalarm \fRor\fB -icsAlarm True/False
1359 Sets the ICS Alarm menu option. Default: True.
1362 Sets the time in milliseconds for the ICS Alarm menu option. Default: 5000.
1364 .B -pre/-xpre \fRor\fB -premove True/False
1365 Sets the Premove menu option. Default: True.
1367 .B -quiet/-xquiet \fRor\fB -quietPlay True/False
1368 Sets the Quiet Play menu option. Default: False.
1371 .B -colorize/-xcolorize \fRor\fB -colorizeMessages TrueFalse
1376 to colorize the messages received from the ICS.
1377 Colorization works only if your xterm
1378 supports ISO 6429 escape sequences for changing text colors.
1380 .B -colorShout foreground,background,bold
1383 .B -colorSShout foreground,background,bold
1385 .B -colorChannel foreground,background,bold
1387 .B -colorKibitz foreground,background,bold
1389 .B -colorTell foreground,background,bold
1391 .B -colorChallenge foreground,background,bold
1393 .B -colorRequest foreground,background,bold
1395 .B -colorSeek foreground,background,bold
1397 .B -colorNormal foreground,background,bold
1399 These options set the colors used when colorizing ICS messages.
1400 All ICS messages are grouped into one of these categories:
1401 shout, sshout, channel 1, other channel, kibitz, tell, challenge,
1402 request (including abort, adjourn, draw, pause, and takeback),
1403 seek, or normal (all other messages).
1405 Each foreground or background argument can be one of the following:
1406 black, red, green, yellow, blue, magenta, cyan, white, or default.
1407 Here "default" means the default foreground or background color of
1408 your xterm. Bold can be 1 or 0. If background is omitted, "default"
1409 is assumed; if bold is omitted, 0 is assumed.
1411 Here is an example of how to set the colors in your \&.Xdefaults file.
1412 The colors shown here are the default values; you will get
1413 them if you turn -colorize on without specifying your own colors.
1416 xboard*colorizeMessages: true
1417 xboard*colorShout: green
1418 xboard*colorSShout: green, black, 1
1419 xboard*colorChannel1: cyan
1420 xboard*colorChannel: cyan, black, 1
1421 xboard*colorKibitz: magenta, black, 1
1422 xboard*colorTell: yellow, black, 1
1423 xboard*colorChallenge: red, black, 1
1424 xboard*colorRequest: red
1425 xboard*colorSeek: blue
1426 xboard*colorNormal: default
1429 .B -soundProgram progname
1430 If this option is set to a sound-playing program that is installed and
1431 working on your system, xboard can play sound files when certain
1432 events occur, listed below. The default program name is "play". If
1433 any of the sound options is set to "$", the event rings the terminal
1434 bell by sending a ^G character to standard output, instead of playing
1435 a sound file. If an option is set to the empty string "", no sound is
1436 played for that event.
1438 .B -soundShout filename
1441 .B -soundSShout filename
1443 .B -soundChannel filename
1445 .B -soundKibitz filename
1447 .B -soundTell filename
1449 .B -soundChallenge filename
1451 .B -soundRequest filename
1453 .B -soundSeek filename
1455 These sounds are triggered in the same way as the colorization events
1456 described above. They all default to "", no sound. They are played
1457 only if the colorizeMessages is on.
1459 .B -soundMove filename
1460 This sound is used by the Move Sound menu option. Default: "$".
1462 .B -soundIcsAlarm filename
1463 This sound is used by the ICS Alarm menu option. Default: "$".
1465 .B -soundIcsWin filename
1466 This sound is played when you win an ICS game. Default: "" (no sound).
1468 .B -soundIcsLoss filename
1469 This sound is played when you lose an ICS game. Default: "" (no sound).
1471 .B -soundIcsDraw filename
1472 This sound is played when you draw an ICS game. Default: "" (no sound).
1474 .B -soundIcsUnfinished filename
1475 This sound is played when an ICS game that you are participating in is
1476 aborted, adjourned, or otherwise ends inconclusively. Default: "" (no
1479 Here is an example of how to set the sounds in your \&.Xdefaults file.
1482 xboard*soundShout: shout.wav
1483 xboard*soundSShout: sshout.wav
1484 xboard*soundChannel1: channel1.wav
1485 xboard*soundChannel: channel.wav
1486 xboard*soundKibitz: kibitz.wav
1487 xboard*soundTell: tell.wav
1488 xboard*soundChallenge: challenge.wav
1489 xboard*soundRequest: request.wav
1490 xboard*soundSeek: seek.wav
1491 xboard*soundMove: move.wav
1492 xboard*soundIcsWin: win.wav
1493 xboard*soundIcsLoss: lose.wav
1494 xboard*soundIcsDraw: draw.wav
1495 xboard*soundIcsUnfinished: unfinished.wav
1496 xboard*soundIcsAlarm: alarm.wav
1498 .SH Load and Save Options
1500 .B -lgf \fRor\fB -loadGameFile file
1503 .B -lgi \fRor\fB -loadGameIndex index
1504 If the loadGameFile option is set,
1506 loads the specified game file at startup.
1507 The file name "-" specifies the standard input.
1508 If there is more than one game in the file,
1510 pops up a menu of the available games, with entries based on their PGN
1511 (portable game notation) tags.
1512 If the loadGameIndex option is set to
1514 the menu is suppressed and
1517 game found in the file is loaded immediately.
1518 The menu is also suppressed if matchMode is enabled or if the game file
1519 is a pipe; in these cases the first game in
1520 the file is loaded immediately. Use the
1522 shell script if you want to pipe files containing multiple games into
1524 and still see the menu.
1527 .B -td \fRor\fB -timeDelay seconds
1528 Time delay between moves during \fBLoad Game\fR.
1529 Fractional seconds are allowed; try -td 0.4.
1530 A time delay value of -1 tells
1532 not to step through game files automatically.
1535 .B -sgf \fRor\fB -saveGameFile file
1536 If this option is set,
1538 appends a record of every game played to the specified file.
1539 The file name "-" specifies the standard output.
1541 .B -autosave/-xautosave \fRor\fB -autoSaveGames True/False
1542 Sets the Auto Save menu option.
1543 Ignored if saveGameFile is set.
1546 .B -lpf \fRor\fB -loadPositionFile file
1549 .B -lpi \fRor\fB -loadPositionIndex index
1550 If the loadPositionFile option is set,
1552 loads the specified position file at startup.
1553 The file name "-" specifies the standard input.
1554 If the loadPositionIndex option is set to
1558 position found in the file is loaded; otherwise the first position is loaded.
1561 .B -spf \fRor\fB -savePositionFile file
1562 If this option is set,
1564 appends the final position reached in
1565 every game played to the specified file.
1566 The file name "-" specifies the standard output.
1568 .B -oldsave/-xoldsave \fRor\fB -oldSaveStyle True/False
1569 Sets the Old Save Style menu option. Default: False.
1570 .SH User Interface Options
1572 .B standard Xt options
1574 accepts standard Xt options like -display, -geometry, and -iconic.
1576 .B -movesound/-xmovesound \fRor\fB -ringBellAfterMoves True/False
1577 Sets the Move Sound menu option. Default: False.
1578 For upward compatibility, -bell/-xbell are also accepted as abbreviations
1581 .B -exit/-xexit \fRor\fB -popupExitMessage True/False
1582 Sets the Popup Exit Message menu option. Default: True.
1584 .B -popup/-xpopup \fRor\fB -popupMoveErrors True/False
1585 Sets the Popup Move Errors menu option. Default: False.
1587 .B -queen/-xqueen \fRor\fB -alwaysPromoteToQueen True/False
1588 Sets the Always Queen menu option. Default: False.
1590 .B -legal/-xlegal \fRor\fB -testLegality True/False
1591 Sets the Test Legality menu option. Default: True.
1593 .B -size \fRor\fB -boardSize "(sizeName | n1,n2,n3,n4,n5,n6,n7)"
1594 Determines how large the board will be, by selecting the pixel size
1595 of the pieces and setting a few related parameters.
1596 The sizeName can be one of: Titanic, giving 129x129 pixel pieces,
1597 Colossal 116x116, Giant 108x108, Huge 95x95, Big 87x87, Large 80x80, Bulky 72x72,
1598 Medium 64x64, Moderate 58x58, Average 54x54, Middling 49x49, Mediocre
1599 45x45, Small 40x40, Slim 37x37, Petite 33x33, Dinky 29x29, Teeny 25x25,
1601 Pieces of all these sizes are built into xboard. Other sizes can
1602 be used if you have them; see the pixmapDirectory and bitmapDirectory
1604 The default depends on the size of your screen; it is approximately the
1605 largest size that will fit without clipping.
1607 You can select other sizes or vary other layout parameters by providing
1608 a list of comma-separated values (with no spaces) as the argument.
1609 You do not need to provide all the values; for any you omit from the
1610 end of the list, defaults are taken from the nearest built-in size.
1611 The value n1 gives the piece size, n2 the width of the black border
1612 between squares, n3 the desired size for the
1614 n4 the desired size for the
1616 n5 the desired size for the default
1618 n6 the smallLayout flag (0 or 1), and n7 the tinyLayout flag (0 or 1).
1619 All dimensions are in pixels.
1620 If the border between squares is eliminated (0 width), the various
1621 highlight options will not work, as there is nowhere to draw the highlight.
1622 If smallLayout is 1 and
1625 the window layout is rearranged to make more room for the title.
1626 If tinyLayout is 1, the labels on the menu bar are abbreviated
1627 to one character each and the buttons in the button bar are made narrower.
1629 .B -coords/-xcoords \fRor\fB -showCoords True/False
1630 Sets the Show Coords menu option. Default: False.
1633 option specifies what font to use.
1635 .B -autoraise/-xautoraise \fRor\fB -autoRaiseBoard True/False
1636 Sets the Auto Raise Board menu option. Default: True.
1638 .B -autoflip/-xautoflip \fRor\fB -autoFlipView True/False
1639 Sets the Auto Flip View menu option. Default: True.
1641 .B -flip/-xflip \fRor\fB -flipView True/False
1642 If Auto Flip View is not set, or if you are observing but not participating
1643 in a game, then the positioning of the board at the start of each game
1644 depends on the flipView option. If flipView is False (the default),
1645 the board is positioned so that the white pawns move from the bottom to the
1646 top; if True, the black pawns move from the bottom to the top.
1647 In any case, the Flip menu option can be used to flip the board after
1650 .B -title/-xtitle \fRor\fB -titleInWindow True/False
1651 If this option is True,
1653 displays player names (for ICS games) and game file names (for Load
1654 Game) inside its main window. If the option is False (the default),
1655 this information is displayed only in the window banner. You probably
1656 won't want to set this option unless the information is not showing up
1657 in the banner, as happens with a few X window managers.
1659 .B -buttons/-xbuttons \fRor\fB -showButtonBar True/False
1660 If this option is False, xboard omits the [<<] [<] [P] [>] [>>] button
1661 bar from the window, allowing the message line to be wider. You can
1662 still get the functions of these buttons using the menus or their keyboard
1663 shortcuts. Default: True.
1665 .B -mono/-xmono \fRor\fB -monoMode True/False
1668 displays its pieces and squares with two colors (True) or four (False).
1669 You shouldn't have to specify monoMode;
1671 will determine if it is necessary.
1673 \fB\-flashCount\fP \fIcount\fP
1676 \fB\-flashRate\fP \fIrate\fP
1681 These options enable flashing of pieces when they
1682 land on their destination square.
1684 tells XBoard how many times to flash a piece after it
1685 lands on its destination square.
1687 controls the rate of flashing (flashes/sec).
1690 sets flashCount to 3.
1692 sets flashCount to 0.
1693 Defaults: flashCount=0 (no flashing), flashRate=5.
1696 .B -highlight/-xhighlight \fRor\fB -highlightLastMove True/False
1697 Sets the Highlight Last Move menu option. Default: False.
1699 .B -blind/-xblind \fRor\fB -blindfold True/False
1700 Sets the Blindfold menu option. Default: False.
1703 The font used for the clocks.
1705 value is a pattern that does not specify the font size,
1707 tries to choose an appropriate font for the board size being used.
1708 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
1711 The font used for rank and file coordinate labels if
1715 value is a pattern that does not specify the font size,
1717 tries to choose an appropriate font for the board size being used.
1718 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
1721 The font used for popup dialogs, menus, comments, etc.
1723 value is a pattern that does not specify the font size,
1725 tries to choose an appropriate font for the board size being used.
1726 Default: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*.
1728 .B -fontSizeTolerance tol
1729 In the font selection algorithm, a nonscalable font will be preferred
1730 over a scalable font if the nonscalable font's size differs by tol pixels
1731 or less from the desired size. A value of -1 will force
1732 a scalable font to always be used if available; a value of 0 will
1733 use a nonscalable font only if it is exactly the right size;
1734 a large value (say 1000) will force a nonscalable font to always be
1735 used if available. Default: 4.
1737 .B -bm \fRor\fB -bitmapDirectory dir
1740 .B -pixmap \fRor\fB -pixmapDirectory dir
1742 These options control what piece images xboard uses. The xboard
1743 distribution includes one set of pixmap pieces in xpm format, in the
1744 directory \fIpixmaps\fR, and two sets of bitmap pieces in xbm format,
1745 in the directories \fIbitmaps\fR and \fIbitmaps.xchess\fR. Pixmap
1746 pieces give a better appearance on the screen: the white pieces have
1747 dark borders, and the black pieces have opaque internal details. With
1748 bitmaps, neither piece color has a border, and the internal details
1749 are transparent; you see the square color or other background color
1752 If xboard is configured and compiled on a system that includes libXpm,
1753 the X pixmap library, the xpm pixmap pieces are compiled in as the
1754 default. A different xpm piece set can be selected at runtime with
1755 the -pixmapDirectory option, or a bitmap piece set can be selected
1756 with the -bitmapDirectory option.
1758 If xboard is configured and compiled on a system that does not include
1759 libXpm (or the --disable-xpm option is given to the configure
1760 program), the bitmap pieces are compiled in as the default. It is not
1761 possible to use xpm pieces in this case, but pixmap pieces in another
1762 format called "xim" can be used by giving the -pixmapDirectory option.
1763 Or again, a different bitmap piece set can be selected with the
1764 -bitmapDirectory option.
1766 Files in the bitmapDirectory must be named as follows:
1767 The first character of a piece bitmap name gives the piece it
1768 represents (p, n, b, r, q, or k),
1769 the next characters give the size in pixels, the
1770 following character indicates whether the piece is solid or outline (s or o),
1771 and the extension is ".bm".
1772 For example, a solid 80x80 knight would be named "n80s.bm".
1773 The outline bitmaps are used only in monochrome mode.
1774 If bitmap pieces are compiled in and the bitmapDirectory is missing
1775 some files, the compiled in pieces are used instead.
1777 If the bitmapDirectory option is given,
1778 it is also possible to replace xboard's icons and menu checkmark,
1779 by supplying files named "icon_white.bm", "icon_black.bm", and
1782 You can import pixmap pieces from the
1784 distribution by using the
1786 program to convert them. This program produces both xpm and xim
1787 pixmaps, so you can use these pieces even if you do not have xpm
1788 support compiled into your xboard. ZIICS provides a large number of
1789 piece sets to choose from. Here's how to import them:
1791 1) Download the ZIICS distribution. It is available from
1794 ftp://ftp.freechess.org/pub/chess/DOS/ziics131.exe
1797 2) Unzip it into a directory, for example:
1800 unzip -L ziics131.exe -d ~/ziics
1803 3) Pick a chess set you want to use, for example the FRITZ4 set.
1804 Create a directory to hold the pieces, then run the
1806 program to create the pieces:
1811 zic2xpm ~/ziics/fritz4.*
1816 program is in the directory where
1819 in case you didn't do a
1820 .IR "make install" .)
1822 4) Now, just add the
1824 option when you start
1828 xboard -pixmapDirectory ~/fritz4
1831 Or add the option to your .Xdefaults file:
1834 xboard*pixmapDirectory: ~/fritz4
1837 .B -whitePieceColor color
1840 .B -blackPieceColor color
1842 .B -lightSquareColor color
1844 .B -darkSquareColor color
1846 .B -highlightSquareColor color
1848 .B -premoveHighlightColor color
1850 Colors to use for the pieces, squares, and square highlights.
1854 -whitePieceColor #FFFFCC
1855 -blackPieceColor #202020
1856 -lightSquareColor #C8C365
1857 -darkSquareColor #77A26D
1858 -highlightSquareColor #FFFF00
1859 -premoveHighlightColor #FF0000
1862 If you are using a grayscale monitor, try setting the colors to:
1865 -whitePieceColor gray100
1866 -blackPieceColor gray0
1867 -lightSquareColor gray80
1868 -darkSquareColor gray60
1869 -highlightSquareColor gray100
1870 -premoveHighlightColor gray70
1873 .B -drag/-xdrag \fRor\fB -animateDragging True/False
1874 Sets the Animate Dragging menu option. Default: True.
1876 .B -animate/-xanimate \fRor\fB -animateMoving True/False
1877 Sets the Animate Moving menu option. Default: True.
1880 Number of milliseconds delay between each animation frame when Animate
1884 .B -ncp/-xncp \fRor\fB -noChessProgram True/False
1885 If this option is True,
1887 acts as a passive chessboard; it does not
1888 start a chess engine at all.
1889 Turning on this option also turns off clockMode.
1892 .B -mode \fRor\fB -initialMode modename
1893 If this option is given, xboard selects the given \fImodename\fP
1894 from the Mode menu after starting and (if applicable) processing the
1895 loadGameFile or loadPositionFile option. Default: "" (no selection).
1896 Other supported values are
1897 MachineWhite, MachineBlack, TwoMachines, Analysis,
1898 AnalyzeFile, EditGame, EditPosition, and Training.
1901 Activates preliminary, partial support for playing chess variants
1902 against a local engine or editing variant games. This flag is not
1903 needed in ICS mode. Recognized variant names are:
1907 wildcastle Shuffle chess, king can castle from d file
1908 nocastle Shuffle chess, no castling allowed
1909 fischerandom Fischer Random shuffle chess
1910 bughouse Bughouse, ICC/FICS rules
1911 crazyhouse Crazyhouse, ICC/FICS rules
1912 losers Lose all pieces or get mated (ICC wild 17)
1913 suicide Lose all pieces including king (FICS)
1914 giveaway Try to have no legal moves (ICC wild 26)
1915 twokings Weird ICC wild 9
1916 kriegspiel Opponent's pieces are invisible
1917 atomic Capturing piece explodes (ICC wild 27)
1918 3check Win by giving check 3 times (ICC wild 25)
1919 shatranj An ancient precursor of chess (ICC wild 28)
1920 unknown Catchall for other unknown variants
1923 In the shuffle variants, xboard does not shuffle the pieces, but
1924 you can do it by hand using Edit Position. Some variants are
1925 supported only in ICS mode, including fischerandom, bughouse, and
1926 kriegspiel. The winning/drawing conditions in crazyhouse (offboard
1927 interposition on mate), losers, suicide, giveaway, atomic, and 3check
1928 are not fully understood. In crazyhouse, xboard does not yet keep
1929 track of offboard pieces. Shatranj is unsupported, but it may be
1930 usable if you turn off Test Legality.
1932 .B -debug/-xdebug \fRor\fB -debugMode True/False
1933 Turns on debugging printout.
1935 .B -rsh \fRor\fB -remoteShell shell-name
1936 Name of the command used to run programs remotely.
1943 is configured and compiled.
1945 .B -ruser \fRor\fB -remoteUser user-name
1946 User name on the remote system when running programs with the remoteShell.
1947 The default is your local user name.
1950 If you are using a chess engine that supports analysis,
1951 such as Crafty, you can use xboard
1952 to analyze your games.
1953 GNU Chess does not support analysis.
1954 See the section titled GETTING CRAFTY
1955 for more information on obtaining and installing Crafty.
1956 There are a few ways to analyze:
1960 .B Analyzing a stored game (PGN, etc):
1965 Type the name of the file you wish to load.
1966 If the file contains multiple games, another popup will
1967 appear to let you choose which game you want to analyze.
1968 Use the arrow buttons to move through the game and watch
1969 the engine's analysis.
1972 .B Setting up a position to analyze
1977 Edit the board (the right and middle mouse buttons bring up
1978 the black/white piece menus). When finished editing, click on
1979 either the White or Black clock to tell
1986 Watch the analysis, move pieces around, etc.
1989 .B Analyzing a new game
1990 If you want to start a new analysis from a fresh board,
1999 Now you can move pieces around and watch the engine's analysis.
2003 Crafty is a chess engine written by Bob Hyatt (hyatt@cis.uab.edu).
2004 You can use XBoard to play a game against Crafty, hook Crafty up
2005 to an ICS, or use Crafty to interactively analyze games and positions
2008 Crafty is a strong, rapidly evolving chess program. This rapid
2009 pace of development is good, because it means Crafty is always
2010 getting better. This can sometimes cause problems with
2011 backwards compatibility, but usually the latest version of Crafty
2012 will work well with the latest version of xboard.
2013 Crafty can be obtained from its author's FTP site:
2014 ftp://ftp.cis.uab.edu/hyatt/.
2016 To use Crafty with XBoard, give the -fcp and -fd options as follows, where
2017 .I crafty's-directory
2018 is the directory in which you installed Crafty
2019 and placed its book and other support files.
2022 xboard -fcp crafty -fd \fIcrafty's-directory\fR
2028 communicates with an Internet Chess Server by opening a TCP socket
2029 directly from the machine it is running on to the ICS. If there is a
2030 firewall between your machine and the ICS, this won't work. Here are some
2031 recipes for getting around common kinds of firewalls using special options to
2033 Important: See the paragraph in the LIMITATIONS section below
2036 Suppose that you can't telnet directly to ICS, but you can telnet to a
2037 firewall host, log in, and then telnet from there to ICS. Let's say the
2038 firewall is called fire.wall.com. Set command-line options as
2042 xboard -ics -icshost fire.wall.com -icsport 23
2045 Or in your \&.Xdefaults file:
2048 XBoard*internetChessServerHost: fire.wall.com
2049 XBoard*internetChessServerPort: 23
2054 in ICS mode, you will be prompted to log in to the firewall host.
2055 (This works because port 23 is the standard telnet login service.)
2056 Log in, then telnet to ICS, using a command like
2057 .IR "telnet chessclub.com 5000" ,
2058 or whatever command the firewall provides for telnetting to port 5000.
2060 If your firewall lets you telnet (or rlogin) to remote hosts, but doesn't let
2061 you telnet to port 5000, you will have to find some other host outside the
2062 firewall that does let you do this, and hop through it. For instance, suppose
2063 you have an account at foo.edu. Follow the recipe above, but
2065 .I "telnet chessclub.com 5000"
2066 to the firewall, type
2069 .IR "rlogin foo.edu" ),
2072 .IR "telnet chessclub.com 5000" .
2074 Exception: chessclub.com itself lets you connect to the chess server on the
2075 default telnet port (23), which is what you get if you don't specify a port
2076 to the telnet program. But the other chess servers don't allow this.
2078 Suppose that you can't telnet directly to ICS, but you can use rsh to run
2079 programs on a firewall host, and that host can telnet to ICS. Let's say the
2080 firewall is called rsh.wall.com. Set command-line options as
2084 xboard -ics -gateway rsh.wall.com -icshost chessclub.com
2087 Or in your \&.Xdefaults file:
2090 XBoard*gateway: rsh.wall.com
2091 XBoard*internetChessServerHost: chessclub.com
2096 in ICS mode, it will connect to the ICS by using rsh
2098 .I "telnet chessclub.com 5000"
2099 on host rsh.wall.com.
2101 Suppose that you can telnet anywhere you want, but you have to run a special
2106 First, we'll consider the easy case, in
2108 .I "ptelnet chessclub.com 5000"
2109 gets you to the chess server.
2110 In this case set command line options as follows:
2113 xboard -ics -telnet -telnetProgram ptelnet
2116 Or in your \&.Xdefaults file:
2119 XBoard*useTelnet: true
2120 XBoard*telnetProgram: ptelnet
2125 in ICS mode, it will issue the command
2126 .I "ptelnet chessclub.com 5000"
2127 to connect to the ICS.
2130 .I "ptelnet chessclub.com 5000"
2131 doesn't work; that is, your ptelnet program
2132 doesn't let you connect to alternative ports. In this case,
2133 you will have to find some other host outside the
2134 firewall that does let you do this, and hop through it. For instance, suppose
2135 you have an account at foo.edu. Set command line options as
2139 xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport ""
2142 Or in your \&.Xdefaults file:
2145 XBoard*useTelnet: true
2146 XBoard*telnetProgram: ptelnet
2147 XBoard*internetChessServerHost: foo.edu
2148 XBoard*internetChessServerPort:
2153 in ICS mode, it will issue the command
2154 .I "ptelnet foo.edu"
2155 to connect to your account at foo.edu. Log in there, then type
2156 .IR "telnet chessclub.com 5000" .
2158 ICC timestamp and FICS timeseal do not work through many
2159 firewalls. You can use them only if your firewall gives a clean TCP
2160 connection with a full 8-bit wide path. If your firewall allows you
2161 to get out only by running a special telnet program, you can't use
2162 timestamp or timeseal across it. But if you have access to a
2163 computer just outside your firewall, and you have much lower netlag
2164 when talking to that computer than to the ICS, it might be worthwhile
2165 running timestamp there. Follow the instructions above for hopping
2166 through a host outside the firewall (foo.edu in the example),
2167 but run timestamp or timeseal on that host instead of telnet.
2169 Suppose that you have a SOCKS firewall that requires you to go through
2170 some extra level of authentication, but after that will give you a
2171 clean 8-bit wide TCP connection to the chess server. In that case,
2172 you could make a socksified version of xboard
2173 and run that. If you are using timestamp or timeseal,
2174 you will need to socksify it, not
2176 this may be difficult seeing that ICC and FICS do not
2177 provide source code for these programs.
2178 Socksification is beyond the scope of this document, but
2179 see the SOCKS Web site at http://www.socks.nec.com/how2socksify.html.
2183 Game and position files
2184 are found in the directory named by the CHESSDIR environment
2185 variable. If this variable is not set, the current working
2189 actually changes its working directory to $CHESSDIR, so
2190 any files written by the chess engine will be placed there too.
2197 There is no way for two people running copies of
2199 to play each other without going through the Internet Chess Server.
2201 Under some circumstances, your ICS password may be echoed when you log on.
2203 If you are connecting to the ICS by running telnet, timestamp, or
2204 timeseal on an Internet provider
2205 or firewall host, you may find that each line you type is echoed back an extra
2206 time after you hit Return. If your Internet provider is a Unix system, you
2207 can probably turn its echo off by typing
2209 after you log in, and/or
2210 typing ^E-Return (control-E followed by the Return key) to the telnet
2211 program after you have logged into ICS. It is a good idea to do this if you
2212 can, because otherwise the extra echo can occasionally confuse
2216 The game parser recognizes only algebraic notation.
2218 The internal move legality tester does not look at the game history,
2219 so in some cases it misses illegal castling or en passant captures.
2220 It permits castling with the king on the d file because this is possible in
2221 some "wild 1" games on ICS.
2222 However, if you attempt an illegal move when using
2223 a chess engine or the ICS,
2225 will accept the error message that comes
2226 back, undo the move, and let you try another.
2228 Fischer Random castling is not understood. You can probably play
2229 Fischer Random chess successfully on ICS by typing castling moves into the ICS
2230 Interaction window, but they will not be animated correctly, and saved
2231 games will not be loaded correctly if castling occurs.
2233 FEN positions saved by xboard
2234 never include correct information about whether castling is legal or
2235 how many half-moves have been made since the last irreversible move,
2236 and sometimes may not correctly indicate when en passant capture is available.
2238 The mate detector does not understand that non-contact mate is not really mate
2239 in bughouse. The only problem this causes while playing is minor: a
2240 "#" (mate indicator) character will show up after a non-contact mating move in
2241 the move list; xboard will not assume the game is over at that point.
2242 However, if you are editing
2243 a game, Edit Game mode will be terminated by a non-contact mate.
2247 functions may not work with versions of GNU Chess earlier
2248 than 4.0, patchlevel 77,
2249 or with versions of Crafty earlier than 15.11.
2250 A few functions work with GNU Chess but not Crafty, or vice versa.
2252 The menus may not work if your keyboard is in Caps Lock or Num Lock mode.
2253 This seems to be a problem with the Athena menu widget, not an xboard bug.
2255 Also see the ToDo file included with the distribution for many other
2256 possible bugs, limitations, and ideas for improvement that have been suggested.
2257 .SH REPORTING PROBLEMS
2259 Report bugs and problems with xboard
2260 to <tim@tim-mann.org>.
2263 program to start a typescript, run xboard
2264 with the -debug option, and include the typescript output in your message.
2265 Also tell us what kind of machine and what operating system version
2266 you are using. The command "uname -a" will often tell you this.
2267 Here is a sample of approximately what you should type:
2276 mail tim@tim-mann.org
2277 Subject: Your short description of the problem
2278 Your detailed description of the problem
2285 please send a message about your changes,
2286 and we will get in touch with you about merging them in
2287 to the main line of development.
2288 .SH AUTHORS AND CONTRIBUTORS
2290 Tim Mann has been responsible for
2292 versions 1.3 and beyond, and for
2296 to Microsoft Win32 (Windows NT and Windows 95).
2299 contributed the initial (WinBoard-only) implementation
2300 of many new features added to both XBoard and WinBoard in version 4.1.0,
2301 including copy/paste, premove, icsAlarm, autoFlipView, training mode,
2302 auto raise, and blindfold.
2303 Ben Nye contributed X copy/paste code for XBoard.
2305 Hugh Fisher added animated piece movement to
2307 and Henrik Gram added it to WinBoard.
2308 Frank McIngvale added click/click moving, the Analysis modes, piece flashing,
2309 ZIICS import, and ICS text colorization to xboard.
2310 Jochen Wiedmann ported xboard
2311 to the Amiga, creating
2313 and converted the documentation to texinfo.
2314 Elmar Bartel contributed the new piece bitmaps for version 3.2.
2317 John Chanak contributed the initial implementation of ICS mode.
2318 The color scheme and the old 80x80 piece bitmaps were taken from
2323 Chris Sears and Dan Sears wrote the original
2325 they were responsible for versions 1.0 through 1.2.
2328 Copyright 1991 by Digital Equipment Corporation, Maynard, Massachusetts.
2329 Enhancements Copyright 1992-95 Free Software Foundation, Inc.
2331 XBoard's alternative piece bitmaps (bitmaps.xchess) are derived from the
2332 bitmaps in the XChess program, which was written and is copyrighted by Wayne
2335 The following terms apply to Digital Equipment Corporation's copyright
2341 Permission to use, copy, modify, and distribute this software and its
2342 documentation for any purpose and without fee is hereby granted,
2343 provided that the above copyright notice appear in all copies and that
2344 both that copyright notice and this permission notice appear in
2345 supporting documentation, and that the name of Digital not be
2346 used in advertising or publicity pertaining to distribution of the
2347 software without specific, written prior permission.
2349 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
2350 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
2351 DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
2352 ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
2353 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
2354 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
2358 The following terms apply to this enhanced version of XBoard distributed
2359 by the Free Software Foundation:
2362 This program is free software; you can redistribute it and/or modify
2363 it under the terms of the GNU General Public License as published by
2364 the Free Software Foundation; either version 2 of the License, or
2365 (at your option) any later version.
2367 This program is distributed in the hope that it will be useful,
2368 but WITHOUT ANY WARRANTY; without even the implied warranty of
2369 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2370 GNU General Public License for more details.
2372 You should have received a copy of the GNU General Public License
2373 along with this program; if not, write to the Free Software
2374 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2378 is a separate copyrighted work of Andy McFarland (Zek on ICC). Use
2381 falls under the ZIICS license, not the GPL.
projects / xboard.git / blob