Don't use C++ comment syntax -- oops.
[xboard.git] / xboard.texi
1 @ifinfo
2
3 This file documents version @value{VERSION} of @value{NAME}. 
4 @value{NAME} 
5 is a graphical chessboard that can serve as a
6 user interface to the GNU Chess and Crafty chess engines, the
7 Internet Chess Servers,
8 electronic mail correspondence chess, or your own collection of saved games.
9
10 Copyright (C) 1991 Digital Equipment Corporation, Maynard, Massachusetts.
11
12 All Rights Reserved.
13
14 Permission to use, copy, modify, and distribute this software and its
15 documentation for any purpose and without fee is hereby granted,
16 provided that the above copyright notice appear in all copies and that
17 both that copyright notice and this permission notice appear in
18 supporting documentation, and that the name of Digital not be
19 used in advertising or publicity pertaining to distribution of the
20 software without specific, written prior permission.
21
22 Digital disclaims all warranties with regard to this software, including
23 all implied warranties of merchantability and fitness.  In no event shall
24 Digital be liable for any special, indirect or consequential damages or
25 any damages whatsoever resulting from loss of use, data or profits,
26 whether in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of this
28 software.
29
30 Enhancements copyright (C) 1992-2000 Free Software Foundation, Inc.
31
32 Published by the Free Software Foundation
33 59 Temple Place - Suite 330
34 Boston, MA 02111-1307 USA
35
36 Permission is granted to make and distribute verbatim copies of
37 this manual provided the copyright notice and this permission notice
38 are preserved on all copies.
39
40 @ignore
41 Permission is granted to process this file through Tex and print the
42 results, provided the printed document carries copying permission
43 notice identical to this one except for the removal of this paragraph
44 (this paragraph not being relevant to the printed manual).
45
46 @end ignore
47 Permission is granted to copy and distribute modified versions of this
48 manual under the conditions for verbatim copying, provided also that the
49 section entitled ``GNU General Public License,''
50 is included exactly as in the original, and provided that the entire
51 resulting derived work is distributed under the terms of a permission
52 notice identical to this one.
53
54 Permission is granted to copy and distribute translations of this manual
55 into another language, under the above conditions for modified versions,
56 except that the section entitled ``GNU General Public License,''
57 and this permission notice, may be included in translations approved by
58 the Free Software Foundation instead of in the original English.
59 @end ifinfo
60
61 @titlepage
62 @title @value{NAME}
63 @author Tim Mann
64
65 @page
66 @vskip 0pt plus 1filll
67 Copyright @copyright{} 1991 Digital Equipment Corporation, Maynard, Massachusetts.
68
69 All Rights Reserved
70
71 Permission to use, copy, modify, and distribute this software and its
72 documentation for any purpose and without fee is hereby granted,
73 provided that the above copyright notice appear in all copies and that
74 both that copyright notice and this permission notice appear in
75 supporting documentation, and that the name of Digital not be
76 used in advertising or publicity pertaining to distribution of the
77 software without specific, written prior permission.
78
79 Digital disclaims all warranties with regard to this software, including
80 all implied warranties of merchantability and fitness.  In no event shall
81 Digital be liable for any special, indirect or consequential damages or
82 any damages whatsoever resulting from loss of use, data or profits,
83 whether in an action of contract, negligence or other tortious action,
84 arising out of or in connection with the use or performance of this
85 software.
86
87 Enhancements copyright @copyright{} 1992-2000 Free Software Foundation, Inc.
88
89 @format
90 Published by the Free Software Foundation
91 59 Temple Place - Suite 330
92 Boston, MA 02111-1307 USA
93 @end format
94
95 Permission is granted to make and distribute verbatim copies of
96 this manual provided the copyright notice and this permission notice
97 are preserved on all copies.
98
99 @ignore
100 Permission is granted to process this file through Tex and print the
101 results, provided the printed document carries copying permission
102 notice identical to this one except for the removal of this paragraph
103 (this paragraph not being relevant to the printed manual).
104
105 @end ignore
106 Permission is granted to copy and distribute modified versions of this
107 manual under the conditions for verbatim copying, provided also that the
108 section entitled ``GNU General Public License,'' is
109 included exactly as in the original, and provided that the entire
110 resulting derived work is distributed under the terms of a permission
111 notice identical to this one.
112
113 Permission is granted to copy and distribute translations of this manual
114 into another language, under the above conditions for modified versions,
115 except that the section entitled ``GNU General Public License,''
116 and this permission notice, may be included in
117 translations approved by the Free Software Foundation instead of in the
118 original English.
119
120 @end titlepage
121
122 @node Top
123 @top Introduction
124 @cindex introduction
125
126 This manual documents version @value{VERSION} of @value{NAME}.
127 @value{NAME}
128 is a graphical chessboard that can serve as a
129 user interface to the GNU Chess and Crafty chess engines, the
130 Internet Chess Servers,
131 electronic mail correspondence chess, or your own collection of saved games.
132
133 @menu
134 * Installation::    How to configure, compile and install @value{NAME}.
135 * Invocation::      Command options supported by @value{NAME}.
136 * Menus::           Menus, Buttons and Keys.
137 * ICS::             Using @value{NAME} with an Internet Chess Server (ICS).
138 * Firewalls::       Connecting to the ICS through a firewall.
139 * Environment::     Environment variables.
140 * Limitations::     Known limitations and/or bugs.
141 * Problems::        How and where to report any problems you run into.
142 * Contributors::    People who have helped developing @value{NAME}.
143 * CMail::           Using @value{NAME} for electronic correspondence chess.
144 * Programs::        Other programs you can use with @value{NAME}.
145 * Copying::         The GNU General Public License.
146
147 * Index::           Index of concepts and symbol names.
148 @end menu
149
150 @ifset html
151 @node What is it?
152 @chapter What is it?
153 @cindex What is it?
154 @value{NAME}
155 is a graphical chessboard that can serve as a
156 user interface to the GNU Chess and Crafty chess engines, the
157 Internet Chess Servers,
158 electronic mail correspondence chess, or your own collection of saved games.
159 These Web pages document version @value{VERSION} of @value{NAME}.
160 @end ifset
161
162 @node Installation
163 @chapter How to configure, compile and install @value{NAME}
164 @cindex Installation
165
166 @value{NAME} is normally distributed as source, in a file with a name like
167 @file{xboard-*.tar.gz}.  You need to unpack this file and compile the results
168 with a C compiler.  
169
170 First, decide where you want to install the xboard executable program and
171 documentation.  The default is to put them under the @file{/usr/local}
172 directory tree.  If you want to put them somewhere else, such as under your
173 home directory, change the value in the @samp{--prefix} option below.
174
175 Use the following commands:
176
177 @example
178 gzip -cd xboard-*.tar.gz | tar -xvf -
179 cd xboard-*/
180 configure --prefix=/usr/local
181 make
182 make install
183 @end example
184
185 If you have any problems with these steps,
186 see the file @file{INSTALL} in the @value{NAME} distribution for
187 detailed instructions on options you can give to @code{configure},
188 and see the file @file{FAQ} for answers to frequently asked questions.
189
190 If everything works, you can delete the whole @file{xboard-*} directory after
191 @samp{make install} is done.
192
193 @node Invocation
194 @chapter Command options supported by @value{NAME}
195 @cindex Invocation
196 @cindex Options
197
198 @value{NAME} always runs in one of four major modes:
199
200 @table @asis
201 @item @value{LCNAME} [options]
202 runs @value{NAME} as an interface to a chess engine running
203 on your machine, such as GNU Chess or Crafty. In this mode,
204 @value{NAME} lets you play a game against the chess engine, set up
205 arbitrary positions, force variations, or watch a game between two
206 chess engines.
207 @item @value{LCNAME} -ics -icshost hostname [options]
208 runs @value{NAME} as an interface to the Internet Chess Server
209 (ICS). You can play against other ICS users, observe games they are
210 playing, or review games that have recently finished. @xref{ICS}.
211 All the ``wild'' chess variants on ICS are supported, including bughouse.
212 @item @value{LCNAME} -ncp [options]
213 lets you use @value{NAME} as a simple chessboard to play through
214 games. It will read and write game files and allow you to play
215 through variations manually. You can use it to browse games off the
216 net or review games you have saved.
217 These features are also available in the other modes.
218 If you want to pipe games into @value{NAME}, use the supplied
219 shell script @file{pxboard}.  For example, from the news reader @file{xrn},
220 find a message with one or more games in it,
221 click the Save button, and type @samp{|pxboard} as the file name.
222 @item cmail
223 uses @value{NAME} as an interface to electronic mail
224 correspondence chess.
225 @xref{CMail}.
226 @end table
227
228 Most of the @value{NAME} options have both a long name and a short
229 name. To turn a boolean option on or off from the command line,
230 either give its long name followed by the value @code{true} or
231 @code{false} (@samp{-longOptionName true}), or give just the short
232 name to turn the option on (@samp{-opt}), or the short name
233 preceded by @samp{x} to turn the option off (@samp{-xopt}). For
234 options that take strings or numbers as values, you can use the
235 long or short option names interchangeably.
236
237 Each option corresponds to an X resource with the same name, so
238 if you like, you can set options in your @file{.Xdefaults} file
239 or in a file named @file{XBoard} in your home directory.
240 For options that have two names, the longer one is the name of
241 the corresponding X resource; the short name is not recognized.
242 To turn a boolean option on or off as an
243 X resource, give its long name followed by the value
244 @code{true} or @code{false}:
245
246 @example
247 XBoard*longOptionName: true
248 @end example
249
250 @menu
251 * Chess engine options::        Controlling the chess engine.
252 * ICS options::                 Connecting to and using ICS.
253 * I/O options::                 Load and Save options.
254 * User interface options::      Look and Feel options.
255 * Other options::               Miscellaneous.
256 @end menu
257
258 @node Chess engine options
259 @section Controlling the chess engine
260 @cindex options, Chess engine
261 @cindex Chess engine options
262 @table @asis
263 @item -tc or -timeControl minutes[:seconds]
264 @cindex tc, option
265 @cindex timeControl, option
266 Each player begins with his clock set to the @code{timeControl} period.
267 Default: 5 minutes.
268 The additional options @code{movesPerSession} and @code{timeIncrement}
269 are mutually exclusive.  
270
271 @item -mps or -movesPerSession moves
272 @cindex mps, option
273 @cindex movesPerSession, option
274 When both players have made @code{movesPerSession} moves, a
275 new @code{timeControl} period is added to both clocks.  Default: 40 moves.
276
277 @item -inc or -timeIncrement seconds
278 @cindex inc, option
279 @cindex timeIncrement, option
280 If this option is specified, @code{movesPerSession} is ignored.
281 Instead, after each player's move, @code{timeIncrement} seconds are
282 added to his clock.  
283 Use @samp{-inc 0} if you want to require the entire
284 game to be played in one @code{timeControl} period, with no increment.
285 Default: -1, which specifies @code{movesPerSession} mode.
286
287 @item -clock/-xclock or -clockMode True/False
288 @cindex clock, option
289 @cindex clockMode, option
290 Determines whether or not to display the chess clocks. If clockMode is
291 @samp{false}, the clocks are not shown, but the side that is to play next
292 is still highlighted. Also, unless @code{searchTime}
293 is set, the chess engine still keeps track of the clock time and uses it to
294 determine how fast to make its moves.
295
296 @item -st or -searchTime minutes[:seconds]
297 @cindex st, option
298 @cindex searchTime, option
299 Tells the chess engine to spend at most the given amount of time
300 searching for each of its moves. Without this option, the chess engine
301 chooses its search time based on the number of moves and amount
302 of time remaining until the next time control.
303 Setting this option also sets clockMode to False.
304
305 @item -depth or -searchDepth number
306 @cindex sd, option
307 @cindex searchDepth, option
308 Tells the chess engine to look ahead at most the given number of moves
309 when searching for a move to make. Without this option, the chess
310 engine chooses its search depth based on the number of moves and
311 amount of time remaining until the next time control.  With the option,
312 the engine will cut off its search early if it reaches the specified depth.
313
314 @item -thinking/-xthinking or -showThinking True/False
315 @cindex thinking, option
316 @cindex showThinking, option
317 Sets the Show Thinking option. @xref{Options Menu}. Default: false.
318
319 @item -ponder/-xponder or -ponderNextMove True/False
320 @cindex ponder, option
321 @cindex ponderNextMove, option
322 Sets the Ponder Next Move menu option. @xref{Options Menu}. Default: True.
323
324 @item -mg or -matchGames n
325 @cindex mg, option
326 @cindex matchGames, option
327 Automatically runs an n-game match between two chess engines,
328 with alternating colors.
329 If the @code{loadGameFile} or @code{loadPositionFile} option is set,
330 @value{NAME}
331 starts each game with the given opening moves or the given position;
332 otherwise, the games start with the standard initial chess position.
333 If the @code{saveGameFile} option is set, a move record for the
334 match is appended to the specified file. If the @code{savePositionFile}
335 option is set, the final position reached in each game of the match is appended
336 to the specified file. When the match is over, @value{NAME}
337 displays the match score and exits. Default: 0 (do not run a match).
338
339 @item -mm/-xmm or -matchMode True/False
340 @cindex mm, option
341 @cindex matchMode, option
342 Abbreviation for -matchGames 1.
343
344 @item -fcp or -firstChessProgram program
345 @cindex fcp, option
346 @cindex firstChessProgram, option
347 Name of first chess engine.
348 Default: @file{gnuchessx}.
349
350 @item -scp or -secondChessProgram program
351 @cindex scp, option
352 @cindex secondChessProgram, option
353 Name of second chess engine, if needed.
354 A second chess engine is started only in Two Machines (match) mode.
355 Default: @file{gnuchessx}.
356
357 @item -fb/-xfb or -firstPlaysBlack True/False
358 @cindex fb, option
359 @cindex firstPlaysBlack, option
360 In games between two chess engines, firstChessProgram normally
361 plays white.  (This is a change from earlier versions of @value{NAME}.)
362 If this option is True, firstChessProgram plays black.
363 In a multi-game match, this option affects the colors only for
364 the first game; they still alternate in subsequent games.
365
366 @item -fh or -firstHost host
367 @itemx -sh or -secondHost host
368 @cindex fh, option
369 @cindex firstHost, option
370 @cindex sh, option
371 @cindex secondHost, option
372 Hosts on which the chess engines are to run. The default for
373 each is @file{localhost}. If you specify another host, @value{NAME}
374 uses @file{rsh} (1) to run the chess engine there. (You can substitute a
375 different remote shell program for rsh using the @code{remoteShell}
376 option described below.)
377
378 @item -fd or -firstDirectory dir
379 @itemx -sd or -secondDirectory dir
380 @cindex fd, option
381 @cindex firstDirectory, option
382 @cindex sd, option
383 @cindex secondDirectory, option
384 Working directories in which the chess engines are to be run.
385 The default is "", which means to run the chess engine
386 in the same working directory as @value{NAME}
387 itself.  (See the CHESSDIR environment variable.)
388 This option is effective only when the chess engine is being run
389 on the local host; it does not work if the engine is run remotely
390 using the -fh or -sh option.
391
392 @item -initString string
393 @itemx -secondInitString string
394 @cindex initString, option
395 @cindex secondInitString, option
396 The string that is sent to initialize each chess engine for a new game.
397 Default:
398
399 @example
400 new
401 random
402 @end example
403 @noindent
404 Setting this option from the command line is tricky, because you must
405 type in real newline characters, including one at the very end.
406 In most shells you can do this by
407 entering a @samp{\} character followed by a newline. It is easier to set
408 the option from your @file{.Xdefaults} file; in that case you can
409 include the character sequence @samp{\n} in the string, and it will
410 be converted to a newline.
411
412 If you change this option, don't remove the @samp{new} 
413 command; it is required by all chess engines to
414 start a new game.
415
416 You can remove the @samp{random} command if you like;
417 including it causes GNU Chess to randomize its move selection
418 slightly so that it doesn't play the same moves in every game.
419 Even without @samp{random}, GNU Chess randomizes its choice of moves
420 from its opening book.  Crafty
421 ignores this command; it randomizes by default.
422
423 You can also try adding other
424 commands to the initString; see the GNU Chess or Crafty documentation for
425 details.
426
427 @item -firstComputerString string
428 @itemx -secondComputerString string
429 @cindex firstComputerString, option
430 @cindex secondComputerString, option
431 The string that is sent to the chess engine if its opponent is another
432 computer chess engine.  The default is @samp{computer\n}.  Probably the
433 only useful alternative is the empty string (@samp{}), which keeps the
434 engine from knowing that it is playing another computer.
435
436 @item -reuse/-xreuse or -reuseFirst True/False
437 @itemx -reuse2/-xreuse2 or -reuseSecond True/False
438 @cindex reuse, option
439 @cindex reuseFirst, option
440 @cindex reuse2, option
441 @cindex reuseSecond, option
442 If the option is false,
443 @value{NAME} kills off the chess engine after every game and starts
444 it again for the next game.  
445 If the option is true (the default), 
446 @value{NAME} starts the chess engine only once
447 and uses it repeatedly to play multiple games.
448 Some chess engines may not work properly when
449 reuse is turned on, such as versions of Crafty earlier than 12.0,
450 but otherwise new games will start faster if it is left on.
451
452 @item -firstProtocolVersion version-number
453 @itemx -secondProtocolVersion version-number
454 @cindex firstProtocolVersion, option
455 @cindex secondProtocolVersion, option
456 This option specifies which version of the chess engine communication
457 protocol to use.  By default, version-number is 2.  In version 1, the
458 "protover" command is not sent to the engine; since version 1 is a
459 subset of version 2, nothing else changes.  Other values for
460 version-number are not supported.
461 @end table
462
463 @node ICS options
464 @section Connecting to and using ICS
465 @cindex ICS options
466 @cindex Options, ICS
467 @table @asis
468 @item -ics/-xics or -internetChessServerMode True/False
469 @cindex ics, option
470 @cindex internetChessServerMode, option
471 Connect with an Internet Chess Server to play chess against its
472 other users, observe games they are playing, or review games
473 that have recently finished. Default: false.
474 To use @value{NAME} in ICS mode, run it in the foreground, and use the
475 terminal you started it from to type commands and receive text
476 responses from the chess server.
477 @xref{ICS}. @xref{File Menu}. @xref{Step Menu}.
478 @xref{Mode Menu}.
479
480 @item -icshost or -internetChessServerHost host
481 @cindex icshost, option
482 @cindex internetChessServerHost, option
483 The Internet host name or address of the chess server to connect
484 to when in ICS mode. Default: @code{chessclub.com}. See the file
485 @file{ics-addresses} in the @value{NAME}
486 distribution for a list of other addresses to try.
487 If your site doesn't have a working Internet name server, try
488 specifying the host address in numeric form. 
489 You may also need
490 to specify the numeric address when using the icshelper option
491 with timestamp or timeseal (see below).
492 At this writing
493 @code{chessclub.com} is @samp{207.99.5.190} and
494 @code{freechess.org} is @samp{164.58.253.13}.
495
496 @item -icsport or -internetChessServerPort port-number
497 @cindex icsport, option
498 @cindex internetChessServerPort, option
499 The port number to use when connecting to a chess server in ICS
500 mode. Default: 5000.
501
502 @item -icshelper or -internetChessServerHelper prog-name
503 @cindex icshelper, option
504 @cindex internetChessServerHelper, option
505 An external helper program used to communicate with the chess server.
506 You would set it to "timestamp" for ICC (chessclub.com) or
507 "timeseal" for FICS (freechess.org, eics.daimi.aau.dk, etc.), after
508 obtaining the correct version of timestamp or timeseal for your
509 computer.  See "help timestamp" on ICC and "help timeseal" on FICS.
510 This option is shorthand for @code{-useTelnet -telnetProgram program}.
511
512 @item -telnet/-xtelnet or -useTelnet True/False
513 @cindex telnet, option
514 @cindex useTelnet, option
515 This option is poorly named; it should be called useHelper.
516 If set to true, it instructs @value{NAME} to run an external
517 program to communicate with the Internet Chess Server. 
518 The program to use is given by the telnetProgram option.
519 If the option is
520 false (the default), @value{NAME} opens a TCP socket and uses its own
521 internal implementation of the telnet protocol to communicate with the
522 ICS. @xref{Firewalls}.
523
524 @item -telnetProgram prog-name
525 @cindex telnetProgram, option
526 This option is poorly named; it should be called helperProgram.
527 It gives the name of the telnet program to be used with
528 the @code{gateway} and @code{useTelnet} options.  The default is
529 @file{telnet}. The telnet program is invoked with the value of
530 @code{internetChessServerHost} as its first argument and the value
531 of @code{internetChessServerPort} as its second argument.
532 @xref{Firewalls}.
533
534 @item -gateway host-name
535 @cindex gateway, option
536 If this option is set to a host name, @value{NAME} uses @file{rsh} (1) to run
537 the @file{telnet} (1) program on the given host to communicate with the
538 Internet Chess Server instead of using its own internal implementation
539 of the telnet protocol. You can substitute a different remote shell
540 program for @file{rsh} using the @code{remoteShell} option described below.
541 @xref{Firewalls}.
542
543 @item -internetChessServerCommPort or -icscomm dev-name
544 @cindex internetChessServerCommPort, option
545 @cindex icscomm, option
546 If this option is set, @value{NAME} communicates with the ICS through
547 the given character I/O device instead of opening a TCP connection.
548 Use this option if your system does not have any kind of
549 Internet connection itself (not even a SLIP or PPP connection),
550 but you do have dialup access (or a hardwired terminal line) to
551 an Internet service provider from which you can telnet to the
552 ICS.
553
554 The support for this option in @value{NAME} is minimal. You need to
555 set all communication parameters and tty modes before you enter
556 @value{NAME}.
557
558 Use a script something like this:
559
560 @example
561 stty raw -echo 9600 > /dev/tty00
562 @value{LCNAME} -ics -icscomm /dev/tty00
563 @end example
564
565 Here replace @samp{/dev/tty00} with the name of the device that your
566 modem is connected to. You might have to add several more
567 options to these stty commands. See the man pages for @file{stty} (1)
568 and @code{tty} (4) if you run into problems. Also, on many systems stty
569 works on its standard input instead of standard output, so you
570 have to use @samp{<} instead of @samp{>}.
571
572 If you are using linux, try starting with the script below.
573 Change it as necessary for your installation.
574
575 @example
576 ####################################################
577 #!/bin/sh -f
578 # configure modem and fire up @value{NAME}
579
580 # configure modem
581 (
582   stty 2400 ; stty raw ; stty hupcl ; stty -clocal
583   stty ignbrk ; stty ignpar ; stty ixon ; stty ixoff
584   stty -iexten ; stty -echo
585 ) < /dev/modem
586 @value{LCNAME} -ics -icscomm /dev/modem
587 ####################################################
588 @end example
589 @noindent
590 After you start @value{NAME} in this way, type whatever commands are
591 necessary to dial out to your Internet provider and log in.
592 Then telnet to ICS, using a command like
593
594 @example
595 telnet chessclub.com 5000
596 @end example
597 @noindent
598 Important: See the paragraph below about extra echoes, 
599 in @ref{Limitations}.
600
601 @item -icslogon or -internetChessServerLogonScript file-name
602 @cindex icslogon, option
603 @cindex internetChessServerLogonScript, option
604 @cindex .icsrc
605 Whenever @value{NAME} connects to the Internet Chess Server,
606 if it finds a file with the name given in this option, it feeds the
607 file's contents to the ICS as commands. The default file name
608 is @file{.icsrc}.
609 Usually the first two lines of the file should be
610 your ICS user name and password.
611 The file can be either in $CHESSDIR, in @value{NAME}'s working
612 directory if CHESSDIR is not set, or in your home directory.
613
614 @item -msLoginDelay delay
615 @cindex msLoginDelay, option
616 If you experience trouble logging on to an ICS when using the
617 @code{-icslogon} option, inserting some delay between characters
618 of the logon script may help. This option adds @code{delay}
619 milliseconds of delay between characters. Good values to try
620 are 100 and 250.
621
622 @item -icsinput/-xicsinput or -internetChessServerInputBox True/False
623 @cindex icsinput, option
624 @cindex internetChessServerInputBox, option
625 Sets the ICS Input Box menu option. @xref{Mode Menu}. Default: false.
626
627 @item -autocomm/-xautocomm or -autoComment True/False
628 @cindex autocomm, option
629 @cindex autoComment, option
630 Sets the Auto Comment menu option. @xref{Options Menu}. Default: False.
631
632 @item -autoflag/-xautoflag or -autoCallFlag True/False
633 @cindex autoflag, option
634 @cindex autoCallFlag, option
635 Sets the Auto Flag menu option.  @xref{Options Menu}. Default: false.
636
637 @item -autobs/-xautobs or -autoObserve True/False
638 @cindex autobs, option
639 @cindex autoObserve, option
640 Sets the Auto Observe menu option.  @xref{Options Menu}. Default: false.
641
642 @item -moves/-xmoves or -getMoveList True/False
643 @cindex moves, option
644 @cindex getMoveList, option
645 Sets the Get Move List menu option.  @xref{Options Menu}.  Default: true.
646
647 @item -alarm/-xalarm or -icsAlarm True/False
648 @cindex alarm, option
649 @cindex icsAlarm, option
650 Sets the ICS Alarm menu option.  @xref{Options Menu}. Default: true.
651
652 @item -icsAlarmTime ms
653 @cindex icsAlarmTime, option
654 Sets the time in milliseconds for the ICS Alarm menu option. 
655 @xref{Options Menu}. Default: 5000.
656
657 @item -pre/-xpre \fRor\fB -premove True/False
658 @cindex pre, option
659 @cindex premove, option
660 Sets the Premove menu option. @xref{Options Menu}. Default: true.
661
662 @item -quiet/-xquiet or -quietPlay True/False
663 @cindex quiet, option
664 @cindex quietPlay, option
665 Sets the Quiet Play menu option.  @xref{Options Menu}.  Default: false.
666
667 @item -colorizeMessages or -colorize
668 @cindex Colors
669 @cindex colorize, option
670 Setting colorizeMessages
671 to True tells XBoard to colorize the messages received from
672 the ICS.  Colorization works only if your xterm 
673 supports ISO 6429 escape sequences for changing text colors.
674
675 @item -colorShout foreground,background,bold
676 @itemx -colorSShout foreground,background,bold
677 @itemx -colorChannel1 foreground,background,bold
678 @itemx -colorChannel foreground,background,bold
679 @itemx -colorKibitz foreground,background,bold
680 @itemx -colorTell foreground,background,bold
681 @itemx -colorChallege foreground,background,bold
682 @itemx -colorRequest foreground,background,bold
683 @itemx -colorSeek foreground,background,bold
684 @itemx -colorNormal foreground,background,bold
685 @cindex Colors
686 @cindex colorShout, option
687 @cindex colorSShout, option
688 @cindex colorChannel1, option
689 @cindex colorChannel, option
690 @cindex colorKibitz, option
691 @cindex colorTell, option
692 @cindex colorChallenge, option
693 @cindex colorRequest, option
694 @cindex colorSeek, option
695 @cindex colorNormal, option
696 These options set the colors used when colorizing ICS messages.
697 All ICS messages are grouped into one of these categories:
698 shout, sshout, channel 1, other channel, kibitz, tell, challenge, 
699 request (including abort, adjourn, draw, pause, and takeback), or
700 normal (all other messages).  
701
702 Each foreground or background argument can be one of the following:
703 black, red, green, yellow, blue, magenta, cyan, white, or default.
704 Here ``default'' means the default foreground or background color of
705 your xterm.  Bold can be 1 or 0.  If background is omitted, ``default''
706 is assumed; if bold is omitted, 0 is assumed.
707
708 Here is an example of how to set the colors in your @file{.Xdefaults} file.
709 The colors shown here are the default values; you will get
710 them if you turn @code{-colorize} on without specifying your own colors.
711 @example
712     xboard*colorizeMessages: true       
713     xboard*colorShout: green
714     xboard*colorSShout: green, black, 1
715     xboard*colorChannel1: cyan
716     xboard*colorChannel: cyan, black, 1
717     xboard*colorKibitz: magenta, black, 1
718     xboard*colorTell: yellow, black, 1
719     xboard*colorChallenge: red, black, 1
720     xboard*colorRequest: red
721     xboard*colorSeek: blue
722     xboard*colorNormal: default
723 @end example
724
725 @item -soundProgram progname
726 @cindex soundProgram, option
727 @cindex Sounds
728 If this option is set to a sound-playing program that is installed and
729 working on your system, @value{NAME} can play sound files when certain
730 events occur, listed below.  The default program name is "play".  If
731 any of the sound options is set to "$", the event rings the terminal
732 bell by sending a ^G character to standard output, instead of playing
733 a sound file.  If an option is set to the empty string "", no sound is
734 played for that event.
735
736 @item -soundShout filename
737 @itemx -soundSShout filename
738 @itemx -soundChannel filename
739 @itemx -soundKibitz filename
740 @itemx -soundTell filename
741 @itemx -soundChallenge filename
742 @itemx -soundRequest filename
743 @itemx -soundSeek filename
744 @cindex soundShout, option
745 @cindex soundSShout, option
746 @cindex soundChannel, option
747 @cindex soundKibitz, option
748 @cindex soundTell, option
749 @cindex soundChallenge, option
750 @cindex soundRequest, option
751 @cindex soundSeek, option
752 These sounds are triggered in the same way as the colorization events
753 described above.  They all default to "", no sound.  They are played
754 only if the colorizeMessages is on.
755
756 @item -soundMove filename
757 @cindex soundMove, option
758 This sound is used by the Move Sound menu option.  Default: "$".
759
760 @item -soundIcsAlarm filename
761 @cindex soundIcsAlarm, option
762 This sound is used by the ICS Alarm menu option.  Default: "$".
763
764 @item -soundIcsWin filename
765 @cindex soundIcsWin, option
766 This sound is played when you win an ICS game.  Default: "" (no sound).
767
768 @item -soundIcsLoss filename
769 @cindex soundIcsLoss, option
770 This sound is played when you lose an ICS game.  Default: "" (no sound).
771
772 @item -soundIcsDraw filename
773 @cindex soundIcsDraw, option
774 This sound is played when you draw an ICS game.  Default: "" (no sound).
775
776 @item -soundIcsUnfinished filename
777 @cindex soundIcsUnfinished, option
778 This sound is played when an ICS game that you are participating in is
779 aborted, adjourned, or otherwise ends inconclusively.  Default: "" (no
780 sound).
781
782 Here is an example of how to set the sounds in your .Xdefaults file.
783 @example
784     xboard*soundShout: shout.wav
785     xboard*soundSShout: sshout.wav
786     xboard*soundChannel1: channel1.wav
787     xboard*soundChannel: channel.wav
788     xboard*soundKibitz: kibitz.wav
789     xboard*soundTell: tell.wav
790     xboard*soundChallenge: challenge.wav
791     xboard*soundRequest: request.wav
792     xboard*soundSeek: seek.wav
793     xboard*soundMove: move.wav
794     xboard*soundIcsWin: win.wav
795     xboard*soundIcsLoss: lose.wav
796     xboard*soundIcsDraw: draw.wav
797     xboard*soundIcsUnfinished: unfinished.wav
798     xboard*soundIcsAlarm: alarm.wav
799 @end example
800 @end table
801
802 @node I/O options
803 @section Load and Save options
804 @cindex Options, I/O
805 @cindex I/O options
806 @table @asis
807 @item -lgf or -loadGameFile file
808 @itemx -lgi or -loadGameIndex index
809 @cindex lgf, option
810 @cindex loadGameFile, option
811 @cindex lgi, option
812 @cindex loadGameIndex, option
813 If the @code{loadGameFile} option is set, @value{NAME} loads the specified
814 game file at startup. The file name @file{-} specifies the standard
815 input. If there is more than one game in the file, @value{NAME}
816 pops up a menu of the available games, with entries based on their PGN tags.
817 If the @code{loadGameIndex} option is set to @samp{N}, the menu is suppressed
818 and the N th game found in the file is loaded immediately.
819 The menu is also suppressed if @code{matchMode} is enabled or if the game file
820 is a pipe; in these cases the first game in the file is loaded immediately.
821 @ifset XBOARD
822 Use the @file{pxboard} shell script provided with @value{NAME} if you
823 want to pipe in files containing multiple games and still see the menu.
824 @end ifset
825
826 @item -td or -timeDelay seconds
827 @cindex td, option
828 @cindex timeDelay, option
829 Time delay between moves during @samp{Load Game}. Fractional seconds
830 are allowed; try @samp{-td 0.4}. A time delay value of -1 tells
831 @value{NAME} not to step through game files automatically. Default: 1
832 second.
833
834 @item -sgf or -saveGameFile file
835 @cindex sgf, option
836 @cindex saveGameFile, option
837 If this option is set, @value{NAME} appends a record of every game
838 played to the specified file. The file name @file{-} specifies the
839 standard output.
840
841 @item -autosave/-xautosave or -autoSaveGames True/False
842 @cindex autosave, option
843 @cindex autoSaveGames, option
844 Sets the Auto Save menu option.  @xref{Options Menu}.  Default: false.
845 Ignored if @code{saveGameFile} is set.
846
847 @item -lpf or -loadPositionFile file
848 @itemx -lpi or -loadPositionIndex index
849 @cindex lpf, option
850 @cindex loadPositionFile, option
851 @cindex lpi, option
852 @cindex loadPositionIndex, option
853 If the @code{loadPositionFile} option is set, @value{NAME} loads the
854 specified position file at startup. The file name @file{-} specifies the
855 standard input. If the @code{loadPositionIndex} option is set to N,
856 the Nth position found in the file is loaded; otherwise the
857 first position is loaded.
858
859 @item -spf or -savePositionFile file
860 @cindex spf, option
861 @cindex savePositionFile, option
862 If this option is set, @value{NAME} appends the final position reached
863 in every game played to the specified file. The file name @file{-}
864 specifies the standard output.
865
866 @item -oldsave/-xoldsave or -oldSaveStyle True/False
867 @cindex oldsave, option
868 @cindex oldSaveStyle, option
869 Sets the Old Save Style menu option.  @xref{Options Menu}.  Default: false.
870 @end table
871
872 @node User interface options
873 @section Look and Feel options
874 @cindex User interface options
875 @cindex Options, User interface
876 @table @asis
877 @item -display
878 @itemx -geometry
879 @itemx -iconic
880 @cindex display, option
881 @cindex geometry, option
882 @cindex iconic, option
883 These are just the standard Xt options accepted by @value{NAME}.
884
885 @item -movesound/-xmovesound or -bell/-xbell or -ringBellAfterMoves True/False
886 @cindex movesound, option
887 @cindex bell, option
888 @cindex ringBellAfterMoves, option
889 Sets the Move Sound menu option.  @xref{Options Menu}.  Default: false.
890
891 @item -exit/-xexit or -popupExitMessage True/False
892 @cindex exit, option
893 @cindex popupExitMessage, option
894 Sets the Popup Exit Message menu option.  @xref{Options Menu}. Default: True.
895
896 @item -popup/-xpopup or -popupMoveErrors True/False
897 @cindex popup, option
898 @cindex popupMoveErrors, option
899 Sets the Popup Move Errors menu option.  @xref{Options Menu}. Default: False.
900
901 @item -queen/-xqueen or -alwaysPromoteToQueen True/False
902 @cindex queen, option
903 @cindex alwaysPromoteToQueen, option
904 Sets the Always Queen menu option.  @xref{Options Menu}.  Default: false.
905
906 @item -legal/-xlegal or -testLegality True/False
907 @cindex legal, option
908 @cindex testLegality, option
909 If this option is true (the default), 
910 @value{NAME}
911 tests whether moves you try to make with the mouse are legal, and
912 refuses to let you make an illegal move.  Moves loaded from a file
913 with @samp{Load Game} are also checked.
914 If the option is false, all moves are accepted.
915 If GNU Chess, Crafty, or the ICS is active,
916 they will still reject illegal moves.  Turning off this option is
917 useful if you are playing a chess variant with rules that 
918 @value{NAME}
919 does not understand.
920
921 @item -size or -boardSize (sizeName | n1,n2,n3,n4,n5,n6,n7)
922 @cindex size, option
923 @cindex boardSize, option
924 @cindex board size
925 Determines how large the board will be, by selecting the pixel size
926 of the pieces and setting a few related parameters.
927 The sizeName can be one of: Titanic, giving 129x129 pixel pieces,
928 Colossal 116x116, Giant 108x108, Huge 95x95, Big 87x87, Large 80x80, Bulky 72x72,
929 Medium 64x64, Moderate 58x58, Average 54x54, Middling 49x49, Mediocre
930 45x45, Small 40x40, Slim 37x37, Petite 33x33, Dinky 29x29, Teeny 25x25,
931 or Tiny 21x21.
932 Pieces of all these sizes are built into @value{NAME}.
933 Other sizes can
934 be used if you have them; see the pixmapDirectory and bitmapDirectory
935 options.
936 The default depends on the size of your screen; it is approximately the
937 largest size that will fit without clipping.
938
939 You can select other sizes or vary other layout parameters by providing
940 a list of comma-separated values (with no spaces) as the argument.
941 You do not need to provide all the values; for any you omit from the
942 end of the list, defaults are taken from the nearest built-in size.
943 The value @code{n1} gives the piece size, @code{n2} the width of the
944 black border
945 between squares, @code{n3} the desired size for the 
946 clockFont, @code{n4} the desired size for the coordFont,
947 @code{n5} the desired size for the default font,
948 @code{n6} the smallLayout flag (0 or 1), 
949 and @code{n7} the tinyLayout flag (0 or 1).  
950 All dimensions are in pixels.
951 If the border between squares is eliminated (0 width), the various
952 highlight options will not work, as there is nowhere to draw the highlight.
953 If smallLayout is 1 and @code{titleInWindow} is True, 
954 the window layout is rearranged to make more room for the title.
955 If tinyLayout is 1, the labels on the menu bar are abbreviated
956 to one character each and the buttons in the button bar are made narrower.
957
958 @item -coords/-xcoords or -showCoords True/False
959 @cindex coords, option
960 @cindex showCoords, option
961 Sets the Show Coords menu option.  @xref{Options Menu}.  Default: false.
962 The @code{coordFont} option specifies what font to use.
963
964 @item -autoraise/-xautoraise or -autoRaiseBoard True/False
965 @cindex autoraise, option
966 @cindex autoRaiseBoard, option
967 Sets the Auto Raise Board menu option.  Default: true.
968
969 @item -autoflip/-xautoflip or -autoFlipView True/False
970 @cindex autoflip, option
971 @cindex autoFlipView, option
972 Sets the Auto Flip View menu option.  Default: true.
973
974 @item -flip/-xflip or -flipView True/False
975 @cindex flip, option
976 @cindex flipView, option
977 If Auto Flip View is not set, or if you are observing but not participating
978 in a game, then the positioning of the board at the start of each game
979 depends on the flipView option.  If flipView is False (the default),
980 the board is positioned so that the white pawns move from the bottom to the
981 top; if True, the black pawns move from the bottom to the top.
982 In any case, the Flip menu option can be used to flip the board after
983 the game starts.
984
985 @item -title/-xtitle or -titleInWindow True/False
986 @cindex title, option
987 @cindex titleInWindow, option
988 If this option is true, @value{NAME} displays player names (for ICS
989 games) and game file names (for @samp{Load Game}) inside its main
990 window. If the option is false (the default), this information is
991 displayed only in the window banner. You probably won't want to
992 set this option unless the information is not showing up in the
993 banner, as happens with a few X window managers.
994
995 @item -mono/-xmono or -monoMode True/False
996 @cindex mono, option
997 @cindex monoMode, option
998 Determines whether @value{NAME} displays its pieces and squares with
999 two colors (true) or four (false). You shouldn't have to
1000 specify @code{monoMode}; @value{NAME} will determine if it is necessary.
1001
1002 @item -flashCount count
1003 @itemx -flashRate rate
1004 @itemx -flash
1005 @itemx -xflash
1006 @cindex flashCount, option
1007 @cindex flashRate, option
1008 @cindex flash, option
1009 @cindex xflash, option
1010 These options enable flashing of pieces when they
1011 land on their destination square.
1012 @code{flashCount}
1013 tells XBoard how many times to flash a piece after it
1014 lands on its destination square.
1015 @code{flashRate}
1016 controls the rate of flashing (flashes/sec).
1017 Abbreviations:
1018 @code{flash}
1019 sets flashCount to 3.
1020 @code{xflash}
1021 sets flashCount to 0.
1022 Defaults:  flashCount=0 (no flashing), flashRate=5.
1023
1024 @item -highlight/-xhighlight or -highlightLastMove True/False
1025 @cindex highlight, option
1026 @cindex highlightLastMove, option
1027 Sets the Highlight Last Move menu option. Default: false.
1028
1029 @item -blind/-xblind or -blindfold True/False
1030 @cindex blind, option
1031 @cindex blindfold, option
1032 Sets the Blindfold menu option.  Default: false.
1033
1034 @item -clockFont font
1035 @cindex clockFont, option
1036 @cindex Font, clock
1037 The font used for the clocks. If the option value is a pattern
1038 that does not specify the font size, @value{NAME} tries to choose an
1039 appropriate font for the board size being used.
1040 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
1041
1042 @item -coordFont font
1043 @cindex coordFont, option
1044 @cindex Font, coordinates
1045 The font used for rank and file coordinate labels if @code{showCoords}
1046 is true. If the option value is a pattern that does not specify
1047 the font size, @value{NAME} tries to choose an appropriate font for
1048 the board size being used.
1049 Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.
1050
1051 @item -font font
1052 @cindex font, option
1053 @cindex Font
1054 The font used for popup dialogs, menus, comments, etc.
1055 If the option value is a pattern that does not specify
1056 the font size, @value{NAME} tries to choose an appropriate font for
1057 the board size being used.
1058 Default: -*-helvetica-medium-r-normal--*-*-*-*-*-*-*-*.
1059
1060 @item -fontSizeTolerance tol
1061 @cindex fontSizeTolerance, option
1062 In the font selection algorithm, a nonscalable font will be preferred
1063 over a scalable font if the nonscalable font's size differs by tol pixels
1064 or less from the desired size.  A value of -1 will force
1065 a scalable font to always be used if available; a value of 0 will
1066 use a nonscalable font only if it is exactly the right size; 
1067 a large value (say 1000) will force a nonscalable font to always be
1068 used if available.  Default: 4.
1069
1070 @item -bm or -bitmapDirectory dir
1071 @itemx -pixmap or -pixmapDirectory dir
1072 @cindex bm, option
1073 @cindex bitmapDirectory, option
1074 @cindex pixmap, option
1075 @cindex pixmapDirectory, option
1076 These options control what piece images xboard uses.  The @value{NAME}
1077 distribution includes one set of pixmap pieces in xpm format, in the
1078 directory @file{pixmaps}, and two sets of bitmap pieces in xbm format,
1079 in the directories @file{bitmaps} and @file{bitmaps.xchess}.  Pixmap
1080 pieces give a better appearance on the screen: the white pieces have
1081 dark borders, and the black pieces have opaque internal details.  With
1082 bitmaps, neither piece color has a border, and the internal details
1083 are transparent; you see the square color or other background color
1084 through them.
1085
1086 If @value{NAME} is configured and compiled on a system that includes libXpm,
1087 the X pixmap library, the xpm pixmap pieces are compiled in as the
1088 default.  A different xpm piece set can be selected at runtime with
1089 the @code{pixmapDirectory} option, or a bitmap piece set can be selected
1090 with the @code{bitmapDirectory} option.
1091
1092 If @value{NAME} is configured and compiled on a system that does not include
1093 libXpm (or the @code{--disable-xpm} option is given to the configure
1094 program), the bitmap pieces are compiled in as the default.  It is not
1095 possible to use xpm pieces in this case, but pixmap pieces in another
1096 format called "xim" can be used by giving the @code{pixmapDirectory} option.
1097 Or again, a different bitmap piece set can be selected with the
1098 @code{bitmapDirectory} option.
1099
1100 Files in the @code{bitmapDirectory} must be named as follows:
1101 The first character of a piece bitmap name gives the piece it 
1102 represents (@samp{p}, @samp{n}, @samp{b}, @samp{r}, @samp{q}, or @samp{k}),
1103 the next characters give the size in pixels, the
1104 following character indicates whether the piece is
1105 solid or outline (@samp{s} or @samp{o}),
1106 and the extension is @samp{.bm}.
1107 For example, a solid 80x80 knight would be named @file{n80s.bm}.
1108 The outline bitmaps are used only in monochrome mode.
1109 If bitmap pieces are compiled in and the bitmapDirectory is missing
1110 some files, the compiled in pieces are used instead.
1111
1112 If the bitmapDirectory option is given,
1113 it is also possible to replace xboard's icons and menu checkmark,
1114 by supplying files named @file{icon_white.bm}, @file{icon_black.bm}, and
1115 @file{checkmark.bm}.
1116
1117 For more information about pixmap pieces and how to get additional
1118 sets, see @ref{zic2xpm}.
1119
1120 @item -whitePieceColor color
1121 @itemx -blackPieceColor color
1122 @itemx -lightSquareColor color
1123 @itemx -darkSquareColor color
1124 @itemx -highlightSquareColor color
1125 @cindex Colors
1126 @cindex whitePieceColor, option
1127 @cindex blackPieceColor, option
1128 @cindex lightSquareColor, option
1129 @cindex darkSquareColor, option
1130 @cindex highlightSquareColor, option
1131 Colors to use for the pieces, squares, and square highlights.
1132 Defaults:
1133 @example
1134 -whitePieceColor       #FFFFCC
1135 -blackPieceColor       #202020
1136 -lightSquareColor      #C8C365
1137 -darkSquareColor       #77A26D
1138 -highlightSquareColor  #FFFF00
1139 -premoveHighlightColor #FF0000
1140 @end example
1141
1142 On a grayscale monitor you might prefer:
1143 @example
1144 -whitePieceColor       gray100
1145 -blackPieceColor       gray0
1146 -lightSquareColor      gray80
1147 -darkSquareColor       gray60
1148 -highlightSquareColor  gray100
1149 -premoveHighlightColor gray70
1150 @end example
1151
1152 @item -drag/-xdrag or -animateDragging True/False
1153 @cindex drag, option
1154 @cindex animateDragging, option
1155 Sets the Animate Dragging menu option. Default: True.
1156
1157 @item -animate/-xanimate or -animateMoving True/False
1158 @cindex animate, option
1159 @cindex animateMoving, option
1160 Sets the Animate Moving menu option. Default: True.
1161
1162 @item -animateSpeed n
1163 @cindex -animateSpeed, option
1164 Number of milliseconds delay between each animation frame when Animate
1165 Moves is on.
1166 @end table
1167
1168 @node Other options
1169 @section Miscellaneous
1170 @cindex Options, miscellaneous
1171 @table @asis
1172
1173 @item -ncp/-xncp or -noChessProgram True/False
1174 @cindex ncp, option
1175 @cindex noChessProgram, option
1176 If this option is true, @value{NAME} acts as a passive chessboard; it
1177 does not start a chess engine at all. Turning on this option
1178 also turns off clockMode. Default: false.
1179
1180 @item -mode or -initialMode modename
1181 @cindex mode, option
1182 @cindex initalMode, option
1183 If this option is given, @value{NAME} selects the given modename
1184 from the Mode menu after starting and (if applicable) processing the
1185 loadGameFile or loadPositionFile option. Default: "" (no selection). 
1186 Other supported values are 
1187 MachineWhite, MachineBlack, TwoMachines, Analysis, 
1188 AnalyzeFile, EditGame, EditPosition, and Training.
1189
1190 @item -variant varname
1191 @cindex variant, option
1192
1193 Activates preliminary, partial support for playing chess variants
1194 against a local engine or editing variant games.  This flag is not
1195 needed in ICS mode.  Recognized variant names are:
1196
1197 @example
1198   normal        Normal chess
1199   wildcastle    Shuffle chess, king can castle from d file
1200   nocastle      Shuffle chess, no castling allowed
1201   fischerandom  Fischer Random shuffle chess
1202   bughouse      Bughouse, ICC/FICS rules
1203   crazyhouse    Crazyhouse, ICC/FICS rules
1204   losers        Lose all pieces or get mated (ICC wild 17)
1205   suicide       Lose all pieces including king (FICS)
1206   giveaway      Try to have no legal moves (ICC wild 26)
1207   twokings      Weird ICC wild 9
1208   kriegspiel    Opponent's pieces are invisible
1209   atomic        Capturing piece explodes (ICC wild 27)
1210   3check        Win by giving check 3 times (ICC wild 25)
1211   shatranj      An ancient precursor of chess (ICC wild 28)
1212   unknown       Catchall for other unknown variants
1213 @end example
1214
1215 In the shuffle variants, xboard does not shuffle the pieces, but
1216 you can do it by hand using Edit Position.  Some variants are
1217 supported only in ICS mode, including fischerandom, bughouse, and
1218 kriegspiel.  The winning/drawing conditions in crazyhouse (offboard
1219 interposition on mate), losers, suicide, giveaway, atomic, and 3check
1220 are not fully understood.  In crazyhouse, xboard does not yet keep
1221 track of offboard pieces.  Shatranj is unsupported, but it may be
1222 usable if you turn off Test Legality.
1223
1224 @item -debug/-xdebug or -debugMode True/False
1225 @cindex debug, option
1226 @cindex debugMode, option
1227 Turns on debugging printout.
1228
1229 @item -rsh or -remoteShell shell-name
1230 @cindex rsh, option
1231 @cindex remoteShell, option
1232 Name of the command used to run programs remotely. The default
1233 is @file{rsh} or @file{remsh}, determined when @value{NAME} is
1234 configured and compiled.
1235
1236 @item -ruser or -remoteUser user-name
1237 @cindex ruser, option
1238 @cindex remoteUser, option
1239 User name on the remote system when running programs with the
1240 @code{remoteShell}. The default is your local user name.
1241 @end table
1242
1243
1244 @node Menus
1245 @chapter Menus, buttons and keys
1246 @cindex Menus
1247 To move a piece, either drag it with the left mouse button,
1248 or click the left mouse button once on the piece, then once more on
1249 the destination square.
1250 To drop a new piece on a
1251 square (when applicable), press the 
1252 middle or right mouse button over the square
1253 and select from the popup menu.
1254
1255 All other @value{NAME} commands are available from the menu bar. The most
1256 frequently used commands also have shortcut keys or on-screen buttons.
1257
1258 @menu
1259 * File Menu::       Accessing external games and positions.
1260 * Mode Menu::       Selecting @value{NAME}'s mode.
1261 * Action Menu::     Talking to the chess engine or ICS opponents.
1262 * Step Menu::       Controlling the game.
1263 * Options Menu::    User preferences.
1264 * Help Menu::       Getting help.
1265 * Keys::            Other shortcut keys.
1266 @end menu
1267
1268 @node File Menu
1269 @section Accessing external games and positions
1270 @cindex File Menu
1271 @cindex Menu, File
1272 @table @asis
1273 @item Reset
1274 @cindex Reset, Menuitem
1275 Resets @value{NAME} and the chess engine to the beginning of a new chess
1276 game. The @samp{r} key is a keyboard equivalent. In Internet Chess
1277 Server mode, clears the current state of @value{NAME}, then
1278 resynchronizes with ICS by sending a refresh command. If you want to
1279 stop playing, observing, or examining a game on ICS, use an
1280 appropriate command from the Action menu, not @samp{Reset}. @xref{Action
1281 Menu}.
1282
1283 @item Load Game
1284 @cindex Load Game, Menuitem
1285 Plays a game from a record file. The @samp{g} key is a keyboard equivalent.
1286 A popup dialog prompts you for the file name. If the file contains more
1287 than one game, a second popup dialog
1288 displays a list of games (with information drawn from their PGN tags, if
1289 any), and you can select the one you want. Alternatively, you can load the
1290 Nth game in the file directly, by typing the number @samp{N} after the
1291 file name, separated by a space.
1292
1293 The game file parser will accept PGN (portable game notation),
1294 or in fact almost any file that contains moves in algebraic
1295 notation. 
1296 Notation of the form @samp{P@@f7}
1297 is accepted for piece-drops in bughouse games;
1298 this is a nonstandard extension to PGN.
1299 If the file includes a PGN position (FEN tag), or an
1300 @value{NAME} position diagram bracketed by @samp{[--} and @samp{--]}
1301 before the first move, the game starts from that position. Text
1302 enclosed in parentheses, square brackets, or curly braces is assumed to
1303 be commentary and is displayed in a pop-up window. Any other
1304 text in the file is ignored. PGN variations (enclosed in
1305 parentheses) are treated as comments; @value{NAME} is not able to walk
1306 variation trees.
1307 The nonstandard PGN tag [Variant "varname"] functions similarly to
1308 the -variant command-line option (see below), allowing games in certain chess
1309 variants to be loaded.  There is also a heuristic to 
1310 recognize chess variants from the Event tag, by looking for the strings
1311 that the Internet Chess Servers put there when saving variant ("wild") games.
1312
1313 @item Load Next Game
1314 @cindex Load Next Game, Menuitem
1315 Loads the next game from the last game record file you loaded.
1316 The shifted @samp{N} key is a keyboard equivalent.
1317 Not available if the last game was loaded from a pipe.
1318
1319 @item Load Previous Game
1320 @cindex Load Previous Game, Menuitem
1321 Loads the previous game from the last game record file you
1322 loaded.  The shifted @samp{P} key is a keyboard equivalent.
1323 Not available if the last game was loaded from a pipe.
1324
1325 @item Reload Same Game
1326 @cindex Reload Same Game, Menuitem
1327 Reloads the last game you loaded.
1328
1329 @item Save Game
1330 @cindex Save Game, Menuitem
1331 Appends a record of the current game to a file.
1332 A popup dialog
1333 prompts you for the file name. If the game did not begin with
1334 the standard starting position, the game file includes the
1335 starting position used. Games are saved in the PGN (portable
1336 game notation) format, unless the oldSaveStyle option is true,
1337 in which case they are saved in an older format that is specific
1338 to @value{NAME}. Both formats are human-readable, and both can be
1339 read back by the @samp{Load Game} command.
1340 Notation of the form @samp{P@@f7}
1341 is accepted for piece-drops in bughouse games;
1342 this is a nonstandard extension to PGN.
1343
1344 @item Copy Game
1345 @cindex Copy Game, Menuitem
1346 Copies a record of the current game to an internal clipboard in PGN
1347 format and sets the X selection to the game text.  The game can be
1348 pasted to another application (such as a text editor or another copy
1349 of @value{NAME}) using that application's paste command.  In many X
1350 applications, such as xterm and emacs, the middle mouse button can be
1351 used for pasting; in @value{NAME}, you must use the Paste Game command.
1352
1353 @item Paste Game
1354 @cindex Paste Game, Menuitem
1355 Interprets the current X selection as a game record and loads it, as
1356 with Load Game.
1357
1358 @item Load Position
1359 @cindex Load Position, Menuitem
1360 Sets up a position from a position file.  A popup dialog prompts
1361 you for the file name. If the file contains more than one saved
1362 position, and you want to load the Nth one, type the number N
1363 after the file name, separated by a space. Position files must
1364 be in FEN (Forsythe-Edwards notation), or in the format that the
1365 Save Position command writes when oldSaveStyle is turned on.
1366
1367 @item Load Next Position
1368 @cindex Load Next Position, Menuitem
1369 Loads the next position from the last position file you loaded.
1370 Not available if the last position was loaded from a pipe.
1371
1372 @item Load Previous Position
1373 @cindex Load Previous Position, Menuitem
1374 Loads the previous position from the last position file you
1375 loaded.  Not available if the last position was loaded from a pipe.
1376
1377 @item Reload Same Position
1378 @cindex Reload Same Position, Menuitem
1379 Reloads the last position you loaded.
1380
1381 @item Save Position
1382 @cindex Save Game, Menuitem
1383 Appends a diagram of the current position to a file.
1384 A popup dialog
1385 prompts you for the file name. Positions are saved in
1386 FEN (Forsythe-Edwards notation) format unless the @code{oldSaveStyle}
1387 option is true, in which case they are saved in an older,
1388 human-readable format that is specific to @value{NAME}. Both formats
1389 can be read back by the @samp{Load Position} command.
1390
1391 @item Copy Position
1392 @cindex Copy Position, Menuitem
1393 Copies the current position to an internal clipboard in FEN format and
1394 sets the X selection to the position text.  The position can be pasted
1395 to another application (such as a text editor or another copy of
1396 @value{NAME}) using that application's paste command.  In many X
1397 applications, such as xterm and emacs, the middle mouse button can be
1398 used for pasting; in @value{NAME}, you must use the Paste Position command.
1399
1400 @item Paste Position
1401 @cindex Paste Position, Menuitem
1402 Interprets the current X selection as a FEN position and loads it, as
1403 with Load Position.
1404
1405 @item Mail Move
1406 @itemx Reload CMail Message
1407 @cindex Mail Move, Menuitem
1408 @cindex Reload CMail Message, Menuitem
1409 See @ref{CMail}.
1410
1411 @item Exit
1412 @cindex Exit, Menuitem
1413 Exits from @value{NAME}. The shifted @samp{Q} key is a keyboard equivalent.
1414 @end table
1415
1416
1417 @node Mode Menu
1418 @section Selecting @value{NAME}'s mode
1419 @cindex Menu, Mode
1420 @cindex Mode Menu
1421 @table @asis
1422 @item Machine White
1423 @cindex Machine White, Menuitem
1424 Forces the chess engine to play White.
1425
1426 @item Machine Black
1427 @cindex Machine Black, Menuitem
1428 Forces the chess engine to play Black.
1429
1430 @item Two Machines
1431 @cindex Two Machines, Menuitem
1432 Plays a game between two chess engines.
1433
1434 @item Analysis Mode
1435 @cindex Analysis Mode, Menuitem
1436 XBoard with Crafty only.
1437 For information on getting Crafty, see @ref{Crafty}.
1438
1439 XBoard tells Crafty to start analyzing the current game/position
1440 and shows you the analysis as you move pieces around.
1441
1442 To setup a position to analyze, you do the following:
1443
1444 1. Select Edit Position from the Mode Menu
1445
1446 2. Setup the position (use the right and middle buttons to
1447 bring up the Black/White piece menus).
1448
1449 3. When you are finished, click on either the Black or White
1450 clock to tell XBoard which side moves first.
1451
1452 4. Select Analysis Mode from the Mode Menu to start the analysis.
1453
1454 @item Analyze File
1455 @cindex Analyze File, Menuitem
1456 XBoard with Crafty only.
1457 For information on getting Crafty, see @ref{Crafty}.
1458
1459 This option lets you load a game from a file (PGN, XBoard format, etc.)
1460 and analyze it. When you select this menu item, a popup window appears
1461 and asks for a filename to load.
1462 If the file contains multiple games, another popup appears that lets
1463 you select which game you wish to analyze.
1464 After a game is loaded, use the XBoard arrow buttons to step
1465 forwards/backwards through the game and watch Crafty's analysis.
1466
1467 @item ICS Client
1468 @cindex ICS Client, Menuitem
1469 ICS mode only. Takes @value{NAME} out of the Edit Game or
1470 Edit Position state.
1471
1472 While you are examining a game on the ICS, you can issue the ICS
1473 position-editing commands with the mouse. Do this with @samp{ICS
1474 Client} selected on the Mode menu, not @samp{Edit Position}; the latter
1475 edits only your local copy of the position.
1476
1477 To drop a new piece on a square, press mouse button 2 or 3 over
1478 the square. This brings up a menu of white pieces (button 2) or
1479 black pieces (button 3).
1480 Additional menu choices let you empty the square or clear the board.
1481 You cannot set the side to play or drag pieces to arbitrary squares
1482 while examining on ICS, however; the ICS permits only legal moves
1483 in this mode.
1484
1485 If you are playing a bughouse game on the ICS, you can drop an offboard piece
1486 by pressing mouse button 2 or 3 over an empty square to bring up a piece menu.
1487 It makes no difference which button you use.  
1488 A list of the offboard pieces
1489 each player has available is shown in the window title after the player's name.
1490
1491 @item Edit Game
1492 @cindex Edit Game, Menuitem
1493 Allows you to make moves for both Black and White, and to change
1494 moves after backing up with the @samp{Backward} command. The clocks do
1495 not run.
1496
1497 In GNU Chess mode, the chess engine continues to check moves for legality
1498 but does not participate in the game. You can bring the chess engine
1499 into the game by selecting @samp{Machine White}, @samp{Machine Black},
1500 or @samp{Two Machines}.
1501
1502 In ICS mode, the moves are not sent to the ICS: @samp{Edit Game} takes
1503 @value{NAME} out of ICS Client mode and lets you edit games locally.
1504 If you want to edit games on ICS in a way that other ICS users
1505 can see, use the ICS examine command or start an ICS match
1506 against yourself.
1507
1508 @item Edit Position
1509 @cindex Edit Position, Menuitem
1510 Lets you set up an arbitrary board position.
1511 Use mouse button 1 to drag pieces to new squares, or to delete a piece
1512 by dragging it off the board or dragging an empty square on top of it.
1513 To drop a new piece on a square, press mouse button 2 or 3 over the
1514 square. This brings up a menu of white pieces (button 2) or
1515 black pieces (button 3). Additional menu choices let you empty the
1516 square or clear the board. You can set the side to play next by
1517 clicking on the White or Black indicator at the top of the screen.
1518 Selecting @samp{Edit Position} causes @value{NAME} to discard
1519 all remembered moves in the current game.
1520
1521 In ICS mode, changes made to the position by @samp{Edit Position} are
1522 not sent to the ICS: @samp{Edit Position} takes @value{NAME} out of
1523 @samp{ICS Client} mode and lets you edit positions locally. If you want to
1524 edit positions on ICS in a way that other ICS users can see, use
1525 the @samp{ICS examine} command, or start an ICS match against yourself.
1526 (See also the ICS Client topic above.)
1527
1528 @item Training
1529 @cindex Training, Menuitem
1530 Training mode lets you interactively guess the moves of a game for one
1531 of the players. You guess the next move of the game by playing the
1532 move on the board. If the move played matches the next move of the
1533 game, the move is accepted and the opponent's response is autoplayed.
1534 If the move played is incorrect, an error message is displayed.  You
1535 can select this mode only while loading a game (that is, after
1536 selecting Load Game from the File menu).  While @value{NAME} is in Training
1537 mode, the navigation buttons are disabled.
1538
1539 @item Show Game List
1540 @cindex Show Game List, Menuitem
1541 Shows or hides the list of games generated by the last @samp{Load Game}
1542 command.
1543
1544 @item Edit Tags
1545 @cindex Edit Tags, Menuitem
1546 Lets you edit the PGN (portable game notation)
1547 tags for the current game. After editing, the tags must still conform to
1548 the PGN tag syntax:
1549
1550 @example
1551 <tag-section> ::= <tag-pair> <tag-section>
1552                         <empty>
1553 <tag-pair> ::= [ <tag-name> <tag-value> ]
1554 <tag-name> ::= <identifier>
1555 <tag-value> ::= <string>
1556 @end example
1557 @noindent
1558 See the PGN Standard for full details. Here is an example:
1559
1560 @example
1561 [Event "Portoroz Interzonal"]
1562 [Site "Portoroz, Yugoslavia"]
1563 [Date "1958.08.16"]
1564 [Round "8"]
1565 [White "Robert J. Fischer"]
1566 [Black "Bent Larsen"]
1567 [Result "1-0"]
1568 @end example
1569 @noindent
1570 Any characters that do not match this syntax are silently ignored. Note that
1571 the PGN standard requires all games to have at least the seven tags shown
1572 above. Any that you omit will be filled in by @value{NAME}
1573 with @samp{?} (unknown value), or @samp{-} (inapplicable value).
1574
1575 @item Edit Comment
1576 @cindex Edit Comment, Menuitem
1577 Adds or modifies a comment on the current position. Comments are
1578 saved by @samp{Save Game} and are displayed by @samp{Load Game},
1579 @samp{Forward}, and @samp{Backward}.
1580
1581 @item ICS Input Box
1582 @cindex ICS Input Box, Menuitem
1583 If this option is set in ICS mode,
1584 @value{NAME}
1585 creates an extra window that you can use for typing in ICS commands.
1586 The input box is especially useful if you want to type in something long or do
1587 some editing on your input, because output from ICS doesn't get mixed
1588 in with your typing as it would in the main terminal window.
1589
1590 @item Pause
1591 @cindex Pause, Menuitem
1592 Pauses updates to the board, and if you are playing against a chess engine,
1593 also pauses your clock. To continue, select @samp{Pause} again, and the
1594 display will automatically update to the latest position.
1595 The @samp{P} button and keyboard @samp{p} key are equivalents.
1596
1597 If you select Pause when you are playing against a chess engine and
1598 it is not your move, the chess engine's clock
1599 will continue to run and it will eventually make a move, at which point
1600 both clocks will stop. Since board updates are paused, however,
1601 you will not see the move until you exit from Pause mode (or select Forward).
1602 This behavior is meant to simulate adjournment with a sealed move.
1603
1604 If you select Pause while you are in
1605 @code{examine} mode on ICS, you can step backward and forward in the
1606 current history of the examined game without affecting the other observers
1607 and examiners. Select Pause again to reconnect yourself to the current state
1608 of the game on ICS.
1609
1610 If you select @samp{Pause} while you are loading a game, the game stops
1611 loading. You can load more moves manually by selecting @samp{Forward}, or
1612 resume automatic loading by selecting @samp{Pause} again.
1613 @end table
1614
1615
1616 @node Action Menu
1617 @section Talking to GNU chess or ICS opponents
1618 @cindex Menu, Action
1619 @cindex Action, Menu
1620 @table @asis
1621 @item Accept
1622 @cindex Accept, Menuitem
1623 Accepts a pending match offer. If there is more than one offer
1624 pending, you will have to type in a more specific command
1625 instead of using this menu choice. ICS mode only.
1626
1627 @item Decline
1628 @cindex Decline, Menuitem
1629 Declines a pending offer (match, draw, adjourn, etc.). If there
1630 is more than one offer pending, you will have to type in a more
1631 specific command instead of using this menu choice. ICS mode only.
1632
1633 @item Call Flag
1634 @cindex Call Flag, Menuitem
1635 Calls your opponent's flag, claiming a win on time, or claiming
1636 a draw if you are both out of time. You can also call your
1637 opponent's flag by clicking on his clock or by pressing the
1638 keyboard @samp{t} key.
1639
1640 @item Draw
1641 @cindex Draw, Menuitem
1642 Offers a draw to your opponent, accepts a pending draw offer
1643 from your opponent, or claims a draw by repetition or the 50-move
1644 rule, as appropriate. The @samp{d} key is a keyboard equivalent.
1645 Not available in GNU Chess mode.
1646
1647 @item Adjourn
1648 @cindex Adjourn, Menuitem
1649 Asks your opponent to agree to adjourning the current game, or
1650 agrees to a pending adjournment offer from your opponent. ICS
1651 mode only.
1652
1653 @item Abort
1654 @cindex Abort, Menuitem
1655 Asks your opponent to agree to aborting the current game, or
1656 agrees to a pending abort offer from your opponent. An aborted
1657 game ends immediately without affecting either player's rating.
1658
1659 @item Resign
1660 @cindex Resign, Menuitem
1661 Resigns the game to your opponent. The shifted @samp{R} key is a
1662 keyboard equivalent.
1663
1664 @item Stop Observing
1665 @cindex Stop Observing, Menuitem
1666 Ends your participation in observing a game, by issuing the ICS
1667 observe command with no arguments. ICS mode only.
1668
1669 @item Stop Examining
1670 @cindex Stop Examining, Menuitem
1671 Ends your participation in examining a game, by issuing the ICS
1672 unexamine command. ICS mode only.
1673 @end table
1674
1675
1676 @node Step Menu
1677 @section Controlling the game
1678 @cindex Step Menu
1679 @cindex Menu, Step
1680 @table @asis
1681 @item Backward
1682 @cindex Backward, Menuitem
1683 @cindex <, Button
1684 Steps backward through a series of remembered moves.
1685 The @samp{[<]} button and the @samp{b} key are equivalents.
1686 In addition, pressing the Control key steps back one move, and releasing
1687 it steps forward again.
1688
1689 In most modes, @samp{Backward} only lets you look back at old positions;
1690 it does not retract moves. This is the case if you are playing against
1691 a chess engine, playing or observing a game on the ICS, or loading a game.
1692 If you select @samp{Backward} in any of these situations, you will not
1693 be allowed to make a different move. Use @samp{Retract Move} or
1694 @samp{Edit Game} if you want to change past moves.
1695
1696 If you are examining a game on ICS, the behavior of @samp{Backward}
1697 depends on whether @value{NAME} is in Pause mode. If Pause mode is
1698 off, @samp{Backward} issues the ICS backward command, which backs up
1699 everyone's view of the game and allows you to make a different
1700 move. If Pause mode is on, @samp{Backward} only backs up your local
1701 view.
1702
1703 @item Forward
1704 @cindex Forward, Menuitem
1705 @cindex >, Button
1706 Steps forward through a series of remembered moves (undoing the
1707 effect of @samp{Backward}) or forward through a game file. The
1708 @samp{[>]} button and the @samp{f} key are equivalents.
1709
1710 If you are examining a game on ICS, the behavior of Forward
1711 depends on whether @value{NAME} is in Pause mode. If Pause mode is
1712 off, @samp{Forward} issues the ICS forward command, which moves
1713 everyone's view of the game forward along the current line. If
1714 Pause mode is on, @samp{Forward} only moves your local view forward,
1715 and it will not go past the position that the game was in when
1716 you paused.
1717
1718 @item Back to Start
1719 @cindex Back to Start, Menuitem
1720 @cindex <<, Button
1721 Jumps backward to the first remembered position in the game.
1722 The @samp{[<<]} button and the shifted @samp{B} key are equivalents.
1723
1724 In most modes, Back to Start only lets you look back at old
1725 positions; it does not retract moves. This is the case if you
1726 are playing against GNU chess, playing or observing a game on
1727 the ICS, or loading a game. If you select @samp{Back to Start} in any
1728 of these situations, you will not be allowed to make different
1729 moves. Use @samp{Retract Move} or @samp{Edit Game} if you want to change past
1730 moves; or use Reset to start a new game.
1731
1732 If you are examining a game on ICS, the behavior of @samp{Back to
1733 Start} depends on whether @value{NAME} is in Pause mode. If Pause mode
1734 is off, @samp{Back to Start} issues the ICS @samp{backward 999999}
1735 command, which backs up everyone's view of the game to the start and
1736 allows you to make different moves. If Pause mode is on, @samp{Back
1737 to Start} only backs up your local view.
1738
1739 @item Forward to End
1740 @cindex Forward to End, Menuitem
1741 @cindex >>, Button
1742 Jumps forward to the last remembered position in the game. The
1743 @samp{[>>]} button and the shifted @samp{F} key are equivalents.
1744
1745 If you are examining a game on ICS, the behavior of @samp{Forward to
1746 End} depends on whether @value{NAME} is in Pause mode. If Pause mode
1747 is off, @samp{Forward to End} issues the ICS @samp{forward 999999}
1748 command, which moves everyone's view of the game forward to the end of
1749 the current line. If Pause mode is on, @samp{Forward to End} only moves
1750 your local view forward, and it will not go past the position
1751 that the game was in when you paused.
1752
1753 @item Revert
1754 @cindex Revert, Menuitem
1755 If you are examining a game on ICS and Pause mode is off, issues
1756 the ICS command @samp{revert}.
1757
1758 @item Truncate Game
1759 @cindex Truncate Game, Menuitem
1760 Discards all remembered moves of the game beyond the current
1761 position. Puts @value{NAME} into @samp{Edit Game} mode if it was not there
1762 already.
1763
1764 @item Move Now
1765 @cindex Move Now, Menuitem
1766 Forces the chess engine to move immediately. GNU Chess mode only.
1767
1768 @item Retract Move
1769 @cindex Retract Move, Menuitem
1770 Retracts your last move. In GNU Chess mode, you can do this only
1771 after the chess engine has replied to your move; if the chess engine is still
1772 thinking, use @samp{Move Now} first. In ICS mode, @samp{Retract Move}
1773 issues the command @samp{takeback 1} or @samp{takeback 2}
1774 depending on whether it is your opponent's move or yours.
1775 @end table
1776
1777
1778 @node Options Menu
1779 @section User Preferences
1780 @cindex Menu, Options
1781 @cindex Options Menu
1782 @table @asis
1783 @item Always Queen
1784 @cindex Always Queen, Menuitem
1785 If this option is off, @value{NAME} brings up a dialog
1786 box whenever you move a pawn to the last rank, asking what piece
1787 you want to promote it to. If the option is true, your pawns are
1788 always promoted to queens. Your opponent can still underpromote,
1789 however.
1790 @item Animate Dragging
1791 @cindex Animate Dragging, Menuitem
1792 If Animate Dragging is on, while you are dragging a piece with the
1793 mouse, an image of the piece follows the mouse cursor.
1794 If Animate Dragging is off, there is no visual feedback while you are
1795 dragging a piece, but if Animate Moving is on, the move will be
1796 animated when it is complete. 
1797 @item Animate Moving
1798 @cindex Animate Moving, Menuitem
1799 If Animate Moving is on, all piece moves are animated.  An image of the
1800 piece is shown moving from the old square to the new square when the
1801 move is completed (unless the move was already animated by Animate Dragging).
1802 If Animate Moving is off, a moved piece instantly disappears from its
1803 old square and reappears on its new square when the move is complete.
1804 @item Auto Comment
1805 @cindex Auto Comment, Menuitem
1806 If this option is on, any remarks made on ICS while you are observing or
1807 playing a game are recorded as a comment on the current move.  This includes
1808 remarks made with the ICS commands @kbd{say}, @kbd{tell}, @kbd{whisper},
1809 and @kbd{kibitz}.
1810 Limitation: remarks that you type yourself are not recognized;
1811 @value{NAME} scans only the output from ICS, not the input you type to it.
1812 @item Auto Flag
1813 @cindex Auto Flag, Menuitem
1814 If this option is on and one player runs out of time
1815 before the other,
1816 @value{NAME}
1817 will automatically call his flag, claiming a win on time.
1818 In ICS mode, Auto Flag will only call your opponent's flag, not yours,
1819 and the ICS may award you a draw instead of a win if you have
1820 insufficient mating material.  In local chess engine mode,
1821 @value{NAME}
1822 may call either player's flag and will not take material into account.
1823 @item Auto Flip View
1824 @cindex Auto Flip View, Menuitem
1825 If the Auto Flip View option is on when you start a game, the board
1826 will be automatically oriented so that your pawns move from the bottom
1827 of the window towards the top.
1828 @item Auto Observe
1829 @cindex Auto Observe, Menuitem
1830 If this option is on and you add a player to your @code{gnotify}
1831 list on ICS, @value{NAME} will automatically observe all of that
1832 player's games, unless you are doing something else (such as
1833 observing or playing a game of your own) when one starts.
1834 The games are displayed 
1835 from the point of view of the player on your gnotify list; that is, his
1836 pawns move from the bottom of the window towards the top.
1837 Exceptions:  If both players in a game are on your gnotify list, if
1838 your ICS 
1839 @code{highlight}
1840 variable is set to 0, or if the ICS you are using does not 
1841 properly support observing from Black's point of view,
1842 you will see the game from White's point of view.
1843 @item Auto Raise Board
1844 @cindex Auto Raise Board, Menuitem
1845 If this option is on, whenever a new game begins, the chessboard window
1846 is deiconized (if necessary) and raised to the top of the stack of windows.
1847 @item Auto Save
1848 @cindex Auto Save, Menuitem
1849 If this option is true, at the end of every game @value{NAME} prompts
1850 you for a file name and appends a record of the game to the file
1851 you specify. 
1852 Disabled if the @code{saveGameFile} command-line
1853 option is set, as in that case all games are saved to the specified file.
1854 @xref{I/O options}.
1855 @item Blindfold
1856 @cindex Blindfold, Menuitem
1857 If this option is on, @value{NAME} displays the board as usual but does
1858 not display pieces or move highlights.  You can still move in the
1859 usual way (with the mouse or by typing moves in ICS mode), even though
1860 the pieces are invisible.
1861 @item Flash Moves
1862 @cindex Flash Moves, Menuitem
1863 If this option is on, whenever a move is completed, the moved piece flashes.
1864 The number of times to flash is set by the flashCount command-line
1865 option; it defaults to 3 if Flash Moves is first turned on from the menu.
1866
1867 @item Flip View
1868 @cindex Flip View, Menuitem
1869 Inverts your view of the chess board for the duration of the
1870 current game. Starting a new game returns the board to normal.
1871 The @samp{v} key is a keyboard equivalent.
1872
1873 If you are playing a game on the ICS, the board is always
1874 oriented at the start of the game so that your pawns move from
1875 the bottom of the window towards the top. Otherwise, the starting
1876 orientation is determined by the @code{flipView} command line option;
1877 if it is false (the default), White's pawns move from bottom to top
1878 at the start of each game; if it is true, Black's pawns move from
1879 bottom to top. @xref{User interface options}.
1880
1881 @item Highlight Last Move
1882 @cindex Highlight Last Move, Menuitem
1883 If Highlight Last Move is on, after a move is made, the starting and
1884 ending squares remain highlighted. In addition, after you use Backward
1885 or Back to Start, the starting and ending squares of the last move to
1886 be unmade are highlighted.
1887
1888 @item Move Sound
1889 @cindex Move Sound, Menuitem
1890 If this option is on, @value{NAME} alerts you by playing a sound
1891 after each of your opponent's moves (or after every
1892 move if you are observing a game on the Internet Chess Server).
1893 The sound is not played after moves you make or moves read from a
1894 saved game file. By default, the
1895 sound is the terminal bell, but on some systems you can change it
1896 to a sound file using the soundMove option; see below.
1897
1898 If you turn on this option when using @value{NAME} with the Internet
1899 Chess Server, you will probably want to give the
1900
1901 @example
1902 set bell 0
1903 @end example
1904 @noindent
1905 command to the ICS, since otherwise the ICS will ring the terminal bell
1906 after every move (not just yours). (The @file{.icsrc} file
1907 is a good place for this, @pxref{ICS options})
1908
1909 @item ICS Alarm
1910 @cindex ICS Alarm, Menuitem
1911 When this option is on, an alarm sound is played when your clock
1912 counts down to the icsAlarmTime (by default, 5 seconds) in an ICS
1913 game.  For games with time controls that include an increment, the
1914 alarm will sound each time the clock counts down to the icsAlarmTime.
1915 By default, the alarm sound is the terminal bell, but on some systems
1916 you can change it to a sound file using the soundIcsAlarm option; see
1917 below.
1918
1919 @item Get Move List
1920 @cindex Get Move List, Menuitem
1921 If this option is on, whenever @value{NAME}
1922 receives the first board of a new game (or a different game from
1923 the one it is currently displaying), it
1924 retrieves the list of past moves from the ICS.
1925 You can then review the moves with the @samp{Forward} and @samp{Backward}
1926 commands
1927 or save them with @samp{Save Game}.  You might want to
1928 turn off this option if you are observing several blitz games at once,
1929 to keep from wasting time and network bandwidth fetching the move lists over
1930 and over.
1931 When you turn this option on from the menu, @value{NAME}
1932 immediately fetches the move list of the current game (if any).
1933
1934 @item Old Save Style
1935 @cindex Old Save Style, Menuitem
1936 If this option is off, @value{NAME} saves games in PGN
1937 (portable game notation) and positions in FEN (Forsythe-Edwards
1938 notation).  If the option is on, a save style that is compatible
1939 with older versions of @value{NAME} is used instead.
1940 The old position style is more human-readable
1941 than FEN; the old game style has no particular advantages.
1942
1943 @item Periodic Updates
1944 @cindex Periodic Updates, Menuitem
1945 If this option is off (or if
1946 you are using a chess engine that does not support periodic updates),
1947 the analysis window
1948 will only be updated when the analysis changes. If this option is
1949 on, the Analysis Window will be updated every two seconds.
1950
1951 @item Ponder Next Move
1952 @cindex Ponder Next Move, Menuitem
1953 If this option is off, the chess engine will think only when it is on
1954 move.  If the option is on, the engine will also think while waiting
1955 for you to make your move.
1956
1957 @item Popup Exit Message
1958 @cindex Popup Exit Message, Menuitem
1959 If this option is on, when @value{NAME} wants to display a message just
1960 before exiting, it brings up a modal dialog box and waits for you to
1961 click OK before exiting.  If the option is off, @value{NAME} prints the
1962 message to standard error (the terminal) and exits immediately.
1963
1964 @item Popup Move Errors
1965 @cindex Popup Move Errors, Menuitem
1966 If this option is off, when you make an error in moving (such as
1967 attempting an illegal move or moving the wrong color piece), the
1968 error message is displayed in the message area.  If the option is
1969 on, move errors are displayed in small popup windows like other errors.
1970 You can dismiss an error popup either by clicking its OK button or by
1971 clicking anywhere on the board, including downclicking to start a move.
1972
1973 @item Premove
1974 @cindex Premove, Menuitem
1975 If this option is on while playing a game on ICS, you can register
1976 your next planned move before it is your turn.  Move the piece with
1977 the mouse in the ordinary way, and the starting and ending squares
1978 will be highlighted with a special color (red by default).  When it is
1979 your turn, if your registered move is legal, xboard will send it to
1980 ICS immediately; if not, it will be ignored and you can make a
1981 different move.  If you change your mind about your premove, either
1982 make a different move, or double-click on any piece to cancel the move
1983 entirely.
1984
1985 @item Quiet Play
1986 @cindex Quiet Play, Menuitem
1987 If this option is on, @value{NAME} will automatically issue an ICS
1988
1989 @example
1990 set shout 0
1991 @end example
1992 @noindent
1993 command whenever you start a game and a
1994
1995 @example
1996 set shout 1
1997 @end example
1998 @noindent
1999 command whenever you finish one.  Thus, you will not be distracted
2000 by shouts from other ICS users while playing.
2001
2002 @item Show Coords
2003 @cindex Show Coords, Menuitem
2004 If this option is on, @value{NAME} displays algebraic coordinates
2005 along the board's left and bottom edges.
2006
2007 @item Show Thinking
2008 @cindex Show Thinking, Menuitem
2009 If this option is set, the chess engine's notion of the score and best
2010 line of play from the current position is displayed as it is
2011 thinking. The score indicates how many pawns ahead (or if negative,
2012 behind) the chess engine thinks it is. In matches between two
2013 machines, the score is prefixed by @samp{W} or @samp{B} to indicate
2014 whether it is showing White's thinking or Black's.
2015 @end table
2016
2017 @node Help Menu
2018 @section Getting help
2019 @cindex Menu, Help
2020 @cindex Help Menu
2021 @table @asis
2022 @item Info @value{NAME}
2023 @cindex Info @value{NAME}, Menuitem
2024 Displays this info file in a new window.  For this feature to work,
2025 you must have the GNU info program installed on your system,
2026 and the file @file{xboard.info} must either be present in the current 
2027 working directory, or have been installed by 
2028 the @samp{make install} command when you built @value{NAME}.
2029 @item Man @value{NAME}
2030 @cindex Man @value{NAME}, Menuitem
2031 Displays the @value{NAME} man page in a new window.  For this feature to work,
2032 the file @file{xboard.6} must have been installed by 
2033 the @samp{make install} command when you built @value{NAME}, and the
2034 directory it was placed in must be on the search path for your system's
2035 @samp{man} command.
2036 @item Hint
2037 @cindex Hint, Menuitem
2038 Displays a move hint from GNU Chess. GNU Chess mode only.
2039 @item Book
2040 @cindex Book, Menuitem
2041 Displays a list of possible moves from GNU Chess's opening book.
2042 The first column gives moves, the second column gives one possible
2043 response for each move, and the third column shows the
2044 number of lines in the book that include the move from the first
2045 column. If you select this option and nothing happens, GNU
2046 Chess is out of its book.  GNU Chess mode only.
2047
2048 @item About @value{NAME}
2049 @cindex About @value{NAME}, Menuitem
2050 Shows the current @value{NAME} version number.
2051 @end table
2052
2053
2054 @node Keys
2055 @section Other shortcut keys
2056 @cindex Keys
2057 @cindex Shortcut keys
2058 @table @asis
2059 @item Iconize
2060 Pressing the @samp{i} or @samp{c} key iconizes @value{NAME}. The graphical
2061 icon displays a white knight if it is white's move, or a black knight,
2062 if it is Black's move. If your X window manager displays only text icons,
2063 not graphical ones, check its documentation; there is probably a way to
2064 enable graphical icons. If you are running the Motif window manager
2065 @file{mwm} (1), add these lines to your @file{.Xdefaults} file and
2066 restart mwm:
2067
2068 @example
2069 Mwm*iconDecoration: activelabel label image
2070 Mwm*@value{NAME}*iconImageBackground: White
2071 Mwm*@value{NAME}*iconImageForeground: Black
2072 @end example
2073 @noindent
2074 The first line above enables graphical icons in mwm; you don't need it
2075 if you already have them. The next two lines force the white knights to
2076 come out white and the black knights black. Unfortunately these resources
2077 can't be set from inside @value{NAME}; you have to set them in your
2078 @file{.Xdefaults} file.
2079 @end table
2080
2081 You can add or remove shortcut keys using the X resources
2082 @code{form.translations}. Here is an example of what would go in your
2083 @file{.Xdefaults} file:
2084
2085 @example
2086 @value{NAME}*form.translations: Shift<Key>?: AboutGameProc() \n\
2087 <Key>y: AcceptProc() \n\
2088 <Key>n: DeclineProc() \n\
2089 <Key>i: NothingProc()
2090 @end example
2091 @noindent
2092 Binding a key to @code{NothingProc} makes it do nothing, thus removing
2093 it as a shortcut key. The @value{NAME} commands that can be bound to keys
2094 are:
2095
2096 @example
2097 AbortProc, AboutGameProc, AboutProc, AcceptProc, AdjournProc,
2098 AlwaysQueenProc, AnalysisModeProc, AnalyzeFileProc, AnimateDraggingProc,
2099 AnimateMovingProc, AutobsProc, AutoflagProc, AutoflipProc,
2100 AutoraiseProc, AutosaveProc, BackwardProc, BlindfoldProc, BookProc,
2101 CallFlagProc, CopyGameProc, CopyPositionProc, DebugProc, DeclineProc,
2102 DrawProc, EditCommentProc, EditGameProc, EditPositionProc, EditTagsProc,
2103 EnterKeyProc, FlashMovesProc, FlipViewProc, ForwardProc,
2104 GetMoveListProc, HighlightLastMoveProc, HintProc, Iconify, IcsAlarmProc,
2105 IcsAlarmProc, IcsClientProc, IcsInputBoxProc, InfoProc, LoadGameProc,
2106 LoadNextGameProc, LoadNextPositionProc, LoadPositionProc,
2107 LoadPrevGameProc, LoadPrevPositionProc, LoadSelectedProc,
2108 MachineBlackProc, MachineWhiteProc, MailMoveProc, ManProc, MoveNowProc,
2109 MoveSoundProc, NothingProc, OldSaveStyleProc, PasteGameProc,
2110 PastePositionProc, PauseProc, PeriodicUpdatesProc, PonderNextMoveProc,
2111 PopupExitMessageProc, PopupMoveErrorsProc, PremoveProc, QuietPlayProc,
2112 QuitProc, ReloadCmailMsgProc, ReloadGameProc, ReloadPositionProc,
2113 RematchProc, ResetProc, ResignProc, RetractMoveProc, RevertProc,
2114 SaveGameProc, SavePositionProc, ShowCoordsProc, ShowGameListProc,
2115 ShowThinkingProc, StopExaminingProc, StopObservingProc,
2116 TestLegalityProc, ToEndProc, ToStartProc, TrainingProc,
2117 TruncateGameProc, and TwoMachinesProc.
2118 @end example
2119
2120 @node ICS
2121 @chapter Using @value{NAME} with an Internet Chess Server (ICS)
2122 @cindex ICS
2123 @cindex ICS, addresses
2124 @cindex Internet Chess Server
2125 An @dfn{Internet Chess Server}, or @dfn{ICS}, is a place on the 
2126 Internet where people can get together to play chess,
2127 watch other people's games, or just chat.
2128 You can use either @code{telnet} or
2129 a client program like @value{NAME} to connect to the server.
2130 ICS is getting more and more important for chess players: 
2131 There are thousands of registered users on the different
2132 ICS hosts, and it is not unusual to meet 200 on both ICC and FICS.
2133 The number is increasing rapidly.
2134
2135 Most people can just type
2136
2137 @example
2138 @value{LCNAME} -ics
2139 @end example
2140 @noindent
2141 to start @value{NAME} as
2142 an ICS client.  Invoking @value{NAME} in this way connects you to
2143 the Internet Chess Club (ICC), a commercial ICS.  You can log in there as
2144 a guest even if you do not have a paid account.  To connect to
2145 the largest Free ICS (FICS), use the command
2146
2147 @example
2148 @value{LCNAME} -ics -icshost freechess.org
2149 @end example
2150 @noindent
2151 instead, or substitute a different host name to connect to your
2152 favorite ICS.
2153 The @file{ics-addresses} in the 
2154 @value{NAME} distribution includes a list of ICS hosts.
2155 For a full description of command-line options that control 
2156 the connection to ICS and change the default values of ICS options, see
2157 @ref{ICS options}.  
2158
2159 While you are running @value{NAME} as an ICS client,
2160 you use the terminal window that you started @value{NAME} from
2161 as a place to type in commands and read information that is
2162 not available on the chessboard.
2163
2164 The first time you need to use the terminal is to enter your login name
2165 and password, if you are a registered player. (You don't need to do
2166 this manually; the @code{icsLogon} option can do it for you.
2167 @pxref{ICS options})  If you are not registered, enter any name.
2168 If someone has already registered under that name, you'll be
2169 asked for a password; just hit return and try again.
2170 Or on ICC, you can enter @samp{g} as your name, and ICC will pick a
2171 unique (but boring) name for you.
2172
2173 Some useful ICS commands
2174 include
2175 @table @kbd
2176 @item help <topic>
2177 @cindex help, ICS command
2178 to get help on the given <topic>. To get a list of possible topics type
2179 @dfn{help} without topic.  Try the help command before you ask other
2180 people on the server for help.
2181
2182 For example @kbd{help register} tells you how to become a registered
2183 ICS player.
2184 @item who <flags>
2185 @cindex who, ICS command
2186 to see a list of people who are logged on.  Administrators
2187 (people you should talk to if you have a problem) are marked
2188 with the character @samp{*}, an asterisk. The <flags> allow you to
2189 display only selected players: For example, @kbd{who of} shows a
2190 list of players who are interested in playing but do not have
2191 an opponent.
2192 @item games
2193 @cindex games, ICS command
2194 to see what games are being played
2195 @item match <player> [<mins>] [<inc>]
2196 to challenge another player to a game. Both opponents get <mins> minutes
2197 for the game, and <inc> seconds will be added after each move.
2198 If another player challenges you, the server asks if you want to
2199 accept the challenge; use the @kbd{accept} or @kbd{decline} commands
2200 to answer.
2201 @item accept
2202 @itemx decline
2203 @cindex accept, ICS command
2204 @cindex decline, ICS command
2205 to accept or decline another player's offer. 
2206 The offer may be to start a new game, or to agree to a 
2207 @kbd{draw}, @kbd{adjourn} or @kbd{abort} the current game. @xref{Action Menu}.
2208
2209 If you have more than one pending offer (for example, if more than one player
2210 is challenging you, or if your opponent offers both a draw and to adjourn the
2211 game), you have to supply additional information, by typing something
2212 like @kbd{accept <player>}, @kbd{accept draw}, or @kbd{draw}.
2213
2214 @item draw
2215 @itemx adjourn
2216 @itemx abort
2217 @cindex draw, ICS command
2218 @cindex adjourn, ICS command
2219 @cindex abort, ICS command
2220 asks your opponent to terminate a game by mutual agreement. Adjourned
2221 games can be continued later. 
2222 Your opponent can either @kbd{decline} your offer or accept it (by typing the
2223 same command or typing @kbd{accept}).  In some cases these commands work
2224 immediately, without asking your opponent to agree.  For example, you can
2225 abort the game unilaterally if your opponent is out of time, and you can claim
2226 a draw by repetition or the 50-move rule if available simply by typing 
2227 @kbd{draw}.
2228 @item finger <player>
2229 @cindex finger, ICS command
2230 to get informations about the given <player>. (Default: yourself.)
2231 @item vars
2232 @cindex vars, ICS command
2233 to get a list of personal settings
2234 @item set <var> <value>
2235 @cindex set, ICS command
2236 to modify these settings
2237 @item observe <player>
2238 @cindex observe, ICS command
2239 to observe an ongoing game of the given <player>.
2240 @item examine
2241 @itemx oldmoves
2242 @cindex examine, ICS command
2243 @cindex oldmoves, ICS command
2244 to review a recently completed game
2245 @end table
2246
2247 Some special @value{NAME} features are activated when you are
2248 in examine mode on ICS.  See the descriptions of the menu commands
2249 @samp{Forward}, @samp{Backward}, @samp{Pause}, @samp{ICS Client}, 
2250 and @samp{Stop Examining} on the @ref{Step Menu}, @ref{Mode Menu}, and
2251 @ref{Options Menu}.
2252
2253 @node Firewalls
2254 @chapter Connecting to the ICS through a firewall
2255 By default, @value{NAME} communicates with an Internet Chess Server
2256 by opening a TCP socket directly from the machine it is running on
2257 to the ICS. If there is a firewall between your machine and the ICS,
2258 this won't work. Here are some recipes for getting around common
2259 kinds of firewalls using special options to @value{NAME}.
2260 Important: See the paragraph in the below about extra echoes, in
2261 @ref{Limitations}.
2262
2263 Suppose that you can't telnet directly to ICS, but you can telnet
2264 to a firewall host, log in, and then telnet from there to ICS.
2265 Let's say the firewall is called @samp{fire.wall.com}. Set
2266 command-line options as follows:
2267
2268 @example
2269 xboard -ics -icshost fire.wall.com -icsport 23
2270 @end example
2271 @noindent
2272 Or in your @file{.Xdefaults} file:
2273
2274 @example
2275 XBoard*internetChessServerHost: fire.wall.com
2276 XBoard*internetChessServerPort: 23
2277 @end example
2278 @noindent
2279 Then when you run @value{NAME} in ICS mode, you will be prompted
2280 to log in to the firewall host. (This works because port 23 is the
2281 standard telnet login service.) Do so, then telnet to ICS, using a
2282 command like @samp{telnet chessclub.com 5000}, or whatever command
2283 the firewall provides for telnetting to port 5000.
2284
2285 If your firewall lets you telnet (or rlogin) to remote hosts, but
2286 doesn't let you telnet to port 5000, you will have to find some
2287 other host outside the firewall that does let you do this, and
2288 hop through it. For instance, suppose you have an account at
2289 @samp{foo.edu}. Follow the recipe above, but instead of typing
2290 @samp{telnet chessclub.com 5000} to the firewall, type
2291 @samp{telnet foo.edu} (or @samp{rlogin foo.edu}), log in there, and
2292 then type @samp{telnet chessclub.com 5000}.
2293
2294 Exception: chessclub.com itself lets you connect to the chess server on the
2295 default telnet port (23), which is what you get if you don't specify a port
2296 to the telnet program. But the other chess servers don't allow this.
2297
2298 Suppose that you can't telnet directly to ICS, but you can use rsh
2299 to run programs on a firewall host, and that host can telnet to ICS.
2300 Let's say the firewall is called @samp{rsh.wall.com}. Set
2301 command-line options as follows:
2302
2303 @example
2304 xboard -ics -gateway rsh.wall.com -icshost chessclub.com
2305 @end example
2306 @noindent
2307 Or in your @file{.Xdefaults} file:
2308
2309 @example
2310 XBoard*gateway: rsh.wall.com
2311 XBoard*internetChessServerHost: chessclub.com
2312 @end example
2313 Then when you run @value{NAME} in ICS mode, it will connect to
2314 the ICS by using @file{rsh} to run the command @samp{telnet
2315 chessclub.com 5000} on host @samp{rsh.wall.com}.
2316
2317 Suppose that you can telnet anywhere you want, but you have to
2318 run a special program called @file{ptelnet} to do so.
2319
2320 First, we'll consider the easy case, in which
2321 @samp{ptelnet chessclub.com 5000} gets you to the chess server.
2322 In this case set command line options as follows:
2323
2324 @example
2325 xboard -ics -telnet -telnetProgram ptelnet
2326 @end example
2327 @noindent
2328 Or in your @file{.Xdefaults} file:
2329
2330 @example
2331 XBoard*useTelnet: true
2332 XBoard*telnetProgram: ptelnet
2333 @end example
2334 @noindent
2335 Then when you run @value{NAME} in ICS mode, it will issue the
2336 command @samp{ptelnet chessclub.com 5000} to connect to the ICS.
2337
2338 Next, suppose that @samp{ptelnet chessclub.com 5000} doesn't work;
2339 that is, your @file{ptelnet} program doesn't let you connect to
2340 alternative ports. In this case, you will have to find some other
2341 host outside the firewall that does let you do this, and hop
2342 through it. For instance, suppose you have an account at
2343 @samp{foo.edu}. Set command line options as follows:
2344
2345 @example
2346 xboard -ics -telnet -telnetProgram ptelnet -icshost foo.edu -icsport ""
2347 @end example
2348 @noindent
2349 Or in your @file{.Xdefaults} file:
2350
2351 @example
2352 XBoard*useTelnet: true
2353 XBoard*telnetProgram: ptelnet
2354 XBoard*internetChessServerHost: foo.edu
2355 XBoard*internetChessServerPort:
2356 @end example
2357 @noindent
2358 Then when you run @value{NAME} in ICS mode, it will issue the
2359 command @samp{ptelnet foo.edu} to connect to your account at
2360 @samp{foo.edu}. Log in there, then type @samp{telnet chessclub.com 5000}.
2361
2362 ICC timestamp and FICS timeseal do not work through many
2363 firewalls.  You can use them only if your firewall gives a clean TCP
2364 connection with a full 8-bit wide path.  If your firewall allows you
2365 to get out only by running a special telnet program, you can't use
2366 timestamp or timeseal across it.  But if you have access to a
2367 computer just outside your firewall, and you have much lower netlag
2368 when talking to that computer than to the ICS, it might be worthwhile
2369 running timestamp there.  Follow the instructions above for hopping
2370 through a host outside the firewall (foo.edu in the example),
2371 but run timestamp or timeseal on that host instead of telnet.
2372
2373 Suppose that you have a SOCKS firewall that requires you to go through
2374 some extra level of authentication, but after that will give you a
2375 clean 8-bit wide TCP connection to the chess server.  In that case,
2376 you could make a socksified version of 
2377 @value{NAME}
2378 and run that.  If you are using timestamp or timeseal,
2379 you will to socksify it, not
2380 @value{NAME};
2381 this may be difficult seeing that ICC and FICS do not
2382 provide source code for these programs.
2383 Socksification is beyond the scope of this document, but
2384 see the SOCKS Web site at http://www.socks.nec.com/how2socksify.html.
2385
2386 @node Environment
2387 @chapter Environment variables
2388 @cindex Environment variables
2389 @cindex CHESSDIR
2390 Game and position files are found in a directory named by the
2391 @code{CHESSDIR} environment variable. If this variable is not set, the
2392 current working directory is used. If @code{CHESSDIR} is set,
2393 @value{NAME} actually changes its working directory to
2394 @code{$CHESSDIR}, so GNU Chess listing files will also be stored there
2395 as well.
2396
2397 @node Limitations
2398 @chapter Known limitations and bugs
2399 @cindex Limitations
2400 @cindex Bugs
2401 There is no way for two people running copies of @value{NAME} to play
2402 each other without going through the @code{Internet Chess Server}.
2403
2404 Under some circumstances, your ICS password may be echoed when you log on.
2405
2406 If you are connecting to the ICS by running telnet on an Internet provider
2407 or firewall host, you may find that each line you type is echoed back an extra
2408 time after you hit Return. If your Internet provider is a Unix system, you can
2409 probably turn its echo off by typing
2410
2411 @example
2412 stty -echo
2413 @end example
2414 @noindent
2415 after you log in, and/or typing @key{^E-Return} (@key{control-E} followed by
2416 the @key{Return} key) to the telnet program after you have logged into ICS.
2417 It is a good idea to do this if you can, because the extra echo can
2418 occasionally confuse @value{NAME}'s parsing routines.
2419
2420 The game parser recognizes only algebraic notation.
2421
2422 The internal move legality tester does not look at the game history,
2423 so in some cases it misses illegal castling or en passant captures.
2424 It permits castling with the king on the d file because this is possible in
2425 some "wild 1" games on ICS.  It does not check
2426 piece drops in bughouse and crazyhouse to see if you actually
2427 hold the piece you are trying to drop.
2428 However, if you attempt an illegal move when using
2429 GNU Chess (or the ICS), @value{NAME} will accept the error message
2430 that comes back, undo the move, and let you try another.
2431
2432 Fischer Random castling is not understood.  You can probably play
2433 Fischer Random successfully on ICS by typing castling moves into the ICS
2434 Interaction window, but they will not be animated correctly, and saved
2435 games will not be loaded correctly if castling occurs.
2436
2437 FEN positions saved by @value{NAME}
2438 never include correct information about whether castling is legal or
2439 how many half-moves have been made since the last irreversible move,
2440 and sometimes may not correctly indicate when en passant capture is available.
2441
2442 The mate detector does not understand that non-contact mate is not
2443 really mate in bughouse and crazyhouse.  The only problem this causes
2444 while playing is minor: a @samp{#} (mate indicator) character will show
2445 up after a non-contact mating move in the move list; @value{NAME} will
2446 not assume the game is over at that point.  However, if you are editing
2447 a game, Edit Game mode will be terminated by a non-contact mate.
2448
2449 Some @value{NAME} functions may not work with versions of GNU Chess earlier
2450 than 4.0, patchlevel 77,
2451 or with versions of Crafty earlier than 15.11.
2452 A few functions work with GNU Chess but not Crafty, or vice versa.
2453
2454 The menus may not work if your keyboard is in Caps Lock or Num Lock mode.
2455 This seems to be a problem with the Athena menu widget,
2456 not an @value{NAME} bug.
2457
2458 Also see the ToDo file included with the distribution for many other
2459 possible bugs, limitations, and ideas for improvement that have been
2460 suggested.
2461 @node Problems
2462 @chapter Reporting problems
2463 @cindex Bugs
2464 @cindex Bug reports
2465 @cindex Reporting bugs
2466 @cindex Problems
2467 @cindex Reporting problems
2468
2469 Report bugs and problems with @value{NAME} to
2470 @example
2471 tim@@tim-mann.org.
2472 @end example
2473
2474 Please use the @file{script} program to start a typescript, run 
2475 @value{NAME} with the @samp{-debug} option, and include the typescript
2476 output in your message.
2477 Also tell us what kind of machine and what operating system version
2478 you are using.  The command @samp{uname -a} will often tell you this.
2479 Here is a sample of approximately what you should type:
2480
2481 @example
2482 script
2483 uname -a
2484 ./configure
2485 make
2486 ./xboard -debug
2487 exit
2488 mail tim@@tim-mann.org
2489 Subject: Your short description of the problem
2490 Your detailed description of the problem
2491 ~r typescript
2492 .
2493 @end example
2494
2495 If you improve @value{NAME}, please send a message about your changes,
2496 and we will get in touch with you about merging them in
2497 to the main line of development.
2498
2499 Send CMail bug reports/suggestions to
2500 @example
2501 evan@@quadstone.co.uk
2502 @end example
2503
2504 @node Contributors
2505 @chapter Authors and contributors to @value{NAME}
2506 @cindex Authors
2507 @cindex Contributors
2508 @table @asis
2509 @item Tim Mann (tim@@tim-mann.org)
2510 has been responsible for XBoard versions 1.3 and beyond, and for
2511 WinBoard, a port of XBoard to Microsoft Win32 (Windows NT and
2512 Windows 95)
2513
2514 @item Mark Williams 
2515 contributed the initial (WinBoard-only) implementation
2516 of many new features added to both XBoard and WinBoard in version 4.1.0,
2517 including copy/paste, premove, icsAlarm, autoFlipView, training mode,
2518 auto raise, and blindfold.  
2519
2520 @item Ben Nye contributed X copy/paste code for XBoard.
2521
2522 @item Hugh Fisher (Hugh.Fisher@@cs.anu.edu.au)
2523 added animated piece movement to XBoard, and
2524 Henrik Gram (henrikg@@funcom.com) added it to WinBoard.
2525
2526 @item Frank McIngvale (frankm@@hiwaay.net)
2527 added click/click moving, the Analysis modes,
2528 piece flashing, ZIICS import, and ICS text colorization to XBoard.
2529
2530 @item Jochen Wiedmann (wiedmann@@neckar-alb.de)
2531 ported XBoard to the Amiga, creating AmyBoard, and converted the
2532 documentation to texinfo.  He was responsible for AmyBoard versions through
2533 330.5 (based on xboard 3.3.pl0).
2534
2535 @item Elmar Bartel
2536 contributed the new piece bitmaps introduced in version 3.2.
2537
2538 @item Evan Welsh (Evan.Welsh@@msdw.com)
2539 wrote @code{CMail}.
2540
2541 @item Patrick Surry
2542 helped with design, testing and documenting CMail.
2543
2544 @item John Chanak
2545 contributed the initial implementation of ICS mode.
2546
2547 @item Wayne Christopher
2548 created @code{XChess}; the color scheme and the old 80x80 piece bitmaps
2549 were taken from it.
2550
2551 @item Chris Sears and Dan Sears
2552 wrote the original XBoard.  They were responsible for versions 1.0
2553 through 1.2.
2554 @end table
2555
2556 @node CMail
2557 @chapter Using @value{NAME} for electronic correspondence chess
2558 @cindex cmail
2559 The @file{cmail} program will help you play chess by email with opponents of
2560 your choice using @value{NAME} as an interface.
2561
2562 You will usually run @file{cmail} without giving any options.
2563
2564 @menu
2565 * CMail options::  Invoking CMail.
2566 * CMail game::     Starting a CMail game.
2567 * CMail answer::   Answering a move.
2568 * CMail trouble::  Known CMail problems.
2569 @end menu
2570
2571
2572 @node CMail options
2573 @section Invoking CMail.
2574 @table @asis
2575 @item -h
2576 Displays @file{cmail} usage information.
2577 @item -c
2578 Shows the conditions of the GNU General Public License.
2579 @xref{Copying}.
2580 @item -w
2581 Shows the warranty notice of the GNU General Public License.
2582 @xref{Copying}.
2583 @item -v
2584 @itemx -xv
2585 Provides or inhibits verbose output from @file{cmail} and @value{NAME},
2586 useful for debugging. The
2587 @code{-xv}
2588 form also inhibits the cmail introduction message.
2589 @item -mail
2590 @itemx -xmail
2591 Invokes or inhibits the sending of a mail message containing the move.
2592 @item -xboard
2593 @itemx -xxboard
2594 Invokes or inhibits the running of @value{NAME} on the game file.
2595 @item -reuse
2596 @itemx -xreuse
2597 Invokes or inhibits the reuse of an existing @value{NAME} to display the
2598 current game.
2599 @item -remail
2600 Resends the last mail message for that game. This inhibits running
2601 @value{NAME}.
2602 @item -game <name>
2603 The name of the game to be processed.
2604 @item -wgames <number>
2605 @itemx -bgames <number>
2606 @itemx -games <number>
2607 Number of games to start as White, as Black or in total. Default is 1 as
2608 white and none as black. If only one color is specified then none of the
2609 other color is assumed. If no color is specified then equal numbers of
2610 White and Black games are started, with the extra game being as White if an
2611 odd number of total games is specified.
2612 @item -me <short name>
2613 @itemx -opp <short name>
2614 A one-word alias for yourself or your opponent.
2615 @item -wname <full name>
2616 @itemx -bname <full name>
2617 @itemx -name <full name>
2618 @itemx -oppname <full name>
2619 The full name of White, Black, yourself or your opponent.
2620 @item -wna <net address>
2621 @itemx -bna <net address>
2622 @itemx -na <net address>
2623 @itemx -oppna <net address>
2624 The email address of White, Black, yourself or your opponent.
2625 @item -dir <directory>
2626 The directory in which @file{cmail} keeps its files. This defaults to the
2627 environment variable @code{$CMAIL_DIR} or failing that, @code{$CHESSDIR},
2628 @file{$HOME/Chess} or @file{~/Chess}. It will be created if it does not exist.
2629 @item -arcdir <directory>
2630 The directory in which @file{cmail} archives completed games. Defaults to
2631 the environment variable @code{$CMAIL_ARCDIR} or, in its absence, the same
2632 directory as cmail keeps its working files (above).
2633 @item -mailprog <mail program>
2634 The program used by cmail to send email messages. This defaults to the
2635 environment variable @code{$CMAIL_MAILPROG} or failing that
2636 @file{/usr/ucb/Mail}, @file{/usr/ucb/mail} or @file{Mail}. You will need
2637 to set this variable if none of the above paths fit your system.
2638 @item -gamesFile <file>
2639 @cindex .cmailgames
2640 A file containing a list of games with email addresses. This defaults to
2641 the environment variable @code{$CMAIL_GAMES} or failing that
2642 @file{.cmailgames}.
2643 @item -aliasesFile <file>
2644 @cindex .cmailaliases
2645 A file containing one or more aliases for a set of email addresses. This
2646 defaults to the environment variable @code{$CMAIL_ALIASES} or failing
2647 that @file{.cmailaliases}.
2648 @item -logFile <file>
2649 A file in which to dump verbose debugging messages that are invoked with
2650 the @samp{-v}
2651 option.
2652 @item -event <event>
2653 The PGN Event tag (default @samp{Email correspondence game}).
2654 @item -site <site>
2655 The PGN Site tag (default @samp{NET}).
2656 @item -round <round>
2657 The PGN Round tag (default @samp{-}, not applicable).
2658 @item -mode <mode>
2659 The PGN Mode tag (default @samp{EM}, Electronic Mail).
2660 @item OTHER OPTIONS
2661 Any unrecognized flags will be passed to @value{NAME}.
2662 Those most relevant for use with Icmail\fP are
2663 @samp{-timeDelay}, @samp{-noChessProgram}, @samp{-searchTime},
2664 @samp{-searchDepth}, @samp{-saveGameFile}, @samp{-autosave},
2665 @samp{-savePositionFile} and @samp{-boardSize}. @xref{Invocation}.
2666 @end table
2667
2668
2669 @node CMail game
2670 @section Starting a CMail game.
2671 Type @file{cmail} from a shell to start a game as white. After an opening
2672 message, you will be prompted for a game name, which is optional -- if you
2673 simply press return, the game name will take the form
2674 @samp{you-VS-opponent}. You will next be prompted for the short name
2675 of your opponent. If you haven't played this person before, you will also
2676 be prompted for his/her email address. @file{cmail} will then invoke
2677 @value{NAME} in the background. Make your first move and select
2678 @samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. If all is well,
2679 @file{cmail} will mail a copy of the move to your opponent. If you select
2680 @samp{Exit} without having selected @samp{Mail Move} then no move will be
2681 made.
2682
2683
2684 @node CMail answer
2685 @section Answering a move.
2686 When you receive a message from an opponent containing a move in one of
2687 your games, simply pipe the message through @file{cmail}. In some mailers
2688 this is as simple as typing @kbd{| cmail} when viewing the message, while in
2689 others you may have to save the message to a file and do @kbd{cmail < file}
2690 at the command line. In either case @file{cmail} will display the game using
2691 @value{NAME}. If you didn't exit @value{NAME} when you made your first move
2692 then @file{cmail} will do its best to use the existing @value{NAME} instead
2693 of starting a new one. As before, simply make a move and select
2694 @samp{Mail Move} from the @samp{File} menu. @xref{File Menu}. @file{cmail}
2695 will try to use the
2696 @value{NAME} that was most recently used to display the current game. This
2697 means that many games can be in progress simultaneously, each with its own
2698 active @value{NAME}.
2699
2700 If you want to look at the history or explore a variation, go ahead, but
2701 you must return to the current position before @value{NAME} will allow you
2702 to mail a move. If you edit the game's history you must select
2703 @samp{Reload Same Game} from the @samp{File} menu to get back to the original
2704 position, then make the move you want and select @samp{Mail Move}.
2705 As before, if you decide you aren't ready to make a move just yet you can
2706 either select @samp{Exit} without sending a move or just leave
2707 @value{NAME} running until you are ready.
2708
2709 Because @value{NAME} can now detect checkmate and stalemate, @file{cmail}
2710 now handles game termination sensibly. As well as resignation, the
2711 @samp{Action} menu now allows draws to be offered and accepted for
2712 @file{cmail} games.
2713
2714 For multi-game messages, only unfinished and just-finished games will be
2715 included in email messages. When all the games are finished, they are
2716 archived in the user's archive directory, and similarly in the opponent's
2717 when he or she pipes the final message through @file{cmail}. The archive
2718 file name includes the date the game was started.
2719
2720 It's possible to have a @file{cmail} message carry more than one game.
2721 This feature was implemented to handle IECG (International Email Chess
2722 Group) matches, where a match consists of 1 game as white and 1 as black,
2723 with moves transmitted simultaneously. In case there are more general uses,
2724 @file{cmail} itself places no limit on the number of black/white games
2725 contained in a message; however, @value{NAME} does.
2726
2727
2728 @node CMail trouble
2729 @section Known CMail problems.
2730 It's possible that a strange conjunction of conditions may occasionally
2731 mean that @file{cmail} has trouble reactivating an existing
2732 @value{NAME}. If this should happen, simply trying it again should work.
2733 If not, remove the file that stores the @value{NAME}'s PID
2734 (@file{game.pid}) or use the @samp{-xreuse} option to force
2735 @file{cmail} to start a new @value{NAME}.
2736
2737 Versions of @file{cmail} after 2.16 no longer understand the old file format
2738 that @value{NAME} used to use and so cannot be used to correspond with
2739 anyone using an older version.
2740
2741 Versions of @file{cmail} older than 2.11 do not handle multi-game messages,
2742 so multi-game correspondence is not possible with opponents using an older
2743 version.
2744
2745 @node Programs
2746 @chapter Other programs you can use with @value{NAME}
2747 @cindex Programs
2748
2749 Here are some other programs you can use with @value{NAME}
2750
2751 @menu
2752 * GNU Chess::        The GNU Chess engine
2753 * Crafty::           The Crafty chess engine
2754 * zic2xpm::          The program used to import chess sets from ZIICS
2755 @end menu
2756
2757 @node GNU Chess
2758 @section GNU Chess
2759
2760 The GNU Chess engine is available from:
2761
2762 ftp://ftp.gnu.org/gnu/gnuchess/
2763
2764 You can use XBoard to play a game against GNU Chess, or to
2765 interface GNU Chess to an ICS.
2766
2767 @node Crafty
2768 @section Crafty
2769
2770 Crafty is a chess engine written by Bob Hyatt (hyatt@@cis.uab.edu).
2771 You can use XBoard to play a game against Crafty, hook Crafty up
2772 to an ICS, or use Crafty to interactively analyze games and positions
2773 for you.
2774
2775 Crafty is a strong, rapidly evolving chess program. This rapid
2776 pace of development is good, because it means Crafty is always
2777 getting better.  This can sometimes cause problems with
2778 backwards compatibility, but usually the latest version of Crafty
2779 will work well with the latest version of @value{NAME}.
2780 Crafty can be obtained from its author's FTP site:
2781 ftp://ftp.cis.uab.edu/hyatt/.
2782
2783 To use Crafty with XBoard, give the -fcp and -fd options as follows, where
2784 <crafty's directory> is the directory in which you installed Crafty
2785 and placed its book and other support files.
2786
2787 @node zic2xpm
2788 @section zic2xpm
2789
2790 The ``zic2xpm'' program is used to import chess sets from the ZIICS(*)
2791 program into XBoard. ``zic2xpm'' is part of the XBoard distribution.
2792 ZIICS is available from:
2793
2794 ftp://ftp.freechess.org/pub/chess/DOS/ziics131.exe
2795
2796
2797 To import ZIICS pieces, do this:
2798
2799 @table @asis
2800 @item 1. Unzip ziics131.exe into a directory:
2801
2802 @example
2803 unzip -L ziics131.exe -d ~/ziics
2804 @end example
2805
2806 @item 2. Use zic2xpm to convert a set of pieces to XBoard format.
2807
2808 For example, let's say you want to use the
2809 FRITZ4 set. These files are named ``fritz4.*'' in the ZIICS distribution.
2810
2811 @example
2812 mkdir ~/fritz4
2813 cd ~/fritz4
2814 zic2xpm ~/ziics/fritz4.*
2815 @end example
2816
2817 @item 3. Now, either give XBoard the ``-pixmap'' option when starting up, e.g.:
2818
2819 @example
2820 xboard -pixmap ~/fritz4
2821 @end example
2822
2823 Or, add this line to your .Xdefaults file:
2824
2825 @example
2826 xboard*pixmapDirectory: ~/fritz4
2827 @end example
2828 @end table
2829
2830 (*) ZIICS is a separate copyrighted work of Andy McFarland (Zek on ICS).
2831 The ``ZIICS pieces'' are copyrighted works of their respective
2832 creators. Files produced by ``zic2xpm'' are for PERSONAL USE ONLY
2833 and may NOT be redistributed without explicit permission from
2834 the original creator(s) of the pieces.
2835
2836 @node Copying
2837 @unnumbered GNU GENERAL PUBLIC LICENSE
2838 @include gpl.texinfo
2839
2840 @node Index
2841 @unnumbered Index
2842
2843
2844 @printindex cp
2845 @contents
2846