cmail - an email chess helper
The cmail program will help you play chess by email with opponents of
your choice using an X interface. To use it, you will need to be able to
run xboard with which cmail is distributed, available by
anonymous FTP from numerous sites around the world. It has been tested with
xboard 3.2; it may require modification for other versions.
You will usually run cmail without giving any options. See the next
section for instructions.
- Displays cmail usage information.
- Shows the conditions of the GNU General Public License.
- Shows the warranty notice of the GNU General Public License.
- Provides or inhibits verbose output from cmail and xboard,
useful for debugging. The
form also inhibits the cmail introduction message.
- Invokes or inhibits the sending of a mail message containing the move.
- Invokes or inhibits the running of xboard on the game file.
- Invokes or inhibits the reuse of an existing xboard to display the
- Resends the last mail message for that game. This inhibits running
- -game name
- The name of the game to be processed.
- -(w|b|)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|opp) short name
- A one-word alias for yourself or your opponent.
- -(w|b|my|opp)name full name
- The full name of White, Black, yourself or your opponent.
- -(w|b|my|opp)na 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
- -logFile file
- A file in which to dump verbose debugging messages that are invoked with
- -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).
Any unrecognised flags will be passed to xboard. Those most relevant
for use with cmail are:
- -timeDelay (or -td) delay
- This sets the speed at which the moves are displayed on start-up. It
defaults to the environment variable $CMAIL_TIME_DELAY if set, and 0
- -noChessProgram (True | False), or -[x]ncp
- If this option is False,
starts a chess program which can be used with cmail to suggest moves.
- -searchTime (or -st) 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.
- -searchDepth (or -sd) 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.
- -saveGameFile (or -sgf) file
- If this option is set,
appends a record of the game played to the specified file on exit.
- -autosave or -autoSaveGames
- If this option is True, at the end of every game
prompts you for a filename and appends a record of the game to the file you
- -savePositionFile (or -spf) file
- If this option is set,
appends the final position reached to the specified file on exit.
- -boardSize (or -size) (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.
STARTING A 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
xboard in the background. Make your first move and select Mail
Move from the 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
xboard. If you didn't exit xboard when you made your first move
then cmail will do its best to use the existing xboard instead
of starting a new one. As before, simply make a move and select Mail
Move from the File menu. cmail will try to use the
xboard that was most recently used to display the current game. This
means that many games can be in progress simultaneously, each with its own
If you want to look at the history or explore a variation, go ahead, but
you must return to the current position before xboard 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 xboard running until
you are ready.
COMPLETING A GAME
Because xboard 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
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, xboard does.
It's possible that a strange conjunction of conditions may occasionally
mean that cmail has trouble reactivating an existing xboard. If
this should happen, simply trying it again should work. If not, remove the
file that stores the xboard's PID (<game>.pid) or use the
-xreuse option to force cmail to start a new xboard.
Versions of cmail after 2.16 no longer understand the old file format
that xboard 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
I make no promises but if you send bug reports/suggestions to
Evan.Welsh@msdw.com I'll do my best to fix/implement them.
Copyright (C) 1993 Free Software Foundation, Inc.
cmail is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
cmail is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with cmail; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
Author: Evan Welsh <Evan.Welsh@msdw.com>
Patrick Surry helped with design, testing and documentation.
Tim Mann helped integrate cmail with xboard.
Mail(1), perl(1), xboard(1)