This file documents the use of NAME. NAME is a graphical chessboard that can serve as a user interface for GNU Chess, for the Internet Chess Server, or for electronic mail correspondence chess. NAME can also be used by itself.

Published by the Free Software Foundation 675 Massachusetts Avenue Cambridge, MA 02139 USA

Copyright (C) 1995 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled ``GNU General Public License,'' is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled ``GNU General Public License,'' and this permission notice, may be included in translations approved by the Free Software Foundation instead of in the original English.

Introduction
************

This manual documents how to run and install NAME and how to report bugs.

GNU GENERAL PUBLIC LICENSE
**************************

     [file gpl.texinfo not included]

How to configure, compile and install NAME.
*******************************************

NAME is usually distributed as source. You need to compile this sources with any C compiler.

A shell script called configure will attempt to adapt the sources to your system and C compiler. It is important to execute this script before attempting to compile the sources. Usually you would use configure like below

         ./configure --prefix=/usr/local

This will install the NAME in /usr/local/bin, man pages in /usr/local/man etc. (/usr/local is the default, you may omit this option, if you don't want another installation directory. configure will create a Makefile for you, thus you can compile the sources with

         make

once configure is done. If all goes well and no error messages occur, you finish the installation with

         make install

Please read the file INSTALL for details about configure, the files it creates and how to configure configure itself. See the file FAQ for answers to frequently asked questions.

After the installation is done, you can remove the sources.

Command options supported by NAME.
**********************************

NAME always runs in one of 4 possible modes:

LCNAME [options]
     starts NAME as a GNU chess interface. As an interface to GNU Chess, NAME lets you play a game against the machine, set up arbitrary positions, force variations, or watch a game between two machines.

LCNAME -ics [options]
     lets NAME act as an interface to the Internet Chess Server (ICS). You can play against other ICS users, observe games they are playing, or review games that have recently finished. See ICS.

LCNAME -ncp [options]
     allows to use NAME as a simple chessboard to play through games. It will read and write game files and allow you to play through variations manually. You can use it to browse games off the net or review GNU Chess, ICS, and correspondence games you have saved. These features are available at all times; even if you do not have access to GNU Chess or the ICS, you can use them.

cmail
     will use NAME as an interface to electronic mail correspondence chess. See CMail.

Most of the NAME options have both a long name and a short name. To turn a boolean option on or off from the command line, either give its long name followed by the value TRUE or FALSE (-longOptionName true), or give just the short name to turn the option on (-opt), or the short name preceded by x to turn the option off (-xopt). For options that take strings or numbers as values, you can use the long or short option names interchangeably.

Each option corresponds to an X resource with the same name, so you can set options in your .Xdefaults file if you like. For options that have two names, the longer one is the name of the corresponding X resource; the short name is not recognized in .Xdefaults. To turn a boolean option on or off in your .Xdefaults file, give its long name followed by the value TRUE or FALSE:

         XBoard*longOptionName: true

Controlling GNU Chess
=====================

-tc or -timeControl minutes[:seconds]
-mps or -movesPerSession moves
     Each player begins with the specified amount of time on his clock. If a player makes the specified number of moves before his clock runs out, NAME adds the specified amount of time to his clock. Default: 40 moves in 5 minutes.

-clock or -clockMode
     Determines whether or not to display the chess clocks. If clockMode is false, the clocks are not shown, but the side that is to play next is still highlighted. Also, unless SEARCHTIME or SEARCHDEPTH is set, GNU Chess still keeps track of the clock time and uses it to determine how fast to make its moves.

-st or -searchTime minutes[:seconds]
     Tells GNU Chess to spend at most the given amount of time searching for each of its moves. Without this option, GNU Chess chooses its search time based on the number of moves and amount of time remaining until the next time control. Setting this option also sets CLOCKMODE to false.

-sd or -searchDepth number
     Tells GNU Chess to look ahead at most the given number of moves when searching for a move to make. Without this option, GNU Chess chooses its search depth based on the number of moves and amount of time remaining until the next time control. Setting this option also sets CLOCKMODE to false.

-thinking or -showThinking
     If this option is set, GNU Chess's notion of the score and best line of play from the current position is displayed as it is thinking. The score indicates how many pawns ahead (or if nega- tive, behind) GNU Chess thinks it is. In matches between two machines, the score is prefixed by W or B to indicate whether it is showing White's thinking or Black's.

-mm or -matchMode
     Automatically runs a game between two chess programs.  If the LOADGAMEFILE or LOADPOSITIONFILE option is set, NAME starts the game with the given opening moves or the given position; otherwise, the game starts with the standard initial chess position. If the SAVEGAMEFILE option is set, a move record for the match is appended to the specified file. If the SAVEPOSITIONFILE option is set, the final position reached in the match is appended to the specified file. When the match is over, NAME exits. Default: false.

-fcp or -firstChessProgram program
     Name of first chess program.  In matches between two machines, this program plays Black. Default: gnuchessx.

-scp or -secondChessProgram program
     Name of second chess program, if needed. In matches between two machines, this program plays White; otherwise it is not started. Default: gnuchessx.

-fh or -firstHost host
-sh or -secondHost host
     Hosts on which the chess programs are to run. The default for each is localhost. If you specify another host, NAME uses rsh (1) to run the chess program there. (You can substitute a different remote shell program for rsh using the REMOTESHELL option described below.)

-initString string
     The string that is sent to initialize the chess program. Default:

              new
              beep
              random
              easy

     If you change this option, don't remove the new and beep commands. You can remove the random command if you like; including it causes GNU Chess to randomize its move selection slightly so that it doesn't play the same moves in every game. (Even without random, GNU Chess randomizes its choice of moves from its opening book.) You can also remove easy if you like; including it toggles easy mode off, causing GNU Chess to think on your time. That is, if easy is included in the initString, GNU Chess thinks on your time; if not, it does not. (Yes, this does seem backwards, doesn't it!) You can also try adding other commands to the initString; see the GNU Chess documentation for details.

-whiteString string
-blackString string
     These options control what is sent when the Machine White and Machine Black buttons are selected. This is mostly for compati- bility with obsolete versions of GNU Chess.

Connecting to and using ICS
===========================

-ics or -internetChessServerMode
     Connect with an Internet Chess Server to play chess against its other users, observe games they are playing, or review games that have recently finished. Default: false. To use NAME in ICS mode, run it in the foreground, and use the terminal you started it from to type commands and receive text responses from the chess server. See ICS. See File Menu. See Step Menu. See Mode Menu.

-icslogon or -internetChessServerLogonScript file-name
     Whenever NAME connects to the Internet Chess Server, if it finds a file with the name given in this option, it feeds the file's contents to the ICS as commands. The default file name is .icsrc. Usually the first two lines of the file should be your ICS user name and password. The file can be either in $CHESSDIR, in NAME's working directory if CHESSDIR is not set, or in your home directory.

-autoflag or -autoCallFlag
     If AUTOCALLFLAG is true and your opponent runs out of time before you do, NAME will automatically call his flag, claiming a win on time (or a draw if you do not have mating material). Default: false.

-autobs or -autoObserve
     If AUTOOBSERVE is true and you add a player to your gnotify list on ICS, NAME will automatically observe all of that player's games, unless you are doing something else (such as observing or playing a game of your own) when one starts. Default: false.

-quiet or -quietPlay
     If this option is true, NAME will automatically issue a

              set shout 0

     command whenever you start an ICS game and a

              set shout 1

     command whenever you finish one. Default: false.

-icshost or -internetChessServerHost host
     The Internet host name or address of the chess server to connect to when in ICS mode. Default: chess.lm.com. See the file ics-addresses in the NAME source distribution for a list of other addresses to try. See also the output of the command

              finger chess@ics.onenet.net

     If your site doesn't have a working Internet name server, try specifying the host address in numeric form. The address for chess.lm.com is 192.231.221.16.

-icsport or -internetChessServerPort port-number
     The port number to use when connecting to a chess server in ICS mode. Default: 5000.

-gateway host-name
     If this option is set to a host name, NAME uses rsh (1) to run the telnet (1) program on the given host to communicate with the Internet Chess Server instead of opening a direct TCP connection. (You can substitute a different remote shell program for rsh using the REMOTESHELL option described below.)

     This option is useful if your machine is unable to connect directly to the ICS but is able to rsh to a gateway host that can connect to the ICS. As an example, suppose the gateway host is called gate.ralph.com, and you set options as follows:

              LCNAME -ics -gateway gate.ralph.com -icshost chess.lm.com

     Or in your .Xdefaults file:

              NAME*gateway: gate.ralph.com
              NAME*internetChessServerHost: chess.lm.com

     Then when you run NAME in ICS mode, it will connect to the ICS by using rsh to run the command

              telnet chess.lm.com 5000

     on host gate.ralph.com.

-telnet or -useTelnet
     If this option is set to true, NAME runs the telnet (1) program to communicate with the Internet Chess Server. If the option is false (the default), NAME opens a TCP socket to communicate with the ICS.

     One case where this option is useful is if your machine cannot connect directly to the ICS, but can telnet to a gateway host that can connect to the ICS. It is more general than the gateway option, because you may be able to telnet to a host that you cannot rsh to, but it's not as convenient to use. As an example, suppose the gateway host is called gate.ralph.com, and you set command-line options as follows:

              LCNAME -ics -telnet -icshost gate.ralph.com -icsport 23

     Or in your .Xdefaults file:

              NAME*useTelnet: true
              NAME*internetChessServerHost: gate.ralph.com
              NAME*internetChessServerPort: 23

     Then when you run NAME in ICS mode, you will be prompted to log in to the gateway host. Then telnet to ICS (using a command like

              telnet chess.lm.com 5000

     See Limitations.

     The recipe above works because the option -icsport 23 causes NAME to connect to the gateway host's standard incoming telnet service (port 23) instead of trying to connect to a chess server running on the gateway host (port 5000).

-telnetProgram prog-name
     This option gives the name of the telnet program to be used with the gateway and USETELNET options.  The default is telnet. The telnet program is invoked with the value of INTERNETCHESSSERVERHOST as its first argument and the value of INTERNETCHESSSERVERPORT as its second argument.

     One case where this option is useful is if your machine cannot make a direct TCP connection to the ICS but can telnet there through a proxy server. As an example, suppose that your proxy telnet program is called ptelnet. You should then set commandline options as follows:

              LCNAME -ics -telnet -telnetProgram ptelnet

     Or in your .Xdefaults file:

              NAME*useTelnet: true
              NAME*telnetProgram: ptelnet

     Then when you run NAME in ICS mode, it will issue the command

              ptelnet chess.lm.com 5000

     to connect to the ICS.

-internetChessServerCommPort or -icscomm dev-name
     If this option is set, NAME communicates with the ICS through the given character I/O device instead of opening a TCP connection. Use this option if your system does not have any kind of Internet connection itself (not even a SLIP or PPP connection), but you do have dialup access (or a hardwired terminal line) to an Internet service provider from which you can telnet to the ICS.

     The support for this option in NAME is minimal. You need to set all communication parameters and tty modes before you enter NAME.

     Use a script something like this:

              stty raw -echo 9600 > /dev/tty00
              NAME -ics -icscomm /dev/tty00

     Here replace /dev/tty00 with the name of the device that your modem is connected to. You might have to add several more options to these stty commands. See the man pages for stty (1) and tty (4) if you run into problems. Also, on many systems stty works on its standard input instead of standard output, so you have to use < instead of >.

     If you are using linux, try starting with the script below. Change it as necessary for your installation.

              ####################################################
              #!/bin/sh -f
              # configure modem and fire up NAME

              # configure modem
              (
              stty 2400 ; stty raw ; stty hupcl ; stty -clocal
              stty ignbrk ; stty ignpar ; stty ixon ; stty ixoff
              stty -iexten ; stty -echo
              ) < /dev/modem
              NAME -ics -icscomm /dev/modem
              ####################################################

     After you start NAME in this way, type whatever commands are necessary to dial out to your Internet provider and log in. Then telnet to ICS, using a command like

              telnet chess.lm.com 5000

     See Limitations.

Load and Save options
=====================

-lgf or -loadGameFile file
-lgi or -loadGameIndex index
     If the LOADGAMEFILE option is set, NAME loads the specified game file at startup. The file name - specifies the standard input. If the LOADGAMEINDEX option is set to N, the Nth game found in the file is loaded; otherwise the first game is loaded.

-td or -timeDelay seconds
     Time delay between moves during LOAD GAME. Fractional seconds are allowed; try -td 0.4. A time delay value of -1 tells NAME not to step through game files automatically. Default: 1 second.

-sgf or -saveGameFile file
     If this option is set, NAME appends a record of every game played to the specified file. The file name - specifies the standard output.

-autosave or -autoSaveGames
     If this option is true, at the end of every game NAME prompts you for a file name and appends a record of the game to the file you specify. Ignored if SAVEGAMEFILE is set.

-lpf or -loadPositionFile file
-lpi or -loadPositionIndex index
     If the LOADPOSITIONFILE option is set, NAME loads the specified position file at startup. The file name - specifies the standard input. If the LOADPOSITIONINDEX option is set to N, the Nth position found in the file is loaded; otherwise the first position is loaded.

-spf or -savePositionFile file
     If this option is set, NAME appends the final position reached in every game played to the specified file. The file name - specifies the standard output.

-oldsave or -oldSaveStyle
     If this option is false (the default), NAME saves games in PGN (portable game notation) and positions in FEN (Forsythe-Edwards notation).  If the option is true, a save style that is compatible with older versions of NAME is used instead.

Look and Feel
=============

-display
-geometry
-iconic
     These are just the standard Xt options accepted by NAME.

-bell or -ringBellAfterMoves
     If this option is true, NAME alerts you by ringing the terminal bell after each of your opponent's moves (or after every move if you are observing a game on the Internet Chess Server). The bell is not rung after moves you make or moves read from a saved game file. Default: false.

     If you turn on this option when using NAME with the Internet Chess Server, you will probably want to give the

              set bell 0

     command to the ICS, since otherwise the ICS will ring the bell itself after every move (not just yours). (The .icsrc file is a good place for this, see ICS options)

-queen or -alwaysPromoteToQueen
     If this option is false (the default), NAME brings up a dialog box whenever you move a pawn to the last rank, asking what piece you want to promote it to. If the option is true, your pawns are always promoted to queens. (Your opponent can still underpromote, however.)

-size or -boardSize (Large | Medium | Small)
     Determines how large the board will be and what built-in piece bitmaps will be used. On a large board (the default), pieces are 80x80 pixels, on a medium board 64x64 pixels, and on a small board 40x40 pixels.

-coords or -showCoords
     If this option is true, NAME displays algebraic coordinates along the board's left and bottom edges. The default is false. The COORDFONT option specifies what font to use.

-flip or -flipView
     If you are playing a game on the ICS, the board is always oriented at the start of the game so that your pawns move from the bottom of the window towards the top. Otherwise, the starting is determined by the flipView option; if it is false (the default), White's pawns move from bottom to top at the start of each game; if it is true, Black's pawns move from bottom to top.

-title or -titleInWindow
     If this option is true, NAME displays player names (for ICS games) and game file names (for LOAD GAME) inside its main window. If the option is false (the default), this information is displayed only in the window banner. You probably won't want to set this option unless the information is not showing up in the banner, as happens with a few X window managers.

-mono or -monoMode
     Determines whether NAME displays its pieces and squares with two colors (true) or four (false). You shouldn't have to specify MONOMODE; NAME will determine if it is necessary.

-borderXoffset
-borderYoffset
     These options are part of a kludge that helps position the Comment and Edit Comment windows in the same place on the screen when they are closed and reopened. They should be set equal to the width and height of the borders that your X window manager adds to windows when it displays them. The defaults are correct for tvtwm (1).

-clockFont
     The font used for the clocks. If the option value is a pattern that does not specify the font size, NAME tries to choose an appropriate font for the board size being used. Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.

-coordFont
     The font used for rank and file coordinate labels if SHOWCOORDS is true. If the option value is a pattern that does not specify the font size, NAME tries to choose an appropriate font for the board size being used. Default: -*-helvetica-bold-r-normal--*-*-*-*-*-*-*-*.

-font
     The font used for popup dialogs, menus, comments, etc.  Default: -*-helvetica-medium-r-normal--14-*-*-*-*-*-*-*.

-bm or -bitmapDirectory
     By default, NAME uses a set of compiled-in bitmaps for its pieces. If the BITMAPDIRECTORY option is set at runtime, piece bitmaps are taken from files in the specified directory instead. The first character of a bitmap name gives the piece it represents (p, n, b, r, q, or k); the next characters give the size in pixels (80, 64, or 40), and the following character indicates whether the piece is solid or outline (s or o). Bitmap file names have the extension .bm. The outline bitmaps are used only in monochrome mode.

     Two sets of bitmaps are distributed with NAME. Those in the directory bitmaps are normally compiled in as the default. Those in the bitmaps.xchess directory can be selected at runtime with the BITMAPDIRECTORY option. If you want to compile in the latter set as the default, rename the bitmaps directory to bitmaps.fselch and the bitmaps.xchess directory to bitmaps; then recompile NAME.

-whitePieceColor

-blackPieceColor

-lightSquareColor

-darkSquareColor
     Color specifications, suitable for XParseColor (3X11). Defaults:

              -whitePieceColor    #FFFFCC
              -blackPieceColor    #202020
              -lightSquareColor   #C8C365
              -darkSquareColor    #77A26D

     These colors look good on a DEC workstation. If you need different colors, try using the xcolors application. Source for xcolors can be found in the X11 contrib directory.

     On a grayscale monitor you might prefer

              -whitePieceColor    gray100
              -blackPieceColor    gray0
              -lightSquareColor   gray80
              -darkSquareColor    gray60

Miscellaneous
=============

-ncp or -noChessProgram
     If this option is true, NAME acts as a passive chessboard; it does not start a chess program at all. Turning on this option also turns off clockMode. Default: false.

-debug or -debugMode
     Turns on debugging printout.

-rsh or -remoteShell shell-name
     Name of the command used to run programs remotely. The default is rsh or remsh, determined when NAME is configured and compiled.

-ruser or -remoteUser user-name
     User name on the remote system when running programs with the REMOTESHELL. The default is your local user name.

Menus, Buttons and Keys
***********************

All NAME commands are available on menus. The most frequently used commands also have shortcut keys or on-screen buttons.

Accessing external games and positions
======================================

Reset
     Resets NAME and GNU Chess to the beginning of a new chess game. The r key is a keyboard equivalent. In Internet Chess Server mode, clears the current state of NAME, then resynchronizes with ICS by sending a refresh command. If you want to stop playing, observing, or examining a game on ICS, use an appropriate command from the Action menu, not RESET. See Action Menu.

Load Game
     Plays a game from a record file. A popup dialog prompts you for the file name. If the file contains more than one game, and you want to load the Nth one, type the number N after the file name, separated by a space. The g key is a keyboard equivalent.

     The game file parser will accept PGN (portable game notation), or in fact almost any file that contains moves in algebraic notation. If the file includes a PGN position (FEN tag), or an NAME position diagram bracketed by [-- and --] before the first move, the game starts from that position. Text enclosed in parentheses, square brackets, or curly braces is assumed to be commentary and is displayed in a pop-up window. Any other text in the file is ignored. PGN variations (enclosed in parentheses) are treated as comments; NAME is not able to walk variation trees.

Load Next Game
     Loads the next game from the last game record file you loaded. The shifted N key is a keyboard equivalent.

Load Previous Game
     Loads the previous game from the last game record file you loaded.  The shifted P key is a keyboard equivalent.

Reload Same Game
     Reloads the last game you loaded.

Load Position
     Sets up a position from a position file.  A popup dialog prompts you for the file name. If the file contains more than one saved position, and you want to load the Nth one, type the number N after the file name, separated by a space. Position files must be in FEN (Forsythe-Edwards notation), or in the format that the Save Position command writes when oldSaveStyle is turned on.

Save Game
     Appends a record of the current game to a file. A popup dialog prompts you for the file name. If the game did not begin with the standard starting position, the game file includes the starting position used. Games are saved in the PGN (portable game notation) format, unless the oldSaveStyle option is true, in which case they are saved in an older format that is specific to NAME. Both formats are human-readable, and both can be read back by the LOAD GAME command.

Save Position
     Appends a diagram of the current position to a file. A popup dialog prompts you for the file name. Positions are saved in FEN (Forsythe-Edwards notation) format unless the OLDSAVESTYLE option is true, in which case they are saved in an older, human-readable format that is specific to NAME. Both formats can be read back by the LOAD POSITION command.

Mail Move

Reload CMail Message
     See the manual page for cmail(6).

Exit
     Exits from NAME. The q key is a keyboard equivalent.

Selecting NAME's mode
=====================

Pause
     Pauses updates to the board, and if you are playing against GNU Chess, also pauses your clock. To continue, select Pause again, and the display will automatically update to the latest posi- tion. The [P] button and keyboard p key are equivalents.

     If you select PAUSE when you are playing against GNU Chess and it is not your move, GNU Chess's clock will continue to run and it will eventually make a move, at which point both clocks will stop. Since board updates are paused, however, you will not see the move until you exit from Pause mode (or select FORWARD). This behavior is meant to simulate adjournment with a sealed move.

     If you select Pause while you are in examine mode on ICS, you can step backward and forward in the current history of the examined game without affecting the other observers and examiners. Select Pause again to reconnect yourself to the current state of the game on ICS.

     If you select Pause while you are loading a game, the game stops loading. You can load more moves manually by selecting FORWARD, or resume automatic loading by selecting PAUSE again.

Edit Comment
     Adds or modifies a comment on the current position. Comments are saved by SAVE GAME and are displayed by LOAD GAME, FORWARD, and BACKWARD.

Machine White
     Forces GNU Chess to play White. GNU Chess mode only.

Machine Black
     Forces GNU Chess to play Black. GNU Chess mode only.

Two Machines
     Plays a game between two computer programs. GNU Chess mode only.

ICS Client
     ICS mode only. Takes NAME out of the Edit Game or Edit Position state.

     While you are examining a game on the ICS, you can issue the ICS position-editing commands with the mouse. (Do this with ICS CLIENT selected on the Mode menu, not EDIT POSITION; the latter edits only your local copy of the position.)

     To drop a new piece on a square, press mouse button 2 or 3 over the square. This brings up a menu of white pieces (button 2) or black pieces (button 3). Additional menu choices let you empty the square or clear the board. You cannot set the side to play or drag pieces to arbitrary squares while examining on ICS, however; the ICS permits only legal moves in this mode.

Edit Game
     Allows you to make moves for both Black and White, and to change moves after backing up with the BACKWARD command. The clocks do not run.

     In GNU Chess mode, GNU chess continues to check moves for legality but does not participate in the game. You can bring GNU Chess back into the game by selecting MACHINE WHITE, MACHINE BLACK, or TWO MACHINES.

     In ICS mode, the moves are not sent to the ICS: EDIT GAME takes NAME out of ICS Client mode and lets you edit games locally. f you want to edit games on ICS in a way that other ICS users can see, use the ICS examine command or start an ICS match against yourself.

Edit Position
     Lets you set up an arbitrary board position. Use mouse button 1 to drag pieces to new squares, or to delete a piece by dragging it off the board or dragging an empty square on top of it. To drop a new piece on a square, press mouse button 2 or 3 over the square. This brings up a menu of white pieces (button 2) or black pieces (button 3). Additional menu choices let you empty the square or clear the board. You can set the side to play next by clicking on the White or Black indicator at the top of the screen. Selecting EDIT POSITION causes NAME to discard all remembered moves in the current game.

     In ICS mode, changes made to the position by EDIT POSITION are not sent to the ICS: EDIT POSITION takes NAME out of ICS CLIENT mode and lets you edit positions locally. If you want to edit positions on ICS in a way that other ICS users can see, use the ICS EXAMINE command, or start an ICS match against yourself. (See also the ICS Client topic above.)

Talking to GNU chess or ICS opponents
=====================================

Accept
     Accepts a pending match offer. If there is more than one offer pending, you will have to type in a more specific command instead of using this menu choice. (ICS mode only)

Decline
     Declines a pending offer (match, draw, adjourn, etc.). If there is more than one offer pending, you will have to type in a more specific command instead of using this menu choice. (ICS mode only)

Call Flag
     Calls your opponent's flag, claiming a win on time, or claiming a draw if you are both out of time. You can also call your opponent's flag by clicking on his clock or by pressing the keyboard t key.

Draw
     Offers a draw to your opponent, accepts a pending draw offer from your opponent, or claims a draw by repetition or the 50-move rule, as appropriate. The d key is a keyboard equivalent. (Not available in GNU Chess mode.)

Adjourn
     Asks your opponent to agree to adjourning the current game, or agrees to a pending adjournment offer from your opponent. (ICS mode only)

Abort
     Asks your opponent to agree to aborting the current game, or agrees to a pending abort offer from your opponent. An aborted game ends immediately without affecting either player's rating.

Resign
     Resigns the game to your opponent. The shifted R key is a keyboard equivalent.

Stop Observing
     Ends your participation in observing a game, by issuing the ICS observe command with no arguments. (ICS mode only)

Stop Examining
     Ends your participation in examining a game, by issuing the ICS unexamine command. (ICS mode only)

Controlling the game
====================

Backward
     Steps backward through a series of remembered moves. The [<] button and the "b" key are equivalents.

     In most modes, BACKWARD only lets you look back at old positions; it does not retract moves. This is the case if you are playing against GNU Chess, playing or observing a game on the ICS, or loading a game. If you select BACKWARD in any of these situations, you will not be allowed to make a different move. Use RETRACT MOVE or EDIT GAME if you want to change past moves.

     If you are examining a game on ICS, the behavior of BACKWARD depends on whether NAME is in Pause mode. If Pause mode is off, BACKWARD issues the ICS backward command, which backs up everyone's view of the game and allows you to make a different move. If Pause mode is on, BACKWARD only backs up your local view.

Forward
     Steps forward through a series of remembered moves (undoing the effect of BACKWARD) or forward through a game file. The [>] button and the f key are equivalents.

     If you are examining a game on ICS, the behavior of Forward depends on whether NAME is in Pause mode. If Pause mode is off, FORWARD issues the ICS forward command, which moves everyone's view of the game forward along the current line. If Pause mode is on, FORWARD only moves your local view forward, and it will not go past the position that the game was in when you paused.

Back to Start
     Jumps backward to the first remembered position in the game. The [<<] button and the shifted B key are equivalents.

     In most modes, Back to Start only lets you look back at old positions; it does not retract moves. This is the case if you are playing against GNU chess, playing or observing a game on the ICS, or loading a game. If you select BACK TO START in any of these situations, you will not be allowed to make different moves. Use RETRACT MOVE or EDIT GAME if you want to change past moves; or use Reset to start a new game.

     If you are examining a game on ICS, the behavior of BACK TO
     START depends on whether NAME is in Pause mode. If Pause mode is off, BACK TO START issues the ICS backward 999999 command, which backs up everyone's view of the game to the start and allows you to make different moves. If Pause mode is on, BACK TO START only backs up your local view.

Forward to End
     Jumps forward to the last remembered position in the game. The [>>] button and the shifted F key are equivalents.

     If you are examining a game on ICS, the behavior of FORWARD TO
     END depends on whether NAME is in Pause mode. If Pause mode is off, FORWARD TO END issues the ICS forward 999999 command, which moves everyone's view of the game forward to the end of the current line. If Pause mode is on, FORWARD TO END only moves your local view forward, and it will not go past the position that the game was in when you paused.

Revert
     If you are examining a game on ICS and Pause mode is off, issues the ICS command revert.

Truncate Game
     Discards all remembered moves of the game beyond the current position. Puts NAME into EDIT GAME mode if it was not there already.

Move Now
     Forces GNU Chess to move immediately. (GNU Chess mode only)

Retract Move
     Retracts your last move. In GNU Chess mode, you can do this only after GNU Chess has replied to your move; if GNU Chess is still thinking, use MOVE NOW first. In ICS mode, RETRACT MOVE issues the command takeback 1 or takeback 2 depending on whether it is your opponent's move or yours.

User Preferences
================

Always Queen
     Toggles the ALWAYSPROMOTETOQUEEN option. See User interface options.

Auto Flag
     Toggles the AUTOCALLFLAG option: NAME will automatically claim a win for you, if your opponents flag falls on ICS. See ICS options.

Auto Observe
     Toggles the AUTOOBSERVE option. See ICS options.

Auto Save
     Toggles the AUTOSAVEGAMES option. Disabled if the SAVEGAMEFILE option is set, as in that case all games are saved to the specified file.

Bell
     Toggles the RINGBELLAFTERMOVES option. See User interface options.

Flip View
     Inverts your view of the chess board for the duration of the current game. Starting a new game returns the board to normal.

     If you are playing a game on the ICS, the board is always oriented at the start of the game so that your pawns move from the bottom of the window towards the top. Otherwise, the starting orientation is determined by the FLIPVIEW command line option; if it is false (the default), White's pawns move from bottom to top at the start of each game; if it is true, Black's pawns move from bottom to top. See User interface options.

Old Save Style
     Toggles the OLDSAVESTYLE option. See I/O options.

Quiet Play
     Toggles the QUIETPLAY option. See ICS options.

Show Coords
     Toggles the SHOWCOORDS option. See User interface options.

Show Thinking
     Toggles the SHOWTHINKING option. See GNU Chess options.

Getting help from GNU Chess
===========================

Hint
     Displays a move hint from GNU Chess. GNU Chess mode only.

Book
     Displays a list of possible moves from GNU Chess's opening book. The first column gives moves, the second column gives one possible response for each move, and the third column shows the number of lines in the book that include the move from the first column. If you select this option and nothing happens, GNU Chess is out of its book.  GNU Chess mode only.

About Game
     Displays information about the current game, in the form of PGN (portable game notation) tags.

About NAME
     Shows the current NAME version number.

Other shortcut keys
===================

Iconize
     Pressing the i or c key iconizes NAME. The graphical icon displays a white knight if it is white's move, or a black knight, if it is Black's move. If your X window manager displays only text icons, not graphical ones, check its documentation; there is probably a way to enable graphical icons. If you are running the Motif window manager mwm (1), add these lines to your .Xdefaults file and restart mwm:

          Mwm*iconDecoration: activelabel label image
          Mwm*NAME*iconImageBackground: White
          Mwm*NAME*iconImageForeground: Black

     The first line above enables graphical icons in mwm; you don't need it if you already have them. The next two lines force the white knights to come out white and the black kinghts black. Unfortunately these resources can't be set from inside NAME; you have to set them in your .Xdefaults file.

You can add or remove shortcut keys using the X resources form.translations. Here is an example of what would go in your .Xdefaults file:

     NAME*form.translations: Shift<Key>?: AboutGameProc() \n\
         <Key>y: AcceptProc()                               \n\
         <Key>n: DeclineProc()                              \n\
         <Key>i: NothingProc()

Binding a key to NOTHINGPROC makes it do nothing, thus removing it as a shortcut key. The NAME keys that can be bound to keys are:

ABORTPROC, ABOUTGAMEPROC, ABOUTPROC, ACCEPTPROC, ADJOURNPROC, ALWAYSQUEENPROC, AUTOFLAGPROC, AUTOBSPROC, AUTOSAVEPROC, BACKWARDPROC, BELLPROC, BOOKPROC, CALLFLAGPROC, DECLINEPROC, DRAWPROC, EDITGAMEPROC, EDITPOSITIONPROC, FLIPVIEWPROC, FORWARDPROC, HINTPROC, ICSCLIENTPROC, LOADGAMEPROC, LOADNEXTGAMEPROC, LOADPOSITIONPROC, LOADPREVGAMEPROC, MACHINEBLACKPROC, MACHINEWHITEPROC, MAILMOVEPROC, MOVENOWPROC, OLDSAVESTYLEPROC, PAUSEPROC, QUIETPLAYPROC, QUITPROC, RELOADGAMEPROC, RESETPROC, RESIGNPROC, RETRACTMOVEPROC, REVERTPROC, SAVEGAMEPROC, SAVEPOSITIONPROC, SHOWCOORDSPROC, SHOWTHINKINGPROC, STOPEXAMININGPROC, STOPOBSERVINGPROC, TOENDPROC, TOSTARTPROC, TRUNCATEGAMEPROC, and TWOMACHINESPROC.

Using NAME as an ICS client
***************************

What is this ICS thing, you probably ask? ICS (Internet chess server, also known as ICC, Internet chess club, which is the commercial version) is an internet service very similar to irc: People use a client program like NAME to connect to a server program on a remote host, the so-called server. There they meet to play chess, watch other people's games or just chat: In fact, the atmoshpere is full of virtual shouts, much like a usual chess club.

ICS is getting more and more important for chess players: Currently (March 1995) there are some thousand registered users on the different ICS hosts and it is not unusual to meet 200-300 of them on ICC in the evening hours. The number is increasing rapidly.

Usually you are using telnet (1) to connect to the chess server. (NAME does this for you.) For a detailed description of options that control the connection, see ICS options.

When using NAME as an ICS client, the program seems to be split into two parts: The first one is the chessboard, as usual. Additionally you are using the terminal window as a possibility to type in commands and read information not available on the chessboard.

The first time you are using the terminal is to enter you're login name and password, if you are a registered player. (You don't need to do this manually, the -ICSLOGIN option may do this for you. see ICS options) If not, just enter any unique name like guest173 and hit return.

You may use the terminal window to enter commands. Useful ICS commands include

help <topic>
     to get help on the given <topic>. (To get a list of possible topics type help without topic.) Obviously this is a very important command for new users. :-) It is recommended netiquette to use it before asking other people.

     For example help register tells you how to become a registered ICS player.

who <flags>
     to see a list of people displayed who are are logged on. Administrators (people you should ask first, if you have something to ask) are marked with the character *, an asterisk. The <flags> allow you to display only selected players: For example, who of shows a list of players which are interested in playing, but do not have an opponent.

games
     to see what games are being played

match <player> [<mins>] [<inc>]
     to challenge another player to a game. Both opponents get <mins> minutes for the game, <inc> seconds will be added after each move. If another player challenges you, the server asks, if you want to accept the challenge: Use the accept or decline commands to answer.

accept
decline
     to accept or decline another players offer; this is both used to start a game (if the player challenges you) or to terminate the game, for example, if your opponent offers you a draw, to adjourn or abort the game. See Action Menu.

     If you have more than one pending offer (for example, if more than one player is challenging you, or if your opponent offers both a draw and to adjourn the game), you have to supply additional information, either by typing something like accept <player>, accept draw or using a command like

draw
adjourn
abort
     offers your opponent to terminate a game by mutual agreement. (Adjourned games may be continued later.) The server asks your opponent, so he can either decline your offer or accept it by typing the same command or accept. (Your opponent won't be asked, of course, if he lacks material to win, for example.)

finger <player>
     to get informations about the given <player>. (Default: yourself.)

vars
     to get a list of personal settings

set <var> <value>
     to modify these settings

observe <player>
     to observe an ongoing game of the given <player>.

examine
oldmoves
     to review a recently completed game

Whenever you ask to observe an ongoing game, review a completed game, or resume an adjourned game, NAME retrieves and parses the list of past moves from the ICS, so you can review them with the FORWARD and BACKWARD commands or save them with SAVE GAME. Some special NAME features are activated when you are in examine mode on ICS.

Using NAME for electronic correspondence chess.
***********************************************

The cmail program will help you play chess by email with opponents of your choice using NAME as an interface.

CMail's author is

         Evan Welsh
         Edinburgh Parallel Computing Centre
         JCMB, Kings Buildings
         The University of Edinburgh
         Edinburgh EH9 3JZ
         Scotland

         Internet: welsh@epcc.ed.ac.uk

You will usually run cmail without giving any options.

Invoking CMail.
===============

-h
     Displays cmail usage information.

-c
     Shows the conditions of the GNU General Public License. See Copying.

-w
     Shows the warranty notice of the GNU General Public License. See Copying.

-v
-xv
     Provides or inhibits verbose output from cmail and NAME, useful for debugging. The -XV form also inhibits the cmail introduction message.

-mail
-xmail
     Invokes or inhibits the sending of a mail message containing the move.

-xboard
-xxboard
     Invokes or inhibits the running of NAME on the game file.

-reuse

-xreuse
     Invokes or inhibits the reuse of an existing NAME to display the current game.

-remail
     Resends the last mail message for that game. This inhibits running NAME.

-game <name>
     The name of the game to be processed.

-wgames <number>
-bgames <number>
-games <number>
     Number of games to start as White, as Black or in total. Default is 1 as white and none as black. If only one colour is specified then none of the other colour is assumed. If no colour is specified then equal numbers of White and Black games are started, with the extra game being as White if an odd number of total games is specified.

-me <short name>
-opp <short name>
     A one-word alias for yourself or your opponent.

-wname <full name>
-bname <full name>
-name <full name>
-oppname <full name>
     The full name of White, Black, yourself or your opponent.

-wna <net address>
-bna <net address>
-na <net address>
-oppna <net address>
     The email address of White, Black, yourself or your opponent.

-dir <directory>
     The directory in which cmail keeps its files. This defaults to the environment variable $CMAIL_DIR or failing that, $CHESSDIR, $HOME/CHESS or ~/CHESS. It will be created if it does not exist.

-arcdir <directory>
     The directory in which cmail archives completed games. Defaults to the environment variable $CMAIL_ARCDIR or, in its absence, the same directory as cmail keeps its working files (above).

-mailprog <mail program>
     The program used by cmail to send email messages. This defaults to the environment variable $CMAIL_MAILPROG or failing that /usr/ucb/Mail, /usr/ucb/mail or Mail. You will need to set this variable if none of the above paths fit your system.

-gamesFile <file>
     A file containing a list of games with email addresses. This defaults to the environment variable $CMAIL_GAMES or failing that .cmailgames.

-aliasesFile <file>
     A file containing one or more aliases for a set of email addresses. This defaults to the environment variable $CMAIL_ALIASES or failing that .cmailaliases.

-logFile <file>
     A file in which to dump verbose debugging messages that are invoked with the -V option.

-event <event>
     The PGN Event tag (default Email correspondence game).

-site <site>
     The PGN Site tag (default NET).

-round <round>
     The PGN Round tag (default -, not applicable).

-mode <mode>
     The PGN Mode tag (default EM, Electronic Mail).

OTHER OPTIONS
     Any unrecognised flags will be passed to NAME. Those most relevant for use with Icmail\fP are -TIMEDELAY, -NOCHESSPROGRAM, -SEARCHTIME, -SEARCHDEPTH, -SAVEGAMEFILE, -AUTOSAVE, -SAVEPOSITIONFILE and -BOARDSIZE. See Invocation.

Starting a CMail game.
======================

Type cmail from a shell to start a game as white. After an opening message, you will be prompted for a game name, which is optional -- if you simply press return, the game name will take the form you-VS-opponent. You will next be prompted for the short name of your opponent. If you haven't played this person before, you will also be prompted for his/her email address. cmail will then invoke NAME in the background. Make your first move and select MAILMOVE from the FILE MENU. See File Menu. If all is well, cmail will mail a copy of the move to your opponent. If you select EXIT without having selected MAIL MOVE then no move will be made.

Answering a move.
=================

When you receive a message from an opponent containing a move in one of your games, simply pipe the message through cmail. In some mailers this is as simple as typing | cmail when viewing the message, while in others you may have to save the message to a file and do cmail < file at the command line. In either case cmail will display the game using NAME. If you didn't exit NAME when you made your first move then cmail will do its best to use the existing NAME instead of starting a new one. As before, simply make a move and select MAIL MOVE from the FILE MENU. See File Menu. cmail will try to use the NAME that was most recently used to display the current game. This means that many games can be in progress simultaneously, each with its own active NAME.

If you want to look at the history or explore a variation, go ahead, but you must return to the current position before NAME will allow you to mail a move. If you edit the game's history you must select RELOAD SAME GAME from the FILE MENU to get back to the original position, then make the move you want and select MAIL MOVE. As before, if you decide you aren't ready to make a move just yet you can either select EXIT without sending a move or just leave NAME running until you are ready.

Because NAME can now detect checkmate and stalemate, cmail now handles game termination sensibly. As well as resignation, the ACTION MENU now allows draws to be offered and accepted for cmail games.

For multi-game messages, only unfinished and just-finished games will be included in email messages. When all the games are finished, they are archived in the user's archive directory, and similarly in the opponent's when he or she pipes the final message through cmail. The archive file name includes the date the game was started.

It's possible to have a cmail message carry more than one game. This feature was implemented to handle IECG (International Email Chess Group) matches, where a match consists of 1 game as white and 1 as black, with moves transmitted simultaneously. In case there are more general uses, cmail itself places no limit on the number of black/white games contained in a message; however, NAME does.

Known CMail problems.
=====================

It's possible that a strange conjunction of conditions may occasionally mean that cmail has trouble reactivating an existing NAME. If this should happen, simply trying it again should work. If not, remove the file that stores the NAME's PID (game.pid) or use the -XREUSE option to force cmail to start a new NAME.

Versions of cmail after 2.16 no longer understand the old file format that NAME used to use and so cannot be used to correspond with anyone using an older version.

Versions of cmail older than 2.11 do not handle multi-game messages, so multi-game correspondence is not possible with opponents using an older version.

Environment variables
*********************

Game and position files are found in a directory named by the CHESSDIR environment variable. If this variable is not set, the current working directory is used. If CHESSDIR is set, NAME actually changes its working directory to $CHESSDIR, so GNU Chess listing files will also be stored there as well.

Known limitations
*****************

There is no way for two people running copies of NAME to play each other without going through the Internet Chess Server.

The game parser recognizes only algebraic notation.

The internal move legality tester does not look at the game history, so in some cases it misses illegal castling or en passant captures. However, if you attempt such a move when using GNU Chess (or the ICS), it will reject the move, and NAME will undo it and let you try another. Also FEN positions saved by NAME do not include correct information about whether castling or en passant are legal.

In ICS mode NAME cannot handle observing (and/or playing) more than one game at a time. It may get confused if you try to do this, thought it tries to recover gracefully. Select RESET from the FILE MENU, if you have problems. See File Menu.

Your password may get echoed when you log on to the ICS.

If you are connecting to the ICS by running telnet on an Internet provider or firewall host, you may find that each line you type is echoed back an extra time after you hit Return. If your Internet provider is a Unix system, you can probably turn its echo off by typing

         stty -echo

after you log in, and/or by typing ^E-Return (control-E followed by the Return key) to the telnet program after you have logged into ICS. It is a good idea to do this if you can, because the extra echo can occasionally confuse NAME's parsing routines.

The .icsrc file does not work properly when you connect to ICS through a Unix gateway host with USETELNET mode. The Unix login process apparently discards type-ahead. See ICS options.

Some NAME functions may not work with versions of GNU Chess earlier than 4.0, patchlevel 73.

Reporting Bugs
**************

Report bugs in NAME or GNU Chess to

         bug-gnu-chess@prep.ai.mit.edu

Please use the script program to start a typescript, run NAME with the -debug option, and include the typescript output in your message. Also tell us what kind of machine and what operating system version you are using.  The command

         uname -a

will often tell you this.

If you improve NAME, please send a message about your changes to bug-gnu-chess, and we will get in touch with you about merging them in to the main line of development.

Send CMail bug reports/suggestions to

         welsh@epcc.ed.ac.uk

What you should keep in mind
****************************

NAME depends on the Xt Intrinsics and Athena Widget Set of X11R4 or later. In particular, X11R3 just won't do.

NAME works best with version 4.0 of GNU Chess. Older versions may also work, but they are unsupported. The GNU Chess project requests that you get a current copy of GNU Chess rather than using older, bug-ridden versions. GNU Chess must be compiled with the -DXBOARD flag for use with NAME.  Use the

         make gnuchessx

target in GNU Chess 4.0 to do this.

The Free Software Foundation would prefer to be able to distribute an X chessboard program covered only by the GNU General Public License and unencumbered by any other copyright.  If you can help with this, please contact the FSF.

Authors and Contributors to NAME
********************************

Tim Mann (mann@pa.dec.com)
     has been responsible for XBoard versions 1.3 throught 3.2 and for WinBoard.

Chris Sears and Dan Sears
     wrote the original XBoard; they were responsible for versions 1.0 through 1.2.

Elmar Bartel (bartel@informatik.tu-muenchen.de)
     Elmar Bartel contributed the new piece bitmaps for version 3.2.

Evan Welsh (welsh@epcc.ed.ac.uk)
     wrote CMail.

Patrick Surry
     helped with design, testing and documening CMail.

John Chanak
     contributed the iniitial implementation of ICS mode.

Wayne Christopher
     created XChess; the color scheme and the old 80x80 piece bitmaps were taken from it.