cmail.man

   1 .\"=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   2 .\"# File:        cmail.man
   3 .\"#
   4 .\"# Author:      Evan Welsh
   5 .\"#
   6 .\"# Email:       Evan.Welsh@msdw.com
   7 .\"#
   8 .\"# Modified:    $Date$
   9 .\"#              $Revision$
  10 .\"#
  11 .\"# Summary:     Man page for cmail
  12 .\"=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  13 .\"
  14 .TH CMAIL 6
  15 .PD
  16 .ad b
  17 .SH NAME
  18 cmail \- an email chess helper
  19 .SH SYNOPSIS
  20 \fBcmail\fR
  21 [\|\fBoptions\fR\|]
  22 .SH DESCRIPTION
  23 .PP
  24 The \fIcmail\fP program will help you play chess by email with opponents of
  25 your choice using an X interface.  To use it, you will need to be able to
  26 run \fIxboard\fP with which \fIcmail\fP is distributed, available by
  27 anonymous FTP from numerous sites around the world. It has been tested with
  28 \fIxboard 3.2\fP; it may require modification for other versions.
  29 .SH OPTIONS
  30 You will usually run cmail without giving any options.  See the next
  31 section for instructions.
  32 .TP 8
  33 .B \-h
  34 Displays \fIcmail\fP usage information.
  35 .TP 8
  36 .B \-c
  37 Shows the conditions of the GNU General Public License.
  38 .TP 8
  39 .B \-w
  40 Shows the warranty notice of the GNU General Public License.
  41 .TP 8
  42 .B \-[\|x\|]v
  43 Provides or inhibits verbose output from \fIcmail\fP and \fIxboard\fP,
  44 useful for debugging. The
  45 .B \-xv
  46 form also inhibits the cmail introduction message.
  47 .TP 8
  48 .B \-[\|x\|]mail
  49 Invokes or inhibits the sending of a mail message containing the move.
  50 .TP 8
  51 .B \-[\|x\|]xboard
  52 Invokes or inhibits the running of \fIxboard\fP on the game file.
  53 .TP 8
  54 .B \-[\|x\|]reuse
  55 Invokes or inhibits the reuse of an existing \fIxboard\fP to display the
  56 current game.
  57 .TP 8
  58 .B \-remail
  59 Resends the last mail message for that game. This inhibits running
  60 \fIxboard\fP.
  61 .TP 8
  62 .B \-game \fIname\fP
  63 The name of the game to be processed.
  64 .TP 8
  65 .B \-(w|b|)games \fInumber\fP
  66 Number of games to start as White, as Black or in total. Default is 1 as
  67 white and none as black. If only one colour is specified then none of the
  68 other colour is assumed. If no colour is specified then equal numbers of
  69 White and Black games are started, with the extra game being as White if an
  70 odd number of total games is specified.
  71 .TP 8
  72 .B \-(me|opp) \fIshort name\fP
  73 A one-word alias for yourself or your opponent.
  74 .TP 8
  75 .B \-(w|b|my|opp)name \fIfull name\fP
  76 The full name of White, Black, yourself or your opponent.
  77 .TP 8
  78 .B \-(w|b|my|opp)na \fInet address\fP
  79 The email address of White, Black, yourself or your opponent.
  80 .TP 8
  81 .B \-dir \fIdirectory\fP
  82 The directory in which \fIcmail\fP keeps its files. This defaults to the
  83 environment variable $CMAIL_DIR or failing that, $CHESSDIR, $HOME/Chess or
  84 ~/Chess. It will be created if it does not exist.
  85 .TP 8
  86 .B \-arcdir \fIdirectory\fP
  87 The directory in which \fIcmail\fP archives completed games. Defaults to
  88 the environment variable $CMAIL_ARCDIR or, in its absence, the same
  89 directory as cmail keeps its working files (above).
  90 .TP 8
  91 .B \-mailprog \fImail program\fP
  92 The program used by cmail to send email messages. This defaults to the
  93 environment variable $CMAIL_MAILPROG or failing that "/usr/ucb/Mail",
  94 "/usr/ucb/mail" or "Mail". You will need to set this variable if none of
  95 the above paths fit your system.
  96 .TP 8
  97 .B \-gamesFile \fIfile\fP
  98 A file containing a list of games with email addresses. This defaults to
  99 the environment variable $CMAIL_GAMES or failing that .cmailgames.
 100 .TP 8
 101 .B \-aliasesFile \fIfile\fP
 102 A file containing one or more aliases for a set of email addresses. This
 103 defaults to the environment variable $CMAIL_ALIASES or failing
 104 that .cmailaliases.
 105 .TP 8
 106 .B \-logFile \fIfile\fP
 107 A file in which to dump verbose debugging messages that are invoked with
 108 the
 109 .B \-v
 110 option.
 111 .TP 8
 112 .B \-event \fIevent\fP
 113 The PGN Event tag (default "Email correspondence game").
 114 .TP 8
 115 .B \-site \fIsite\fP
 116 The PGN Site tag (default "NET").
 117 .TP 8
 118 .B \-round \fIround\fP
 119 The PGN Round tag (default "-", not applicable).
 120 .TP 8
 121 .B \-mode \fImode\fP
 122 The PGN Mode tag (default "EM", Electronic Mail).
 123 .PP
 124 .SH OTHER OPTIONS
 125 Any unrecognised flags will be passed to \fIxboard\fP. Those most relevant
 126 for use with \fIcmail\fP are:
 127 .TP 8
 128 .B \-timeDelay (or -td) \fIdelay\fP
 129 This sets the speed at which the moves are displayed on start-up. It
 130 defaults to the environment variable $CMAIL_TIME_DELAY if set, and 0
 131 otherwise.
 132 .TP 8
 133 .B \-noChessProgram (True | False), or -[x]ncp
 134 If this option is False,
 135 .IR xboard
 136 starts a chess program which can be used with \fIcmail\fP to suggest moves.
 137 Default: True.
 138 .TP 8
 139 .B \-searchTime (or -st) minutes[:seconds]
 140 Tells GNU Chess to spend at most the given amount of time searching
 141 for each of its moves.  Without this option, GNU Chess chooses
 142 its search time based on the number of moves and amount of time
 143 remaining until the next time control.
 144 .TP 8
 145 .B \-searchDepth (or -sd) number
 146 Tells GNU Chess to look ahead at most the given number of moves when
 147 searching for a move to make.  Without this option, GNU Chess chooses its
 148 search depth based on the number of moves and amount of time remaining
 149 until the next time control.
 150 .TP 8
 151 .B \-saveGameFile (or -sgf) file
 152 If this option is set,
 153 .IR xboard
 154 appends a record of the game played to the specified file on exit.
 155 .TP 8
 156 .B -autosave or -autoSaveGames
 157 If this option is True, at the end of every game
 158 .IR xboard
 159 prompts you for a filename and appends a record of the game to the file you
 160 specify.
 161 .TP 8
 162 .B \-savePositionFile (or -spf) file
 163 If this option is set,
 164 .IR xboard
 165 appends the final position reached to the specified file on exit.
 166 .TP 8
 167 .B \-boardSize (or -size) "(Large | Medium | Small)"
 168 Determines how large the board will be and what built-in piece bitmaps
 169 will be used.  On a large board (the default),
 170 pieces are 80x80 pixels, on a medium board 64x64 pixels, and
 171 on a small board 40x40 pixels.
 172 .SH STARTING A GAME
 173 Type \fIcmail\fP from a shell to start a game as white.  After an opening
 174 message, you will be prompted for a game name, which is optional -- if you
 175 simply press return, the game name will take the form
 176 \fIyou\fP-VS-\fIopponent\fP.  You will next be prompted for the short name
 177 of your opponent.  If you haven't played this person before, you will also
 178 be prompted for his/her email address.  \fIcmail\fP will then invoke
 179 \fIxboard\fP in the background.  Make your first move and select \fIMail
 180 Move\fP from the \fIFile\fP menu.  If all is well, \fIcmail\fP will mail a
 181 copy of the move to your opponent. If you select \fIExit\fP without having
 182 selected \fIMail Move\fP then no move will be made.
 183 .SH ANSWERING A MOVE
 184 When you receive a message from an opponent containing a move in one of
 185 your games, simply pipe the message through \fIcmail\fP.  In some mailers
 186 this is as simple as typing "| cmail" when viewing the message, while in
 187 others you may have to save the message to a file and do "cmail < file" at
 188 the command line.  In either case \fIcmail\fP will display the game using
 189 \fIxboard\fP. If you didn't exit \fIxboard\fP when you made your first move
 190 then \fIcmail\fP will do its best to use the existing \fIxboard\fP instead
 191 of starting a new one. As before, simply make a move and select \fIMail
 192 Move\fP from the \fIFile\fP menu. \fIcmail\fP will try to use the
 193 \fIxboard\fP that was most recently used to display the current game. This
 194 means that many games can be in progress simultaneously, each with its own
 195 active \fIxboard\fP.
 196 .PP
 197 If you want to look at the history or explore a variation, go ahead, but
 198 you must return to the current position before \fIxboard\fP will allow you
 199 to mail a move. If you edit the game's history you must select \fIReload
 200 Same Game\fP from the \fIFile\fP menu to get back to the original position,
 201 then make the move you want and select \fIMail Move\fP.  As before, if you
 202 decide you aren't ready to make a move just yet you can either select
 203 \fIExit\fP without sending a move or just leave \fIxboard\fP running until
 204 you are ready.
 205 .SH COMPLETING A GAME
 206 Because \fIxboard\fP can now detect checkmate and stalemate, \fIcmail\fP
 207 now handles game termination sensibly. As well as resignation, the
 208 \fIAction\fP menu now allows draws to be offered and accepted for
 209 \fIcmail\fP games.
 210 .PP
 211 For multi-game messages, only unfinished and just-finished games will be
 212 included in email messages. When all the games are finished, they are
 213 archived in the user's archive directory, and similarly in the opponent's
 214 when he or she pipes the final message through \fIcmail\fP. The archive
 215 file name includes the date the game was started.
 216 .SH MULTI-GAME MESSAGES
 217 It's possible to have a \fIcmail\fP message carry more than one game. This
 218 feature was implemented to handle IECG (International Email Chess Group)
 219 matches, where a match consists of 1 game as white and 1 as black, with
 220 moves transmitted simultaneously. In case there are more general uses,
 221 \fIcmail\fP itself places no limit on the number of black/white games
 222 contained in a message; however, \fIxboard\fP does.
 223 .SH TROUBLE SHOOTING
 224 It's possible that a strange conjunction of conditions may occasionally
 225 mean that \fIcmail\fP has trouble reactivating an existing \fIxboard\fP. If
 226 this should happen, simply trying it again should work. If not, remove the
 227 file that stores the \fIxboard\fP's PID (<\fIgame\fP>.pid) or use the
 228 \fI-xreuse\fP option to force \fIcmail\fP to start a new \fIxboard\fP.
 229 .PP
 230 Versions of \fIcmail\fP after 2.16 no longer understand the old file format
 231 that \fIxboard\fP used to use and so cannot be used to correspond with
 232 anyone using an older version.
 233 .PP
 234 Versions of \fIcmail\fP older than 2.11 do not handle multi-game messages,
 235 so multi-game correspondence is not possible with opponents using an older
 236 version.
 237 .SH FILES
 238 "\fI.cmailgames\fP"
 239 contains a list of games with the email addresses of the opponents.
 240 .PP
 241 "\fI.cmailaliases\fP"
 242 contains one or more aliases for a set of email addresses.
 243 .SH BUGS
 244 No known bugs.
 245 .SH BUG REPORTS
 246 I make no promises but if you send bug reports/suggestions to
 247 Evan.Welsh@msdw.com I'll do my best to fix/implement them.
 248 .SH AUTHOR
 249 Copyright (C) 1993  Free Software Foundation, Inc.
 250 .PP
 251 \fIcmail\fP is free software; you can redistribute it and/or modify
 252 it under the terms of the GNU General Public License as published by
 253 the Free Software Foundation; either version 2 of the License, or
 254 (at your option) any later version.
 255 .PP
 256 \fIcmail\fP is distributed in the hope that it will be useful,
 257 but WITHOUT ANY WARRANTY; without even the implied warranty of
 258 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 259 GNU General Public License for more details.
 260 .PP
 261 You should have received a copy of the GNU General Public License
 262 along with cmail; if not, write to the Free Software
 263 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
 264 .sp
 265 .ta 1.0i 3.0i
 266 .nf
 267 Author: Evan Welsh <Evan.Welsh@msdw.com>
 268 .fi
 269 .SH CONTRIBUTORS
 270 .PP
 271 Patrick Surry helped with design, testing and documentation.
 272 .PP
 273 Tim Mann helped integrate \fIcmail\fP with \fIxboard\fP.
 274 .SH SEE ALSO
 275 \fIMail\fP(1), \fIperl\fP(1), \fIxboard\fP(1)