cmail - an email chess helper


SYNOPSIS

       cmail [options]


DESCRIPTION

       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.


OPTIONS

       You will usually run cmail  without  giving  any  options.
       See the next section for instructions.

       -h      Displays cmail usage information.

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

       -w      Shows the warranty notice of the GNU General  Pub­
               lic License.

       -[x]v   Provides or inhibits verbose output from cmail and
               xboard, useful for debugging. The  -xv  form  also
               inhibits the cmail introduction message.

       -[x]mail
               Invokes  or inhibits the sending of a mail message
               containing the move.

       -[x]xboard
               Invokes or inhibits the running of xboard  on  the
               game file.

       -[x]reuse
               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.

       -(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

               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  direc­
               tory 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 vari­
               able $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").

               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  xboard.  Those
       most relevant for use with cmail are:

       -timeDelay (or -td) delay
               This  sets  the  speed at which the moves are dis­
               played on start-up. It defaults to the environment
               variable  $CMAIL_TIME_DELAY  if  set, and 0 other­
               wise.

       -noChessProgram (True | False), or -[x]ncp
               If this option is False,  xboard  starts  a  chess
               program  which  can  be used with cmail to suggest
               moves.  Default: True.

       -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, xboard 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
               xboard prompts you for a filename  and  appends  a
               record of the game to the file you specify.

       -savePositionFile (or -spf) file
               If  this  option  is set, xboard 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

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


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

       or  she pipes the final message through cmail. The archive
       file name includes the date the game was started.


MULTI-GAME MESSAGES

       It's possible to have a cmail message carry more than  one
       game.  This feature was implemented to handle IECG (Inter­
       national Email Chess Group) matches, where  a  match  con­
       sists of 1 game as white and 1 as black, with moves trans­
       mitted 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.


TROUBLE SHOOTING

       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.


FILES

       ".cmailgames" contains a list  of  games  with  the  email
       addresses of the opponents.

       ".cmailaliases"  contains one or more aliases for a set of
       email addresses.


BUGS

       No known bugs.


BUG REPORTS

       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.


AUTHOR

       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.

       but  WITHOUT  ANY  WARRANTY; without even the implied war­
       ranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR  PUR­
       POSE.   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 Soft­
       ware Foundation, Inc., 59 Temple Place, Suite 330, Boston,
       MA 02111 USA.

       Author:   Evan Welsh <Evan.Welsh@msdw.com>


CONTRIBUTORS

       Patrick  Surry  helped with design, testing and documenta­
       tion.

       Tim Mann helped integrate cmail with xboard.


SEE ALSO

       Mail(1), perl(1), xboard(1)


Man(1) output converted with man2html