Initial checkin. I created this by combining the XBoard 4.2.6 and
[xboard.git] /
1 .\"=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
2 .\"# File:
3 .\"#
4 .\"# Author:      Evan Welsh
5 .\"#
6 .\"# Email:
7 .\"#
8 .\"# Modified:    $Date$
9 .\"#              $Revision$
10 .\"#
11 .\"# Summary:     Man page for cmail
12 .\"=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
13 .\"
14 .TH CMAIL 6
15 .PD
16 .ad b
18 cmail \- an email chess helper
20 \fBcmail\fR
21 [\|\fBoptions\fR\|]
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.
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
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.
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.
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.
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.
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.
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.
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.
246 I make no promises but if you send bug reports/suggestions to
247 I'll do my best to fix/implement them.
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
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 <>
268 .fi
270 .PP
271 Patrick Surry helped with design, testing and documentation.
272 .PP
273 Tim Mann helped integrate \fIcmail\fP with \fIxboard\fP.
275 \fIMail\fP(1), \fIperl\fP(1), \fIxboard\fP(1)