These are the changes I had made in my source tree between 4.2.6 and
[xboard.git] /
1 .\" $Id$
2 .TH xboard 6 "$Date$" "GNU"
4 .PP
5 xboard \- X user interface for GNU Chess, Crafty, the Internet Chess Server (ICS),
6 and electronic mail correspondence chess.
8 .PP
9 To run with GNU Chess:
10 .B xboard [options]
11 .br
12 To run with Crafty:
13 .B xboard -fcp crafty -fd \fIcrafty's-directory\fB [options]
14 .br
15 To run with the ICS:
16 .B xboard -ics -icshost hostname [options]
17 .br
18 To play email chess: See
19 .BR cmail (6).
20 .br
21 To run standalone:
22 .B xboard -ncp [options]
23 .br
24 To use in a pipeline:
25 .B |pxboard
27 .PP
28 .BR xboard
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.
33 .PP
34 As an interface to GNU Chess or Crafty,
35 xboard
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.
40 .PP
41 As an interface to Crafty,
42 xboard
43 also lets you interactively analyze your stored games
44 or set up and analyze arbitrary positions.
45 .PP
46 As an interface to the Internet Chess Server (ICS),
47 .B xboard -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,
52 including bughouse.
53 .PP
54 As an interface to electronic mail correspondence chess,
55 xboard
56 works with the
57 .BR cmail (6)
58 program.  See its manual page for instructions.
59 .PP
60 You can also use
61 xboard
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
70 .BR "xboard -ncp" .
71 .PP
72 To view games from a netnews reader like
73 .BR rn (1)
74 or
75 .BR xrn (1),
76 use the news reader's Save command and specify "|pxboard"
77 as the save
78 file name.  This pipes the article to 
79 .BR pxboard ,
80 a simple shell script that saves the article to a temporary file and runs
81 xboard
82 in the background.  See the script itself for more information.
83 .PP
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.
89 .PP
90 When
91 xboard
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 
94 .B Iconize
95 below if you have problems getting this feature to work.
97 .PP
98 All 
99 xboard
100 commands are available on menus.  The most frequently used
101 commands also have shortcut keys or on-screen buttons.
102 .SH File Menu
103 .TP 8
104 .B Reset
105 Resets
106 xboard
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 
110 xboard,
111 then resynchronizes with ICS by sending a 
112 .IR refresh
113 command.
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.
117 .TP 8
118 .B Load Game
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 
126 .IR N th
127 game in the file directly from the file name dialog, by typing the number
128 .IR N 
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
136 xboard
137 position diagram
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; 
144 xboard
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.
151 .TP 8
152 .B Load Next Game
153 Loads the next game from the last game record file you loaded.
154 The shifted "N" key is a keyboard equivalent.
155 .TP 8
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.
160 .TP 8
161 .B Reload Same Game
162 Reloads the last game you loaded.
163 Not available if the last game was loaded from a pipe.
164 .TP 8
165 .B Save Game
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 
173 xboard.
174 Both formats are human-readable, and both can be read back by the Load Game 
175 command. 
176 Notation of the form "P@f7" is generated for piece-drops in bughouse games;
177 this is a nonstandard extension to PGN.
178 .TP 8
179 .B Copy Game
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.
186 .TP 8
187 .B Paste Game
188 Interprets the current X selection as a game record and loads it, as
189 with Load Game.
190 .TP 8
191 .B Load Position
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
195 to load the 
196 .IR N th
197 one, type the number 
198 .IR N 
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.
202 .TP 8
203 .B Load Next Position
204 Loads the next position from the last position file you loaded.
205 .TP 8
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.
209 .TP 8
210 .B Reload Same Position
211 Reloads the last position you loaded.
212 Not available if the last position was loaded from a pipe.
213 .TP 8
214 .B Save Position
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 
220 xboard.
221 Both formats can be read back by the Load Position command.
222 .TP 8
223 .B Copy Position
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.
230 .TP 8
231 .B Paste Position
232 Interprets the current X selection as a FEN position and loads it, as
233 with Load Position.
234 .TP 8
235 .B Mail Move
236 .PD 0
237 .TP 8
238 .B Reload CMail Message
239 See the manual page for
240 .BR cmail (6).
241 .PD
242 .TP 8
243 .B Exit
244 Exits from
245 xboard.
246 The shifted "Q" key is a keyboard equivalent.
247 .SH Mode Menu
248 .TP 8
249 .B Machine White
250 Tells the chess engine to play White.
251 .TP 8
252 .B Machine Black
253 Tells the chess engine to play Black.
254 .TP 8
255 .B Two Machines
256 Plays a game between two chess engines.
257 .TP 8
258 .B Analysis Mode
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.
265 .TP 8
266 .B Analyze File
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.
274 .TP 8
275 .B ICS Client
276 This is the normal mode when
277 .I xboard
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
282 option, and use the
283 terminal you started it from to type commands and receive text responses
284 from the chess server.  Useful ICS commands include
285 .IR who
286 to see who is logged on,
287 .IR games
288 to see what games are being played,
289 .IR match
290 to challenge another player to a game,
291 .IR observe
292 to observe an ongoing game,
293 .IR examine
294 or
295 .IR oldmoves
296 to review a recently completed game,
297 and of course
298 .IR help .
300 Some special 
301 xboard
302 features are activated when you are in 
303 .IR examine 
304 or
305 .IR bsetup
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.
321 .TP 8
322 .B Edit Game
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, 
330 or Two Machines.
332 In ICS mode, the moves are not sent to the ICS:
333 Edit Game takes 
334 xboard
335 out of ICS Client mode and lets you edit games locally.
336 If you want to edit
337 games on ICS in a way that other ICS users can see,
338 use the ICS
339 .IR examine
340 command or start an ICS match against yourself.
341 .TP 8
342 .B Edit Position
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 
352 xboard
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 
357 xboard
358 out of ICS Client mode and lets you edit positions locally.
359 If you want to edit
360 positions on ICS in a way that other ICS users can see,
361 use the ICS
362 .IR examine
363 command, or start an ICS match against yourself.  
364 (See also the ICS Client topic above.)
365 .TP 8
366 .B Training
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.
375 .TP 8
376 .B Show Game List
377 Shows or hides the list of games generated by the last Load Game command.
378 .TP 8
379 .B Edit Tags
380 Lets you edit the PGN (portable game notation)
381 tags for the current game.  After editing, the tags must still conform to
382 the PGN tag syntax:
384 .nf
385     <tag-section> ::= <tag-pair> <tag-section>
386                       <empty>
387     <tag-pair> ::= [ <tag-name> <tag-value> ]
388     <tag-name> ::= <identifier>
389     <tag-value> ::= <string>
390 .fi
392 See the PGN Standard for full details.  Here is an example:
394 .nf
395     [Event "Portoroz Interzonal"]
396     [Site "Portoroz, Yugoslavia"]
397     [Date "1958.08.16"]
398     [Round "8"]
399     [White "Robert J. Fischer"]
400     [Black "Bent Larsen"]
401     [Result "1-0"]
402 .fi
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
407 xboard
408 with "?" (unknown value), or "-" (inapplicable value).
409 .TP 8
410 .B Edit Comment
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.
413 .TP 8
414 .B ICS Input Box
415 If this mode is on in ICS mode,
416 xboard
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.
421 .TP 8
422 .B Pause
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 
437 .IR examine
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 
444 game stops loading.
445 You can load more moves manually by selecting Forward, or resume automatic
446 loading by selecting Pause again.
447 .SH Action Menu
448 .TP 8
449 .B Accept
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.
453 .TP 8
454 .B Decline
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.
458 .TP 8
459 .B Call Flag
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.
463 .TP 8
464 .B Draw
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.
468 .TP 8
469 .B Adjourn
470 Asks your opponent to agree to adjourning the current game, or
471 agrees to a pending adjournment offer from your opponent.
472 .TP 8
473 .B Abort
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.
477 .TP 8
478 .B Resign
479 Resigns the game to your opponent.  The shifted "R" key is a keyboard
480 equivalent. 
481 .TP 8
482 .B Stop Observing
483 Ends your participation in observing a game, by issuing the ICS
484 .IR observe
485 command with no arguments.
486 .TP 8
487 .B Stop Examining
488 Ends your participation in examining a game, by issuing the ICS
489 .IR unexamine
490 command.
491 .SH Step Menu
492 .TP 8
493 .B Backward
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 
508 xboard
509 is in Pause mode.
510 If Pause mode is off, Backward issues the ICS 
511 .IR backward
512 command, which
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.
515 .TP 8
516 .B Forward
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 
523 xboard
524 is in Pause mode.
525 If Pause mode is off, Forward issues the ICS 
526 .IR forward
527 command, which
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.
531 .TP 8
532 .B Back to Start
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
540 Start in any
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 
547 xboard
548 is in Pause mode.
549 If Pause mode is off, Back to Start issues the ICS 
550 .I backward 999999
551 command, which
552 backs up everyone's view of the game to the start and allows you to make
553 different moves.
554 If Pause mode is on, Back to Start only backs up your local view.
555 .TP 8
556 .B Forward to End
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 
562 xboard
563 is in Pause mode.
564 If Pause mode is off, Forward to End issues the ICS 
565 .I forward 999999
566 command, which moves everyone's view of the game forward to the end
567 of the current line.  
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.
570 .TP 8
571 .B Revert
572 If you are examining a game on ICS and Pause mode is off, 
573 issues the ICS command
574 .IR revert .
575 .TP 8
576 .B Truncate Game
577 Discards all remembered moves of the game beyond the current position.
578 Puts 
579 xboard
580 into Edit Game mode if it was not there already.
581 .TP 8
582 .B Move Now
583 Forces the chess engine to move immediately.  May not work with all
584 chess engines.
585 .TP 8
586 .B Retract Move
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 
591 .I takeback 1
592 or
593 .I takeback 2
594 depending on whether it is your opponent's move or yours.
595 .SH Options Menu
596 .TP 8
597 .B Always Queen
598 If this option is off,
599 xboard
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.
604 .TP 8
605 .B Animate Dragging
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. 
611 .TP 8
612 .B Animate Moving
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.
618 .TP 8
619 .B Auto Comment
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,
624 and
625 .I kibitz.
626 Limitation: remarks that you type yourself are not recognized;
627 xboard
628 scans only the output from ICS, not the input you type to it.
629 .TP 8
630 .B Auto Flag
631 If this option is on and one player runs out of time
632 before the other,
633 xboard
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,
638 xboard
639 may call either player's flag and will not take material into account.
640 .TP 8
641 .B Auto Flip View
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.
645 .TP 8
646 .B Auto Observe
647 If this option is on and you add a player to your 
648 .IR gnotify
649 list on ICS,
650 xboard
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
653 one starts.
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
658 your ICS 
659 .IR highlight
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.
663 .TP 8
664 .B Auto Raise Board
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.
667 .TP 8
668 .B Auto Save
669 If this option is on, at the end of every game
670 xboard
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.
674 .TP 8
675 .B Blindfold
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.
680 .TP 8
681 .B Flash Moves
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.
685 .TP 8
686 .B Flip View
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.
691 If you are
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
698 from bottom to top.
699 .TP 8
700 .B Get Move List
701 If this option is on, whenever
702 xboard
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
710 and over.
711 When you turn this option on from the menu,
712 xboard
713 immediately fetches the move list of the current game (if any).
714 .TP 8
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.
720 .TP 8
721 .B Move Sound
722 If this option is on,
723 xboard
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
733 xboard
734 with the Internet Chess Server, you will probably want to
735 give the 
736 .I "set bell 0"
737 command to the ICS, since otherwise the ICS
738 will ring the terminal bell after every move.
739 .TP 8
740 .B ICS Alarm
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
747 below.
748 .TP 8
749 .B Old Save Style
750 If this option is off,
751 xboard
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
755 xboard
756 is used instead.  The old position style is more human-readable than
757 FEN; the old game style has no particular advantages.
758 .TP 8
759 .B Periodic Updates
760 If this option is off (or if
761 you are using a chess engine that does not support periodic updates),
762 the analysis window
763 will be updated only when the analysis changes. If this option is
764 on, the Analysis Window will be updated every two seconds.
765 .TP 8
766 .B Ponder Next Move
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.
770 .TP 8
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.
776 .TP 8
777 .B Popup Move Errors
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.
784 .TP 8
785 .B Premove
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
794 entirely.
795 .TP 8
796 .B Quiet Play
797 If this option is on,
798 xboard
799 will automatically issue an ICS 
800 .I "set shout 0"
801 command whenever you start an ICS
802 game and a 
803 .I "set shout 1"
804 command whenever you finish one.  Thus you 
805 will not be distracted by shouts from other ICS users while playing.
806 .TP 8
807 .B Show Coords
808 If this option is on,
809 xboard
810 displays algebraic coordinates along the board's left and bottom edges.
811 .TP 8
812 .B Show Thinking
813 If this option is on, the chess engine's notion of the score and best
814 line of play
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.
822 .TP 8
823 .B Test Legality
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 
832 xboard
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.)
836 .SH Help Menu
837 .TP 8
838 .B Info XBoard
839 Displays the xboard
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 must either be present in the current 
843 working directory, or have been installed by 
844 the 
845 .I "make install"
846 command when you built 
847 xboard.
848 .TP 8
849 .B Man XBoard
850 Displays this man page in a new window.  For this feature to work,
851 the file xboard.6 must have been installed by 
852 the
853 .I "make install"
854 command when you built 
855 xboard,
856 and the
857 directory it was placed in must be on the search path for your system's
858 .BR man (1)
859 command.
860 .TP 8
861 .B Hint
862 Displays a move hint from the local chess engine.
863 .TP 8
864 .B Book
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.
871 .TP 8
872 .B About XBoard
873 Shows the current 
874 xboard
875 version number.
876 .SH Other shortcut keys
877 .TP 8
878 .B Iconize
879 Pressing the i or c key iconizes
880 xboard.
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 
885 .BR mwm (1),
886 add these lines to your \&.Xdefaults file and restart mwm:
888 .nf
889     Mwm*iconDecoration: activelabel label image
890     Mwm*XBoard*iconImageBackground: White
891     Mwm*XBoard*iconImageForeground: Black
892 .fi
894 The first line above enables graphical icons in 
895 .BR mwm ;
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 
899 xboard;
900 you have to set them in your \&.Xdefaults.
901 .PP
902 You can add or remove
903 xboard
904 shortcut keys
905 using the X resource 
906 .IR form.translations .
907 Here is an example of what would go in your \&.Xdefaults file:
909 .nf
910     XBoard*form.translations: \\
911         Shift<Key>?: AboutGameProc() \\n \\
912         <Key>y: AcceptProc() \\n \\
913         <Key>n: DeclineProc() \\n \\
914         <Key>i: NothingProc()
915 .fi
917 Binding a key to NothingProc makes it do nothing, thus removing it as a
918 shortcut key.
919 The 
920 xboard
921 functions that can be bound to keys are: 
923 .nf
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
950 TwoMachinesProc.
951 .fi
953 .PP
954 This section documents the command-line options to 
955 xboard.
956 You can set these options in two ways: by typing them on the shell
957 command line you use to start
958 xboard,
959 or by setting them as X resources (typically in your \&.Xdefaults file).
960 Many of the options cannot be changed while
961 xboard
962 is running; others set the initial state of items
963 that can be changed with the Options menu.
964 .PP
965 Most of the 
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
970 True), or give
971 just the short name to turn the option on
972 .RI ( -opt ),
973 or the short name preceded by "x" to turn the option off
974 .RI ( - x opt ).
975 For options that take strings or numbers as values, you can use the long or
976 short option names interchangeably.
977 .PP
978 Each option corresponds to an X resource
979 with the same name, so if you like, you can set options in your
980 .IR \&.Xdefaults
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
984 recognized.
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 :
988 True).
989 .SH Chess Engine Options
990 All of these options apply to both the GNU Chess and Crafty
991 chess engines.
992 .TP 8
993 .B -tc \fRor\fB -timeControl minutes[:seconds]
994 Each player begins with his clock set to the timeControl period.
995 Default: 5 minutes.
996 The additional options movesPerSession and timeIncrement are mutually
997 exclusive.  
998 .TP 8
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.
1002 .TP 8
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
1006 added to his clock.  
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.
1010 .TP 8
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.
1017 .TP 8
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.
1024 .TP 8
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.
1031 With the option,
1032 the engine will cut off its search early if it reaches the specified depth.
1033 .TP 8
1034 .B -thinking/-xthinking \fRor\fB -showThinking True/False
1035 Sets the Show Thinking menu option.  Default: False.
1036 .TP 8
1037 .B -ponder/-xponder \fRor\fB -ponderNextMove True/False
1038 Sets the Ponder Next Move menu option. Default: True.
1039 .TP 8
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, 
1044 xboard
1045 starts each game with the given opening moves or the given position; 
1046 otherwise, the games start with the standard initial chess position.
1047 If the saveGameFile 
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, 
1054 xboard
1055 displays the match score and exits.  Default: 0 (do not run a match).
1056 .TP 8
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.
1060 .TP 8
1061 .B -fcp \fRor\fB -firstChessProgram program
1062 Name of first chess engine.
1063 Default:
1064 .IR gnuchessx .
1065 .TP 8
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.
1069 Default:
1070 .IR gnuchessx .
1071 .TP 8
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
1075 xboard.)
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.
1079 .TP 8
1080 .B -fh \fRor\fB -firstHost host
1081 .PD 0
1082 .TP 8
1083 .B -sh \fRor\fB -secondHost host
1084 Hosts on which the chess engines are to be run.
1085 The default for each is 
1086 .IR localhost .
1087 If you specify another host, 
1088 xboard
1089 uses 
1090 .BR rsh (1)
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.)
1094 .PD
1095 .TP 8
1096 .B -fd \fRor\fB -firstDirectory dir
1097 .PD 0
1098 .TP 8
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 
1103 xboard
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.
1108 .PD
1109 .TP 8
1110 .B -initString string
1111 .PD 0
1112 .TP 8
1113 .B -secondInitString string
1114 The string that is sent to initialize each chess engine for a new game.
1115 Default:
1116 .nf
1117     new
1118     random
1119 .fi
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 
1129 .I new
1130 command; it is required by all chess engines to start a new game.
1132 You can remove the 
1133 .I random
1134 command if you
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.  
1137 Even without 
1138 .IR random ,
1139 GNU Chess
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.
1145 .PD
1146 .TP 8
1147 .B -firstComputerString string
1148 .PD 0
1149 .TP 8
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.
1155 .PD
1156 .TP 8
1157 .B -reuse/-xreuse \fRor\fB -reuseFirst True/False
1158 .PD 0
1159 .TP 8
1160 .B -reuse2/-xreuse2 \fRor\fB -reuseSecond True/False
1161 If the option is False,
1162 xboard
1163 kills off the chess engine after every game and starts it again
1164 for the next game.  
1165 If the option is True (the default), 
1166 xboard
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.
1172 .PD
1173 .TP 8
1174 .B -firstProtocolVersion version-number
1175 .PD 0
1176 .TP 8
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.
1183 .PD
1184 .SH Internet Chess Server Options
1185 .TP 8
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.
1190 .TP 8
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:
1195 See the file 
1196 .I ics-addresses
1197 in the 
1198 xboard
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).
1204 At this writing,
1205 is and (formerly
1206 is
1207 .TP 8
1208 .B -icsport \fRor\fB -internetChessServerPort port-number
1209 The port number to use when connecting to a chess server in ICS mode.
1210 Default: 5000.
1211 .TP 8
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 ( or
1215 "timeseal" for FICS (,, 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".
1219 .TP 8
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
1223 xboard 
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),
1227 xboard
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.
1232 .TP 8
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 
1237 .IR telnet .
1238 The telnet program 
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
1242 useful. 
1243 .TP 8
1244 .B -gateway host-name
1245 If this option is set to a host name,
1246 xboard
1247 communicates with the Internet Chess Server by using
1248 .BR rsh (1)
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
1255 useful. 
1256 .TP 8
1257 .B -internetChessServerCommPort \fRor\fB -icscomm dev-name
1258 If this option is set, 
1259 xboard
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 
1269 xboard
1270 is minimal.  You need to set all communication parameters and tty modes
1271 before you enter
1272 xboard.
1274 Use a script something like this:
1276 .nf
1277     stty raw -echo 9600 > /dev/tty00
1278     xboard -ics -icscomm /dev/tty00
1279 .fi
1281 Here replace 
1282 .IR /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
1286 man pages for 
1287 .BR stty (1)
1288 and
1289 .BR tty (4)
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.
1297 .nf
1298     ##################################################
1299     #!/bin/sh -f
1300     # configure modem and fire up xboard
1302     # configure modem
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     ##################################################
1309 .fi
1311 After you start
1312 xboard
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 5000" .
1317 Important: See the paragraph in the LIMITATIONS section below 
1318 about extra echoes.
1319 .TP 8
1320 .B -icslogon \fRor\fB -internetChessServerLogonScript file-name
1321 Whenever
1322 xboard
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 
1327 .IR .icsrc .
1328 Usually the first two lines of the file should be your ICS user name
1329 and password.
1330 The file can be either in $CHESSDIR, in 
1331 xboard's
1332 working directory if CHESSDIR is not set, or in your home directory.
1333 .TP 8
1334 .B -msLoginDelay delay
1335 If you experience trouble logging onto an ICS using the
1336 .B -icslogon
1337 option, inserting some delay between characters of the login
1338 script may help. This option inserts
1339 .B delay
1340 milliseconds of delay per character. Good values to
1341 try are 100 and 250.
1342 .TP 8
1343 .B -icsinput/-xicsinput \fRor\fB -internetChessServerInputBox True/False
1344 Sets ICS Input Box on the mode menu.  Default: False.
1345 .TP 8
1346 .B -autocomm/-xautocomm \fRor\fB -autoComment True/False
1347 Sets the Auto Comment menu option.  Default: False.
1348 .TP 8
1349 .B -autoflag/-xautoflag \fRor\fB -autoCallFlag True/False
1350 Sets the Auto Flag menu option.  Default: False.
1351 .TP 8
1352 .B -autobs/-xautobs \fRor\fB -autoObserve True/False
1353 Sets the Auto Observe menu option.  Default: False.
1354 .TP 8
1355 .B -moves/-xmoves \fRor\fB -getMoveList True/False
1356 Sets the Get Move List menu option.  Default: True.
1357 .TP 8
1358 .B -alarm/-xalarm \fRor\fB -icsAlarm True/False
1359 Sets the ICS Alarm menu option.  Default: True.
1360 .TP 8
1361 .B -icsAlarmTime ms
1362 Sets the time in milliseconds for the ICS Alarm menu option.  Default: 5000.
1363 .TP 8
1364 .B -pre/-xpre \fRor\fB -premove True/False
1365 Sets the Premove menu option.  Default: True.
1366 .TP 8
1367 .B -quiet/-xquiet \fRor\fB -quietPlay True/False
1368 Sets the Quiet Play menu option.  Default: False.
1369 Default: False.
1370 .TP 8
1371 .B -colorize/-xcolorize \fRor\fB -colorizeMessages TrueFalse
1372 Setting
1373 .I colorizeMessages
1374 to True causes 
1375 xboard
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.
1379 .TP 8
1380 .B -colorShout foreground,background,bold
1381 .PD 0
1382 .TP 8
1383 .B -colorSShout foreground,background,bold
1384 .TP 8
1385 .B -colorChannel foreground,background,bold
1386 .TP 8
1387 .B -colorKibitz foreground,background,bold
1388 .TP 8
1389 .B -colorTell foreground,background,bold
1390 .TP 8
1391 .B -colorChallenge foreground,background,bold
1392 .TP 8
1393 .B -colorRequest foreground,background,bold
1394 .TP 8
1395 .B -colorSeek foreground,background,bold
1396 .TP 8
1397 .B -colorNormal foreground,background,bold
1398 .PD
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.
1415 .nf
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
1427 .fi
1428 .TP 8
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.
1437 .TP 8
1438 .B -soundShout filename
1439 .PD 0
1440 .TP 8
1441 .B -soundSShout filename
1442 .TP 8
1443 .B -soundChannel filename
1444 .TP 8
1445 .B -soundKibitz filename
1446 .TP 8
1447 .B -soundTell filename
1448 .TP 8
1449 .B -soundChallenge filename
1450 .TP 8
1451 .B -soundRequest filename
1452 .TP 8
1453 .B -soundSeek filename
1454 .PD
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.
1458 .TP 8
1459 .B -soundMove filename
1460 This sound is used by the Move Sound menu option.  Default: "$".
1461 .TP 8
1462 .B -soundIcsAlarm filename
1463 This sound is used by the ICS Alarm menu option.  Default: "$".
1464 .TP 8
1465 .B -soundIcsWin filename
1466 This sound is played when you win an ICS game.  Default: "" (no sound).
1467 .TP 8
1468 .B -soundIcsLoss filename
1469 This sound is played when you lose an ICS game.  Default: "" (no sound).
1470 .TP 8
1471 .B -soundIcsDraw filename
1472 This sound is played when you draw an ICS game.  Default: "" (no sound).
1473 .TP 8
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
1477 sound).
1479 Here is an example of how to set the sounds in your \&.Xdefaults file.
1481 .nf
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
1497 .fi
1498 .SH Load and Save Options
1499 .TP 8
1500 .B -lgf \fRor\fB -loadGameFile file
1501 .PD 0
1502 .TP 8
1503 .B -lgi \fRor\fB -loadGameIndex index
1504 If the loadGameFile option is set,
1505 xboard
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,
1509 xboard
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
1513 .IR N ,
1514 the menu is suppressed and
1515 the
1516 .IR N th
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
1521 .BR pxboard
1522 shell script if you want to pipe files containing multiple games into
1523 xboard 
1524 and still see the menu.
1525 .PD
1526 .TP 8
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
1531 xboard
1532 not to step through game files automatically.
1533 Default: 1 second.
1534 .TP 8
1535 .B -sgf \fRor\fB -saveGameFile file
1536 If this option is set, 
1537 xboard 
1538 appends a record of every game played to the specified file.
1539 The file name "-" specifies the standard output.
1540 .TP 8
1541 .B -autosave/-xautosave \fRor\fB -autoSaveGames True/False
1542 Sets the Auto Save menu option.
1543 Ignored if saveGameFile is set.
1544 Default: False.
1545 .TP 8
1546 .B -lpf \fRor\fB -loadPositionFile file
1547 .PD 0
1548 .TP 8
1549 .B -lpi \fRor\fB -loadPositionIndex index
1550 If the loadPositionFile option is set,
1551 xboard
1552 loads the specified position file at startup.
1553 The file name "-" specifies the standard input.
1554 If the loadPositionIndex option is set to 
1555 .IR N ,
1556 the
1557 .IR N th
1558 position found in the file is loaded; otherwise the first position is loaded.
1559 .PD
1560 .TP 8
1561 .B -spf \fRor\fB -savePositionFile file
1562 If this option is set, 
1563 xboard 
1564 appends the final position reached in
1565 every game played to the specified file.
1566 The file name "-" specifies the standard output.
1567 .TP 8
1568 .B -oldsave/-xoldsave \fRor\fB -oldSaveStyle True/False
1569 Sets the Old Save Style menu option.  Default: False.
1570 .SH User Interface Options
1571 .TP 8
1572 .B standard Xt options
1573 xboard
1574 accepts standard Xt options like -display, -geometry, and -iconic.
1575 .TP 8
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
1579 for this option.
1580 .TP 8
1581 .B -exit/-xexit \fRor\fB -popupExitMessage True/False
1582 Sets the Popup Exit Message menu option.  Default: True.
1583 .TP 8
1584 .B -popup/-xpopup \fRor\fB -popupMoveErrors True/False
1585 Sets the Popup Move Errors menu option.  Default: False.
1586 .TP 8
1587 .B -queen/-xqueen \fRor\fB -alwaysPromoteToQueen True/False
1588 Sets the Always Queen menu option.  Default: False.
1589 .TP 8
1590 .B -legal/-xlegal \fRor\fB -testLegality True/False
1591 Sets the Test Legality menu option.  Default: True.
1592 .TP 8
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,
1600 or Tiny 21x21.
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
1603 options.
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 
1613 .IR clockFont ,
1614 n4 the desired size for the 
1615 .IR coordFont ,
1616 n5 the desired size for the default
1617 .IR font ,
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 
1623 .I titleInWindow
1624 is True, 
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.
1628 .TP 8
1629 .B -coords/-xcoords \fRor\fB -showCoords True/False
1630 Sets the Show Coords menu option.  Default: False.
1631 The
1632 .IR coordFont
1633 option specifies what font to use.  
1634 .TP 8
1635 .B -autoraise/-xautoraise \fRor\fB -autoRaiseBoard True/False
1636 Sets the Auto Raise Board menu option.  Default: True.
1637 .TP 8
1638 .B -autoflip/-xautoflip \fRor\fB -autoFlipView True/False
1639 Sets the Auto Flip View menu option.  Default: True.
1640 .TP 8
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
1648 the game starts.
1649 .TP 8
1650 .B -title/-xtitle \fRor\fB -titleInWindow True/False
1651 If this option is True, 
1652 xboard
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.
1658 .TP 8
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.
1664 .TP 8
1665 .B -mono/-xmono \fRor\fB -monoMode True/False
1666 Determines whether
1667 xboard
1668 displays its pieces and squares with two colors (True) or four (False).
1669 You shouldn't have to specify monoMode;
1670 xboard
1671 will determine if it is necessary.
1672 .TP 8
1673 \fB\-flashCount\fP \fIcount\fP
1674 .PD 0
1675 .TP 8
1676 \fB\-flashRate\fP \fIrate\fP
1677 .TP 8
1678 \fB\-flash\fP
1679 .TP 8
1680 \fB\-xflash\fP
1681 These options enable flashing of pieces when they
1682 land on their destination square.
1683 .B flashCount
1684 tells XBoard how many times to flash a piece after it
1685 lands on its destination square.
1686 .B flashRate
1687 controls the rate of flashing (flashes/sec).
1688 Abbreviations:
1689 .B flash
1690 sets flashCount to 3.
1691 .B xflash
1692 sets flashCount to 0.
1693 Defaults:  flashCount=0 (no flashing), flashRate=5.
1694 .PD
1695 .TP 8
1696 .B -highlight/-xhighlight \fRor\fB -highlightLastMove True/False
1697 Sets the Highlight Last Move menu option. Default: False.
1698 .TP 8
1699 .B -blind/-xblind \fRor\fB -blindfold True/False
1700 Sets the Blindfold menu option.  Default: False.
1701 .TP 8
1702 .B -clockFont font
1703 The font used for the clocks.
1704 If the option
1705 value is a pattern that does not specify the font size, 
1706 xboard
1707 tries to choose an appropriate font for the board size being used.
1708 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
1709 .TP 8
1710 .B -coordFont font
1711 The font used for rank and file coordinate labels if 
1712 .IR showCoords
1713 is True.
1714 If the option
1715 value is a pattern that does not specify the font size, 
1716 xboard
1717 tries to choose an appropriate font for the board size being used.
1718 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
1719 .TP 8
1720 .B -font font
1721 The font used for popup dialogs, menus, comments, etc.
1722 If the option
1723 value is a pattern that does not specify the font size, 
1724 xboard
1725 tries to choose an appropriate font for the board size being used.
1726 Default: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*.
1727 .TP 8
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.
1736 .TP 8
1737 .B -bm \fRor\fB -bitmapDirectory dir
1738 .PD 0
1739 .TP 8
1740 .B -pixmap \fRor\fB -pixmapDirectory dir
1741 .PD
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
1750 through them.
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 "".
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 "", "", and
1780 "".
1782 You can import pixmap pieces from the
1783 .B ZIICS
1784 distribution by using the 
1785 .B zic2xpm
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:
1790 .sp
1791 1) Download the ZIICS distribution. It is available from
1793 .nf
1795 .fi
1796 .sp
1797 2) Unzip it into a directory, for example:
1799 .nf
1800       unzip -L ziics131.exe -d ~/ziics
1801 .fi
1802 .sp
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
1805 .B zic2xpm
1806 program to create the pieces:
1808 .nf
1809       mkdir ~/fritz4
1810       cd ~/fritz4
1811       zic2xpm ~/ziics/fritz4.*
1812 .fi
1813 .sp
1814 (The
1815 .B zic2xpm
1816 program is in the directory where 
1817 xboard
1818 was compiled,
1819 in case you didn't do a 
1820 .IR "make install" .)
1821 .sp
1822 4) Now, just add the
1823 .B -pixmapDirectory
1824 option when you start
1825 xboard:
1827 .nf
1828      xboard -pixmapDirectory ~/fritz4
1829 .fi
1830 .sp
1831 Or add the option to your .Xdefaults file:
1833 .nf
1834      xboard*pixmapDirectory: ~/fritz4
1835 .fi
1836 .TP 8
1837 .B -whitePieceColor color
1838 .PD 0
1839 .TP 8
1840 .B -blackPieceColor color
1841 .TP 8
1842 .B -lightSquareColor color
1843 .TP 8
1844 .B -darkSquareColor color
1845 .TP 8
1846 .B -highlightSquareColor color
1847 .TP 8
1848 .B -premoveHighlightColor color
1849 .PD
1850 Colors to use for the pieces, squares, and square highlights.
1851 Defaults:
1853 .nf
1854     -whitePieceColor       #FFFFCC
1855     -blackPieceColor       #202020
1856     -lightSquareColor      #C8C365
1857     -darkSquareColor       #77A26D
1858     -highlightSquareColor  #FFFF00
1859     -premoveHighlightColor #FF0000
1860 .fi
1862 If you are using a grayscale monitor, try setting the colors to:
1864 .nf
1865     -whitePieceColor       gray100
1866     -blackPieceColor       gray0
1867     -lightSquareColor      gray80
1868     -darkSquareColor       gray60
1869     -highlightSquareColor  gray100
1870     -premoveHighlightColor gray70
1871 .fi
1872 .TP 8
1873 .B -drag/-xdrag \fRor\fB -animateDragging True/False
1874 Sets the Animate Dragging menu option. Default: True.
1875 .TP 8
1876 .B -animate/-xanimate \fRor\fB -animateMoving True/False
1877 Sets the Animate Moving menu option. Default: True.
1878 .TP 8
1879 .B -animateSpeed n
1880 Number of milliseconds delay between each animation frame when Animate
1881 Moves is on.
1882 .SH Other Options
1883 .TP 8
1884 .B -ncp/-xncp \fRor\fB -noChessProgram True/False
1885 If this option is True,
1886 xboard
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.
1890 Default: False.
1891 .TP 8
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.
1899 .TP 8
1900 .B -variant varname
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:
1905 .nf
1906   normal        Normal chess
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
1921 .fi
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.
1931 .TP 8
1932 .B -debug/-xdebug \fRor\fB -debugMode True/False
1933 Turns on debugging printout.
1934 .TP 8
1935 .B -rsh \fRor\fB -remoteShell shell-name
1936 Name of the command used to run programs remotely.  
1937 The default is 
1938 .I rsh
1939 or
1940 .IR remsh ,
1941 determined when
1942 xboard
1943 is configured and compiled.
1944 .TP 8
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.
1949 .PP
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:
1957 .sp
1958 .RS +.6i
1959 .ti -4
1960 .B Analyzing a stored game (PGN, etc):
1961 Choose
1962 .I Analyze File
1963 from the
1964 .I Mode Menu.
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.
1970 .sp
1971 .ti -4
1972 .B Setting up a position to analyze
1973 Choose
1974 .I Edit Position
1975 from the
1976 .I Mode Menu.
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 
1980 xboard
1981 whose turn it is
1982 to move. Choose
1983 .I Analysis Mode
1984 from the
1985 .I Mode Menu.
1986 Watch the analysis, move pieces around, etc.
1987 .sp
1988 .ti -4
1989 .B Analyzing a new game
1990 If you want to start a new analysis from a fresh board,
1991 choose
1992 .I Reset Game
1993 from the
1994 .I File Menu,
1995 then choose
1996 .I Analysis Mode
1997 from the
1998 .I Mode Menu.
1999 Now you can move pieces around and watch the engine's analysis.
2000 .RE
2002 .PP
2003 Crafty is a chess engine written by Bob Hyatt (
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
2006 for you.
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:
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.
2021 .nf
2022     xboard -fcp crafty -fd \fIcrafty's-directory\fR
2023 .fi
2025 .PP
2026 By default,
2027 .B xboard -ics
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
2032 xboard.
2033 Important: See the paragraph in the LIMITATIONS section below 
2034 about extra echoes.
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  Set command-line options as
2039 follows: 
2041 .nf
2042     xboard -ics -icshost -icsport 23
2043 .fi
2045 Or in your \&.Xdefaults file:
2047 .nf
2048     XBoard*internetChessServerHost:
2049     XBoard*internetChessServerPort: 23
2050 .fi
2052 Then when you run
2053 xboard
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 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  Follow the recipe above, but
2064 instead of typing 
2065 .I "telnet 5000"
2066 to the firewall, type 
2067 .I "telnet" 
2068 (or 
2069 .IR "rlogin" ),
2070 log in there, and
2071 then type 
2072 .IR "telnet 5000" .
2074 Exception: 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  Set command-line options as
2081 follows: 
2083 .nf
2084     xboard -ics -gateway -icshost
2085 .fi
2087 Or in your \&.Xdefaults file:
2089 .nf
2090     XBoard*gateway:
2091     XBoard*internetChessServerHost:
2092 .fi
2094 Then when you run
2095 xboard
2096 in ICS mode, it will connect to the ICS by using rsh
2097 to run the command 
2098 .I "telnet 5000" 
2099 on host
2101 Suppose that you can telnet anywhere you want, but you have to run a special
2102 program called 
2103 .BR ptelnet
2104 to do so.  
2106 First, we'll consider the easy case, in
2107 which 
2108 .I "ptelnet 5000"
2109 gets you to the chess server.  
2110 In this case set command line options as follows:
2112 .nf
2113     xboard -ics -telnet -telnetProgram ptelnet
2114 .fi
2116 Or in your \&.Xdefaults file:
2118 .nf
2119     XBoard*useTelnet: true
2120     XBoard*telnetProgram: ptelnet
2121 .fi
2123 Then when you run
2124 xboard
2125 in ICS mode, it will issue the command 
2126 .I "ptelnet 5000"
2127 to connect to the ICS.
2129 Next, suppose that 
2130 .I "ptelnet 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  Set command line options as
2136 follows:
2138 .nf
2139     xboard -ics -telnet -telnetProgram ptelnet -icshost -icsport ""
2140 .fi
2142 Or in your \&.Xdefaults file:
2144 .nf
2145     XBoard*useTelnet: true
2146     XBoard*telnetProgram: ptelnet
2147     XBoard*internetChessServerHost:
2148     XBoard*internetChessServerPort:
2149 .fi
2151 Then when you run
2152 xboard
2153 in ICS mode, it will issue the command 
2154 .I "ptelnet"
2155 to connect to your account at  Log in there, then type
2156 .IR "telnet 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 ( 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
2175 xboard;
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
2182 .PP
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
2186 directory is used.
2187 If CHESSDIR is set,
2188 xboard
2189 actually changes its working directory to $CHESSDIR, so
2190 any files written by the chess engine will be placed there too.
2192 .PP
2193 .BR gnuchess (6),
2194 .BR cmail (6).
2196 .PP
2197 There is no way for two people running copies of
2198 xboard
2199 to play each other without going through the Internet Chess Server.  
2200 .PP
2201 Under some circumstances, your ICS password may be echoed when you log on.
2202 .PP
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 
2208 .I "stty -echo"
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
2213 xboard's
2214 parsing routines.
2215 .PP
2216 The game parser recognizes only algebraic notation.
2217 .PP
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,
2224 xboard
2225 will accept the error message that comes
2226 back, undo the move, and let you try another.
2227 .PP
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.
2232 .PP
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.
2237 .PP
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.
2244 .PP
2245 Some
2246 xboard
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.
2251 .PP
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.
2254 .PP
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.
2258 .PP
2259 Report bugs and problems with xboard
2260 to <>.
2261 Please use the 
2262 .BR script (1)
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:
2269 .nf
2270     script
2271     uname -a
2272     ./configure
2273     make
2274     ./xboard -debug
2275     exit
2276     mail
2277     Subject: Your short description of the problem
2278     Your detailed description of the problem
2279     ~r typescript
2280     .
2281 .fi
2283 If you improve 
2284 xboard,
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.
2289 .PP
2290 Tim Mann has been responsible for 
2291 xboard
2292 versions 1.3 and beyond, and for
2293 .BR WinBoard ,
2294 a port of
2295 xboard
2296 to Microsoft Win32 (Windows NT and Windows 95).
2297 .PP
2298 Mark Williams 
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.
2304 .PP
2305 Hugh Fisher added animated piece movement to
2306 xboard,
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
2312 .BR AmyBoard ,
2313 and converted the documentation to texinfo.
2314 Elmar Bartel contributed the new piece bitmaps for version 3.2.
2315 Evan Welsh wrote
2316 .BR cmail.
2317 John Chanak contributed the initial implementation of ICS mode.
2318 The color scheme and the old 80x80 piece bitmaps were taken from
2319 Wayne Christopher's 
2320 .BR XChess
2321 program.
2322 .PP
2323 Chris Sears and Dan Sears wrote the original 
2324 xboard;
2325 they were responsible for versions 1.0 through 1.2.
2327 .PP
2328 Copyright 1991 by Digital Equipment Corporation, Maynard, Massachusetts.
2329 Enhancements Copyright 1992-95 Free Software Foundation, Inc.
2330 .PP
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
2333 Christopher. 
2334 .PP
2335 The following terms apply to Digital Equipment Corporation's copyright
2336 interest in XBoard:
2337 .PP
2338 .RS
2339 All Rights Reserved
2340 .PP
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.
2348 .PP
2356 .RE
2357 .PP
2358 The following terms apply to this enhanced version of XBoard distributed
2359 by the Free Software Foundation:
2360 .PP
2361 .RS
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.
2366 .PP
2367 This program is distributed in the hope that it will be useful,
2368 but WITHOUT ANY WARRANTY; without even the implied warranty of
2370 GNU General Public License for more details.
2371 .PP
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.
2375 .RE
2376 .PP
2377 .BR ZIICS
2378 is a separate copyrighted work of Andy McFarland (Zek on ICC). Use
2379 of
2380 .BR ZIICS
2381 falls under the ZIICS license, not the GPL.