path: root/chess.texi

\input texinfo  @c -*-texinfo-*-

@c "@(#)$Name$:$Id$"

@c Documentation for Chess.el.
@c Copyright (C) 2001, 20002 John Wiegley.

@c This file is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 2 of the License, or (at
@c your option) any later version.

@c This file is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warraonty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
@c General Public License for more details.

@c You should have received a copy of the GNU General Public License
@c along with Eshell; see the file COPYING.  If not, write to the Free
@c Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

@c %**start of header
@setfilename chess.info
@settitle Chess.el
@c %**end of header

@dircategory Emacs
@direntry
* Chess: (chess).     Chess.el is an Emacs chess client.
@end direntry
@setchapternewpage on

@ifinfo
Copyright @copyright{} 2001, 2002 John Wiegley.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
@end ifinfo

@synindex vr fn
@c The titlepage section does not appear in the Info file.
@titlepage
@sp 4
@c The title is printed in a large font.
@center @titlefont{User's Guide}
@sp
@center @titlefont{to}
@sp
@center @titlefont{Chess.el}
@ignore
@sp 2
@center release 2.0
@c -release-
@end ignore
@sp 3
@center John Wiegley
@c -date-

@c  The following two commands start the copyright page for the printed
@c  manual.  This will not appear in the Info file.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001, 2002 John Wiegley.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
@end titlepage

@contents

@c ================================================================
@c                   The real text starts here
@c ================================================================

@ifinfo
@node Top, The Chess.el library, (dir), (dir)
@top Chess.el

Chess.el is an Emacs chess environment, designed in a modular fashion to
be used either as a library for writing chess-related programs, or as a
plain client for playing chess, analyzing variations, or browsing
historical games.

The purpose of this manual is to help you understand how Chess.el is
structured for use as a library, and also how to use the optional
modules which make it useful as a client.  These modules also serve as
an example of how to make use of the library.
@end ifinfo

@menu
* The Chess.el library::        
* Play sessions::               
* Display modules::             
* Ply sources::                 
@end menu

@node The Chess.el library, Play sessions, Top, Top
@chapter The Chess.el library
@cindex library

@menu
* Positions::                   
* Plies::                       
* Variations::                  
* Games::                       
* Collections::                 
@end menu

@node Positions, Plies, The Chess.el library, The Chess.el library
@section Positions

A chess @dfn{position} is a given layout of pieces on the chess board,
reflecting also which side is next to move, and what privileges are
currently available to each side (castling short or long, en passant
capture, etc).

A position may be represented in ASCII using FEN notation, or
graphically by displaying a chess board.  It is rather inconvenient to
render them verbally.

The position can be represented on a remote terminal using X windows, or
by transmitting the FEN string via a network connection, or clipboard,
to another chess board rendering tool.  It may of course also be
represented physically, by setting up the pieces to match the FEN
notation.

Chess puzzles are most often provided as a set of positions.

@menu
* Creating positions::          
* Position coordinates::        
* Manipulating pieces::         
* Position details::            
* Annotations::                 
* FEN notation::                
@end menu

@node Creating positions, Position coordinates, Positions, Positions
@subsection Creating positions

@defun chess-pos-create &optional blank
@end defun

@defun chess-pos-copy position
@end defun

@defvar chess-starting-position
@end defvar

@node Position coordinates, Manipulating pieces, Creating positions, Positions
@subsection Position coordinates

@defun chess-index-rank index
@end defun

@defun chess-index-file index
@end defun

@defun chess-rf-to-index rank file
@end defun

@defun chess-coord-to-index coord
@end defun

@defun chess-index-to-coord index
@end defun

@defun chess-add-index index rank-move file-move
@end defun

@node Manipulating pieces, Position details, Position coordinates, Positions
@subsection Manipulating pieces

@defun chess-pos-piece position index
@end defun

@defun chess-pos-piece-p position index piece-or-color
@end defun

@defun chess-pos-set-piece position index piece
@end defun

@defun chess-pos-search position piece-or-color
@end defun

@node Position details, Annotations, Manipulating pieces, Positions
@subsection Position details

@defun chess-pos-can-castle position side
@end defun

@defun chess-pos-set-can-castle position side value
@end defun

@defun chess-pos-en-passant position
@end defun

@defun chess-pos-set-en-passant position index
@end defun

@defun chess-pos-status position
@end defun

@defun chess-pos-set-status position status
@end defun

@defun chess-pos-side-to-move position
@end defun

@defun chess-pos-set-side-to-move position color
@end defun

@node Annotations, FEN notation, Position details, Positions
@subsection Annotations

@defun chess-pos-annotation position
@end defun

@defun chess-pos-add-annotation position annotation
@end defun

@node FEN notation,  , Annotations, Positions
@subsection FEN notation

@defun chess-fen-to-pos fen-string
@end defun

@defun chess-pos-to-fen position &optional full
@end defun

@node Plies, Variations, Positions, The Chess.el library
@section Plies

A @dfn{ply} is the differential between two positions.  Or, it is the
coordinate transformations applied to one position in order to arrive at
the following position.  It is also informally called "a move".

A ply may be represented in ASCII by printing the FEN string of the base
position, and then printing the positional transformation in algebraic
notation.  Since the starting position is usually known, the FEN string
is optional.  A ply may be represented graphically by moving the chess
piece(s) involved.  It may be rendered verbally by voicing which piece
is to move, where it will move to, and what will happen a result of the
move (piece capture, check, etc).

Plies may be sent over network connections, postal mail, e-mail, etc.,
so long as the current position is maintained at both sides.
Transmitting the base position's FEN string along with the ply offers a
form of confirmation during the course of a game.

@menu
* Creating plies::              
* Ply details::                 
* The "next" position::         
* Algebraic notation::          
@end menu

@node Creating plies, Ply details, Plies, Plies
@subsection Creating plies

@defun chess-ply-create position &rest changes
@end defun

@defun chess-legal-plies position color
@end defun

@node Ply details, The "next" position, Creating plies, Plies
@subsection Ply details

@defun chess-ply-pos ply
@end defun

@defun chess-ply-set-pos ply position
@end defun

@defun chess-ply-changes ply
@end defun

@defun chess-ply-set-changes ply changes
@end defun

@node The "next" position, Algebraic notation, Ply details, Plies
@subsection The "next" position

@defun chess-ply-next-pos ply
@end defun

@node Algebraic notation,  , The "next" position, Plies
@subsection Algebraic notation

@defun chess-ply-to-algebraic ply &optional long
@end defun

@defun chess-algebraic-to-ply position move
@end defun

@defvar chess-algebraic-regexp
@end defvar

@node Variations, Games, Plies, The Chess.el library
@section Variations

A @dfn{variation} is a sequence of plies that occur after some starting
position.  If the starting position represents the initial setup of a
chess board, and if the final ply results in completion of the game, it
is called the "main variation".  Otherwise, variations typically
represented interesting tangents during a game---but not actually
played---as envisioned by the player, an annotator, or someone studying
the game.

Variations may be represented in ASCII by stating the FEN string for
starting position, followed by the list of plies that follow that
position.  They are difficult to represent graphically, except for
showing each position in turn with a slight pause between---or by
allowing the user to navigate each of the subsequent positions in turn.
They may be represented verbally by announcing each of the plies in
turn, as mentioned above.

@node Games, Collections, Variations, The Chess.el library
@section Games

A @dfn{game} includes its main variation, incidental information about
the game (who played it, where, when, who won, etc), and any
sub-variations of interest to those studying the game afterwards.

Where TAGS is an alist that associates arbitrary English tag names to
their values.

A game may be represented in ASCII using standard PGN notation.
Representing them graphically or verbally is similar to what is done
for variations.

@menu
* Creating games::              
* Game tags::                   
* Game positions::              
* Game plies::                  
@end menu

@node Creating games, Game tags, Games, Games
@subsection Creating games

@defun chess-game-create &optional tags position
@end defun

@node Game tags, Game positions, Creating games, Games
@subsection Game tags

@defun chess-game-tags game
@end defun

@defun chess-game-set-tags game tags
@end defun

@defun chess-game-tag game tag
@end defun

@defun chess-game-set-tag game tag value
@end defun

@defun chess-game-del-tag game tag
@end defun

@node Game positions, Game plies, Game tags, Games
@subsection Game positions

@defun chess-game-pos game &optional index
@end defun

@defun chess-game-index game
@end defun

@defun chess-game-seq game
@end defun

@defun chess-game-side-to-move game
@end defun

@node Game plies,  , Game positions, Games
@subsection Game plies

@defun chess-game-ply game &optional index
@end defun

@subsection Making a move

@defun chess-game-move game ply
@end defun

@subsection PGN notation

@defun chess-pgn-to-game
@end defun

@defun chess-game-to-pgn game &optional indented
@end defun

@defun chess-pgn-insert-plies index plies &optional for-black indented no-ann
@end defun

@subsubsection PGN mode

@node Collections,  , Games, The Chess.el library
@section Collections

A @dfn{collection} is a set of games archived for later perusal.  A set
of games conceptually represents a large tree of branching variations,
and can be used for studying current theory, examining Master
preferences, etc.

Chess.el itself does not attempt to provide library services, or does it
ever represent library collections in memory.  Instead, it interacts
with a chess database engine for the purpose of storing and retrieving
games from the library, or performing library-wide analyses and
searches.

@node Play sessions, Display modules, The Chess.el library, Top
@chapter Play sessions

@node Display modules, Ply sources, Play sessions, Top
@chapter Display modules

@node Ply sources,  , Display modules, Top
@chapter Ply sources

@menu
* Chess engines::               
@end menu

@node Chess engines,  , Ply sources, Ply sources
@section Chess engines

@unnumbered Concept Index

@printindex cp

@unnumbered Function and Variable Index

@printindex fn

@unnumbered Key Index

@printindex ky
@bye