10. CMail
The `cmail' program can help you play chess by email with opponents of
your choice using XBoard as an interface.
You will usually run `cmail' without giving any options.
10.1 CMail options
- -h
- Displays `cmail' usage information.
- -c
- Shows the conditions of the GNU General Public License.
See section GNU GENERAL PUBLIC LICENSE.
- -w
- Shows the warranty notice of the GNU General Public License.
See section GNU GENERAL PUBLIC LICENSE.
- -v
- -xv
- Provides or inhibits verbose output from `cmail' and XBoard,
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 XBoard on the game file.
- -reuse
- -xreuse
- Invokes or inhibits the reuse of an existing XBoard to display the
current game.
- -remail
- Resends the last mail message for that game. This inhibits running
XBoard.
- -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 color is specified then none of the
other color is assumed. If no color 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 option flags not listed above are passed through to XBoard.
Invoking XBoard through CMail changes the default values of two XBoard
options: The default value for `-noChessProgram' is changed to
true; that is, by default no chess engine is started. The default
value for `-timeDelay' is changed to 0; that is, by default
XBoard immediately goes to the end of the game as played so far,
rather than stepping through the moves one by one. You can still set
these options to whatever values you prefer by supplying them on
CMail's command line. See section 3. Options.
10.2 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 Enter, 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. See section 2.1 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.
10.3 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. See section 2.1 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
active XBoard.
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.
10.4 Multi-Game Messages
It is 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 one game as white and one 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.
10.5 Completing a Game
Because XBoard can detect checkmate and stalemate, `cmail'
handles game termination sensibly. As well as resignation, the
`Action' menu 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.
10.6 Known CMail Problems
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
version.
This document was generated
by Tim Mann on November, 28 2003
using texi2html