1 \input texinfo @c -*-texinfo-*-
5 @c Documentation for Chess.el.
6 @c Copyright (C) 2001, 2002 John Wiegley.
8 @c This file is free software; you can redistribute it and/or modify it
9 @c under the terms of the GNU General Public License as published by the
10 @c Free Software Foundation; either version 2 of the License, or (at
11 @c your option) any later version.
13 @c This file is distributed in the hope that it will be useful, but
14 @c WITHOUT ANY WARRANTY; without even the implied warraonty of
15 @c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 @c General Public License for more details.
18 @c You should have received a copy of the GNU General Public License
19 @c along with Eshell; see the file COPYING. If not, write to the Free
20 @c Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
23 @setfilename chess.info
24 @settitle Emacs Chess: chess.el
29 * Chess: (chess). Chess.el is an Emacs chess client.
34 Copyright @copyright{} 2001, 2002 John Wiegley.
36 Permission is granted to copy, distribute and/or modify this document
37 under the terms of the GNU Free Documentation License, Version 1.1 or
38 any later version published by the Free Software Foundation.
42 @c The titlepage section does not appear in the Info file.
45 @c The title is printed in a large font.
46 @center @titlefont{User's Guide}
48 @center @titlefont{to}
50 @center @titlefont{Emacs Chess: chess.el}
60 @c The following two commands start the copyright page for the printed
61 @c manual. This will not appear in the Info file.
63 @vskip 0pt plus 1filll
64 Copyright @copyright{} 2001, 2002 John Wiegley.
66 Permission is granted to copy, distribute and/or modify this document
67 under the terms of the GNU Free Documentation License, Version 1.1 or
68 any later version published by the Free Software Foundation.
73 @c ================================================================
74 @c The real text starts here
75 @c ================================================================
78 @node Top, Emacs Chess: chess.el, (dir), (dir)
79 @top Emacs Chess: chess.el
81 Chess.el is an Emacs chess client and library, designed to be used for
82 writing chess-related programs, or for playing games of chess against
83 various chess engines, including Internet servers. The library can be
84 used for analyzing variations, browsing historical games, or a
85 multitude of other purposes.
87 The purpose of this manual is to help you understand how Chess.el is
88 structured for use as a library, and also how to use it as a client.
91 @chapter The chess.el library
96 A chess @dfn{position} is a given layout of pieces on a chess board,
97 reflecting also which side is next to move, and what privileges are
98 currently available to each side (castling short or long, en passant
101 A position may be represented in ASCII using FEN notation, or
102 graphically by displaying a chess board. It is rather inconvenient to
103 render them verbally.
105 The position can be represented on a remote terminal using X windows, or
106 by transmitting the FEN string via a network connection, or clipboard,
107 to another chess board rendering tool. It may of course also be
108 represented physically, by setting up the pieces to match the FEN
111 Chess puzzles are most often provided as a set of positions.
113 @subsection Creating positions
115 @c lispfun chess-pos-create
117 @c lispfun chess-pos-copy
119 @defvar chess-starting-position
122 @c lispfun chess-fischer-random-position
124 @subsection Position coordinates
126 First of all, a coordinate system of octal indices is
127 used, where ?\044 signifies rank 4 file 4 (i.e., "e4"). Rank is
128 numbered 0 to 7, top to bottom, and file is 0 to 7, left to right.
130 @c lispfun chess-index-rank
132 @c lispfun chess-index-file
134 @c lispfun chess-rf-to-index
136 For those who wish to use ASCII coordinates, such as "e4", there
137 are two conversion functions:
139 @c lispfun chess-coord-to-index
141 @c lispfun chess-index-to-coord
143 @c lispfun chess-incr-index
145 @subsection Position details
147 With an octal index value, you can look up what's on a particular
148 square, or set that square's value:
150 @c lispfun chess-pos-piece
152 @c lispfun chess-pos-piece-p
154 @c lispfun chess-pos-set-piece
156 @c lispfun chess-pos-search
158 @c lispfun chess-search-position
160 @c lispfun chess-pos-can-castle
162 @c lispfun chess-pos-set-can-castle
164 @c lispfun chess-pos-en-passant
166 @c lispfun chess-pos-set-en-passant
168 @c lispfun chess-pos-status
170 @c lispfun chess-pos-set-status
172 @c lispfun chess-pos-side-to-move
174 @c lispfun chess-pos-set-side-to-move
176 @c lispfun chess-pos-move
178 Missing documentation for 'chess-pos-move'
180 @subsection Annotations
182 @c lispfun chess-pos-annotations
184 @c lispfun chess-pos-add-annotation
186 @subsection FEN notation
188 @c lispfun chess-fen-to-pos
190 @c lispfun chess-pos-to-fen
194 A @dfn{ply} is the differential between two positions. Or, it is the
195 coordinate transformations applied to one position in order to arrive at
196 the following position. It is also informally called "a move".
198 A ply may be represented in ASCII by printing the FEN string of the base
199 position, and then printing the positional transformation in algebraic
200 notation. Since the starting position is usually known, the FEN string
201 is optional. A ply may be represented graphically by moving the chess
202 piece(s) involved. It may be rendered verbally by voicing which piece
203 is to move, where it will move to, and what will happen a result of the
204 move (piece capture, check, etc).
206 Plies may be sent over network connections, postal mail, e-mail, etc.,
207 so long as the current position is maintained at both sides.
208 Transmitting the base position's FEN string along with the ply offers a
209 form of confirmation during the course of a game.
211 @subsection Creating plies
213 @c lispfun chess-ply-create
215 @c lispfun chess-legal-plies
217 @subsection Ply details
219 @c lispfun chess-ply-pos
221 @c lispfun chess-ply-set-pos
223 @c lispfun chess-ply-changes
225 @c lispfun chess-ply-set-changes
227 @c lispfun chess-ply-source
229 @c lispfun chess-ply-target
231 @subsection The "next" position
233 @c lispfun chess-ply-next-pos
235 @c lispfun chess-ply-final-p
237 @subsection Algebraic notation
239 @c lispfun chess-ply-to-algebraic
241 @c lispfun chess-algebraic-to-ply
243 @defvar chess-algebraic-regexp
248 A @dfn{variation} is a sequence of plies that occur after some starting
249 position. If the starting position represents the initial setup of a
250 chess board, and if the final ply results in completion of the game, it
251 is called the "main variation". Otherwise, variations typically
252 represented interesting tangents during a game---but not actually
253 played---as envisioned by the player, an annotator, or someone studying
256 Variations may be represented in ASCII by stating the FEN string for
257 starting position, followed by the list of plies that follow that
258 position. They are difficult to represent graphically, except for
259 showing each position in turn with a slight pause between---or by
260 allowing the user to navigate each of the subsequent positions in turn.
261 They may be represented verbally by announcing each of the plies in
262 turn, as mentioned above.
264 @subsection Creating variations
266 @c lispfun chess-var-create
268 @subsection Variation positions
270 @c lispfun chess-var-pos
272 @c lispfun chess-var-index
274 @c lispfun chess-var-seq
276 @c lispfun chess-var-side-to-move
278 @subsection Varation plies
280 @c lispfun chess-var-ply
282 @c lispfun chess-var-plies
284 @c lispfun chess-var-to-algebraic
286 @subsection Making a move in a variation
288 @c lispfun chess-var-move
290 @c lispfun chess-var-add-ply
294 A @dfn{game} includes its main variation, incidental information about
295 the game (who played it, where, when, who won, etc), and any
296 sub-variations of interest to those studying the game afterwards.
298 Where TAGS is an alist that associates arbitrary English tag names to
301 A game may be represented in ASCII using standard PGN notation.
302 Representing them graphically or verbally is similar to what is done
305 @c lispfun chess-game-add-hook
307 @c lispfun chess-game-add-ply
309 @c lispfun chess-game-hooks
311 @c lispfun chess-game-plies
313 @c lispfun chess-game-remove-hook
315 @c lispfun chess-game-run-hooks
317 @c lispfun chess-game-set-hooks
319 @c lispfun chess-game-set-plies
321 @subsection Creating games
323 @c lispfun chess-game-create
325 @subsection Game tags
327 @c lispfun chess-game-tags
329 @c lispfun chess-game-set-tags
331 @c lispfun chess-game-tag
333 @c lispfun chess-game-set-tag
335 @c lispfun chess-game-del-tag
337 @subsection Game positions
339 @c lispfun chess-game-pos
341 @c lispfun chess-game-index
343 @c lispfun chess-game-seq
345 @c lispfun chess-game-side-to-move
347 @subsection Game plies
349 @c lispfun chess-game-ply
351 @subsection Making a move
353 @c lispfun chess-game-move
355 @subsection PGN notation
357 @c lispfun chess-pgn-to-game
359 @c lispfun chess-game-to-pgn
361 @c lispfun chess-pgn-insert-plies
363 @subsubsection PGN mode
367 A @dfn{collection} is a set of games archived for later perusal. A set
368 of games conceptually represents a large tree of branching variations,
369 and can be used for studying current theory, examining Master
372 Chess.el itself does not attempt to provide library services, or does it
373 ever represent library collections in memory. Instead, it interacts
374 with a chess database engine for the purpose of storing and retrieving
375 games from the library, or performing library-wide analyses and
378 @subsection Opening Databases
380 @defvar chess-database-modules
381 List of database modules to try when `chess-database-open' is called.
384 @c lispfun chess-database-open
386 @subsection Querying Databases
388 @c lispfun chess-database-count
390 @c lispfun chess-database-read
392 @c lispfun chess-database-query
394 @subsection Modifying Databases
396 @c lispfun chess-database-write
398 @c lispfun chess-database-replace
400 @subsection Finalising Databases
402 @c lispfun chess-database-save
404 @c lispfun chess-database-close
408 The previous chapter described all the objects found in
409 chess---positions, plies, variations, games and collections. However,
410 these objects can only be manipulated programmitically using the
411 functions given so far. In order to present them in a meaningful
412 fashion to a human reader, it is necessary to create and use a display
415 @c lispfun chess-display-create
417 @c lispfun/c chess-display-destroy
419 @chapter Chessboard displays
421 @c lispfun chess-display-active-p
423 @c lispfun chess-display-clear-board
425 @c lispfun chess-display-game
427 @c lispfun chess-display-highlight
429 @c lispfun chess-display-index
431 @c lispfun chess-display-invert
433 @c lispfun chess-display-move
435 @c lispfun chess-display-move-backward
437 @c lispfun chess-display-move-first
439 @c lispfun chess-display-move-forward
441 @c lispfun chess-display-move-last
443 @c lispfun chess-display-perspective
445 @c lispfun chess-display-ply
447 @c lispfun chess-display-position
449 @c lispfun chess-display-quit
451 @c lispfun chess-display-set-game
453 @c lispfun chess-display-set-index
455 @c lispfun chess-display-set-perspective
457 @c lispfun chess-display-set-ply
459 @c lispfun chess-display-set-position
461 @c lispfun chess-display-set-variation
463 @c lispfun chess-display-update
465 @c lispfun chess-display-variation
469 @c lispfun chess-engine-create
471 @c lispfun chess-engine-set-option
473 @c lispfun/c chess-engine-destroy
475 @c lispfun chess-engine-set-position
477 @c lispfun chess-engine-position
479 @c lispfun chess-engine-set-game
481 @c lispfun chess-engine-game
483 @c lispfun chess-engine-index
485 @c lispfun chess-engine-move
487 @c lispfun chess-engine-command
489 @c lispfun chess-engine-send
491 @unnumbered Concept Index
495 @unnumbered Function and Variable Index
499 @unnumbered Key Index