Go to the first, previous, next, last section, table of contents.

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.

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 Options.

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 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. See section 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.

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.

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.

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.