mlang pushed a commit to branch externals/chess
in repository elpa.
commit c7e551d9a9bc0ff29068ae8953c1e50bd39e831b
Author: Mario Lang <ml...@delysid.org>
Date: Thu Jun 12 08:24:08 2014 +0200
Work on the manual.
---
chess.info | 93 ++++++++++++++++++++++++++++++++++++-----------------
doc/chess.texi | 98 ++++++++++++++++++++++++++++++++------------------------
2 files changed, 119 insertions(+), 72 deletions(-)
diff --git a/chess.info b/chess.info
index 5075235..e29a790 100644
--- a/chess.info
+++ b/chess.info
@@ -1450,6 +1450,9 @@ customisable ASCII board diagram display.
-- User Option: chess-plain-spacing
Number of spaces between files.
+ To customize options of ‘chess-plain’, use ‘M-x customize-group <RET>
+chess-plain <RET>’.
+
File: chess.info, Node: ICS1 style ASCII displays, Next: Graphical displays,
Prev: Plain ASCII diagram displays, Up: Chessboard displays
@@ -1482,6 +1485,9 @@ File: chess.info, Node: ICS1 style ASCII displays,
Next: Graphical displays,
-- User Option: chess-ics1-separate-frame
If non-nil, display the chessboard in its own frame.
+ To customize options of ‘chess-ics1’, use ‘M-x customize-group <RET>
+chess-ics1 <RET>’.
+
File: chess.info, Node: Graphical displays, Prev: ICS1 style ASCII displays,
Up: Chessboard displays
@@ -1500,6 +1506,12 @@ create a visually appealing chessboard in a buffer.
The only image format currently supported is XPM.
+ -- User Option: chess-images-separate-frame
+ If non-nil, display the chessboard in its own frame.
+
+ For all customization options of ‘chess-images’, use ‘M-x
+customize-group <RET> chess-images <RET>’.
+
File: chess.info, Node: Engines, Next: Chess Session, Prev: Chessboard
displays, Up: Top
@@ -1647,13 +1659,13 @@ File: chess.info, Node: GNU Chess, Next: Phalanx,
Prev: Glaurung, Up: Engine
4.6 GNU Chess
=============
-"GNU Chess" is free software, licensed under the terms of the GNU
-General Public License version 3 or any later version, and is maintained
-by collaborating developers. As one of the earliest computer chess
+"GNU Chess" (http://gnu.org/software/chess/) is free software, licensed
+under the terms of the GNU General Public License, and is maintained by
+collaborating developers. As one of the earliest computer chess
programs with full source code available, it’s one of the oldest for
Unix-based systems and has since been ported to many other platforms.
- If the ‘gnuChess’ program is installed and can be found in the
+ If the ‘gnuchess’ program is installed and can be found in the
program search path (‘exec-path’), the ‘chess-gnuchess’ engine module
will automatically detect it.
@@ -1661,7 +1673,7 @@ will automatically detect it.
‘chess-gnuchess-path’ can be set to point to the executable.
If you have multiple engines installed you can explicitly select to
-play against GNU Chess by invoking .
+play against GNU Chess by invoking ‘C-u M-x chess <RET> gnuchess <RET>’.
File: chess.info, Node: Phalanx, Next: Sjeng, Prev: GNU Chess, Up: Engines
@@ -1754,6 +1766,16 @@ used to keep track of the currently active game.
later described in this manual make use of this, *Note Internet Chess
Servers::.
+ To interactively start a chess session, invoke ‘M-x chess <RET>’.
+This uses ‘chess-default-display’ to determine the chessboard display to
+use, and ‘chess-default-engine’ to determine an opponent.
+
+ If you want to play against a specific engine, provide a prefix
+argument as in ‘C-u M-x chess <RET>’, which will prompt for an engine
+module. The module name has the common prefix ‘chess-’ stripped. So
+you enter ‘gnuchess’ to indicate you’d like to play against the
+‘chess-gnuchess’ module.
+
File: chess.info, Node: Internet Chess Servers, Next: Concept Index, Prev:
Chess Session, Up: Top
@@ -2151,6 +2173,8 @@ Function and Variable Index
* chess-database-query: Querying Databases. (line 12)
* chess-database-read: Querying Databases. (line 9)
* chess-database-read-only-p: Modifying Databases. (line 6)
+* chess-default-display: Chess Session. (line 31)
+* chess-default-engine: Chess Session. (line 31)
* chess-default-modules: ECO Classification. (line 6)
* chess-direction-east: Position coordinates.
(line 37)
@@ -2254,6 +2278,7 @@ Function and Variable Index
* chess-ics1-separate-frame: ICS1 style ASCII displays.
(line 29)
* chess-images-directory: Graphical displays. (line 9)
+* chess-images-separate-frame: Graphical displays. (line 18)
* chess-index-file: Position coordinates.
(line 13)
* chess-index-rank: Position coordinates.
@@ -2429,6 +2454,7 @@ Key Index
* C-M-l: Chess ICS Mode. (line 62)
* C-r: Basic operations. (line 13)
* C-s: Basic operations. (line 17)
+* C-u M-x chess RET: Chess Session. (line 35)
* C-u M-x chess RET ai RET: AI. (line 10)
* C-u M-x chess RET crafty RET: Crafty. (line 18)
* C-u M-x chess RET fruit RET: Fruit. (line 21)
@@ -2462,6 +2488,13 @@ Key Index
* M-p: ICS Command Ring. (line 6)
* M-r: ICS Command Ring. (line 14)
* M-w: Basic operations. (line 38)
+* M-x chess RET: Chess Session. (line 31)
+* M-x customize-group RET chess-ics1 RET: ICS1 style ASCII displays.
+ (line 32)
+* M-x customize-group RET chess-images RET: Graphical displays.
+ (line 21)
+* M-x customize-group RET chess-plain RET: Plain ASCII diagram displays.
+ (line 51)
* N: Entering moves with algebraic
notation.
(line 6)
* Q: Entering moves with algebraic
notation.
@@ -2534,31 +2567,31 @@ Node: Selecting pieces with the keyboard50049
Node: Selecting pieces with the mouse50641
Node: Entering moves with algebraic notation51207
Node: Plain ASCII diagram displays52225
-Node: ICS1 style ASCII displays54008
-Node: Graphical displays55260
-Node: Engines55894
-Node: Common functions56410
-Node: AI57458
-Node: Crafty58437
-Node: Fruit59224
-Node: Glaurung60120
-Node: GNU Chess60760
-Node: Phalanx61643
-Node: Sjeng62275
-Node: Stockfish63014
-Node: Chess Session63829
-Node: Internet Chess Servers65068
-Node: Connecting to a server66225
-Node: Chess ICS Mode66781
-Node: Command History70294
-Node: ICS Command Ring70915
-Node: ICS History Copying74128
-Node: Seeking an opponent for a new game75646
-Node: The sought game display76295
-Node: Watching other games77323
-Node: Concept Index78805
-Node: Function and Variable Index80664
-Node: Key Index97689
+Node: ICS1 style ASCII displays54110
+Node: Graphical displays55462
+Node: Engines56313
+Node: Common functions56829
+Node: AI57877
+Node: Crafty58856
+Node: Fruit59643
+Node: Glaurung60539
+Node: GNU Chess61179
+Node: Phalanx62104
+Node: Sjeng62736
+Node: Stockfish63475
+Node: Chess Session64290
+Node: Internet Chess Servers66057
+Node: Connecting to a server67214
+Node: Chess ICS Mode67770
+Node: Command History71283
+Node: ICS Command Ring71904
+Node: ICS History Copying75117
+Node: Seeking an opponent for a new game76635
+Node: The sought game display77284
+Node: Watching other games78312
+Node: Concept Index79794
+Node: Function and Variable Index81653
+Node: Key Index98897
End Tag Table
diff --git a/doc/chess.texi b/doc/chess.texi
index 1ac323a..590f678 100644
--- a/doc/chess.texi
+++ b/doc/chess.texi
@@ -15,7 +15,7 @@
Copyright @copyright{} 2001, 2002, 2014 Free Software Foundation, @abbr{Inc.}
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the @acronym{GNU} Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
@end ifinfo
@@ -45,7 +45,7 @@ any later version published by the Free Software Foundation.
Copyright @copyright{} 2001, 2002, 2014 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the @acronym{GNU} Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation.
@end titlepage
@@ -464,9 +464,9 @@ FEN strings. If you are unsure, use the more verbose form:
@dfn{@acronym{EPD, Extended Position Description}} is a standard for
describing chess
positions along with an extended set of structured attribute values using the
-ASCII character set. It is intended for data and command interchange among
-chess-playing programs. It is also intended for the representation of portable
-opening library repositories.
+@acronym{ASCII} character set. It is intended for data and command interchange
+among chess-playing programs. It is also intended for the representation of
+portable opening library repositories.
A single EPD uses one text line of variable length composed of four data field
followed by zero or more operations. The four fields of the @acronym{EPD}
specification
@@ -513,7 +513,7 @@ Some opcodes that allow for more than one operand may have
special ordering
requirements for the operands. For example, the "pv" (predicted variation)
opcode requires its operands (moves) to appear in the order in which they would
be played. All other opcodes that allow for more than one operand should have
-operands appearing in ASCII order. An example of the latter set is the "bm"
+operands appearing in @acronym{ASCII} order. An example of the latter set is
the "bm"
(best move[s]) opcode; its operands are moves that are all immediately playable
from the current position.
@@ -544,14 +544,14 @@ byte) representation is suggested.
The opcode "am" indicates a set of zero or more moves, all immediately playable
from the current position, that are to be avoided in the opinion of the EPD
-writer. Each operand is a SAN move; they appear in ASCII order.
+writer. Each operand is a @acronym{SAN} move; they appear in @acronym{ASCII}
order.
@node Opcode "bm" best move(s), , Opcode "am" avoid move(s), EPD notation
@subsubsection Opcode "bm" best move(s)
The opcode "bm" indicates a set of zero or more moves, all immediately playable
from the current position, that are judged to the best available by the EPD
-writer. Each operand is a SAN move; they appear in ASCII order.
+writer. Each operand is a @acronym{SAN} move; they appear in @acronym{ASCII}
order.
@node Plies, Variations, Positions, The chess.el library
@section Plies
@@ -713,8 +713,8 @@ 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
+Variations may be represented in @acronym{ASCII} by stating the @acronym{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.
@@ -814,56 +814,41 @@ 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 @acronym{PGN, Portable Game Notation}.
+A game may be represented in @acronym{ASCII} using @acronym{PGN,
+Portable Game Notation}.
Representing them graphically or verbally is similar to what is done
for variations.
-@c lispfun chess-game-add-hook
-
@defun chess-game-add-hook game function &optional data prepend
Add to @var{game} an event hook @var{function}.
@end defun
-@c lispfun chess-game-add-ply
-
@defun chess-game-add-ply game ply
Add @var{ply} to the main variation of @var{game}.
@end defun
-@c lispfun chess-game-hooks
-
@defun chess-game-hooks game
Return the event hooks associated with @var{game}.
@end defun
-@c lispfun chess-game-plies
-
@defun chess-game-plies game
Return the main variation of @var{game} as a list of plies.
@end defun
-@c lispfun chess-game-remove-hook
-
@defun chess-game-remove-hook game function &optional data
Remove from @var{game} all event hooks that match @var{function}.
If @var{data} is specified, only remove those hooks whose associated data
matches.
@end defun
-@c lispfun chess-game-run-hooks
-
@defun chess-game-run-hooks game &rest args
Run the event hooks of @var{game} and pass @var{args}.
@end defun
-@c lispfun chess-game-set-hooks
-
@defun chess-game-set-hooks game hooks
Set the event hooks associated with @var{game}.
@end defun
-@c lispfun chess-game-set-plies
-
@defun chess-game-set-plies game plies
Set the list of plies which represents the main variation of @var{game}.
@end defun
@@ -1697,6 +1682,10 @@ modify `chess-plain-piece-chars' to avoid real
confusion.)
Number of spaces between files.
@end defopt
+@kindex M-x customize-group RET chess-plain RET
+To customize options of @code{chess-plain}, use
+@kbd{M-x customize-group @key{RET} chess-plain @key{RET}}.
+
@node ICS1 style ASCII displays, Graphical displays, Plain ASCII diagram
displays, Chessboard displays
@section ICS1 style ASCII displays
@@ -1729,6 +1718,10 @@ This is how the starting position looks with this
chessboard display:
If non-nil, display the chessboard in its own frame.
@end defopt
+@kindex M-x customize-group RET chess-ics1 RET
+To customize options of @code{chess-ics1}, use
+@kbd{M-x customize-group @key{RET} chess-ics1 @key{RET}}.
+
@node Graphical displays, , ICS1 style ASCII displays, Chessboard displays
@section Graphical displays
@@ -1745,6 +1738,14 @@ and @var{piece} is one of rook, knight, bishop, queen,
king or pawn.
The only image format currently supported is @acronym{XPM}.
@end defopt
+@defopt chess-images-separate-frame
+If non-nil, display the chessboard in its own frame.
+@end defopt
+
+@kindex M-x customize-group RET chess-images RET
+For all customization options of @code{chess-images}, use
+@kbd{M-x customize-group @key{RET} chess-images @key{RET}}.
+
@node Engines, Chess Session, Chessboard displays, Top
@chapter Engines
@@ -1768,18 +1769,14 @@ for playing with opponent over different types of
transports.
@node Common functions, AI, Engines, Engines
@section Common functions
-@c lispfun chess-engine-create
-
@defun chess-engine-create module game &optional response-handler &rest
handler-ctor-args
Create a new chess engine @var{module} (a symbol) associated with @var{game}.
Optionally supply a new @var{response-handler}.
@end defun
-@c lispfun chess-engine-set-option
-
@defun chess-engine-set-option engine option value
-Set @var{engine} @var{option} to @var{value} by invoking its handler with the
'set-option
-event.
+Set @var{engine} @var{option} to @var{value} by invoking its handler with
+the 'set-option event.
@end defun
@c lispfun chess-engine-destroy
@@ -1907,23 +1904,25 @@ to play against Glaurung by invoking @kbd{C-u M-x chess
@key{RET} glaurung @key{
@node GNU Chess, Phalanx, Glaurung, Engines
@section GNU Chess
-@dfn{GNU Chess} is free software, licensed under the terms of the
-GNU General Public License version 3 or any later version,
-and is maintained by collaborating developers. As one of the earliest
-computer chess programs with full source code available, it's one of the oldest
-for Unix-based systems and has since been ported to many other platforms.
+@uref{http://gnu.org/software/chess/, @dfn{@acronym{GNU} Chess}} is free
+software, licensed under the terms of the @acronym{GNU} General Public
License, and is
+maintained by collaborating developers.
+As one of the earliest computer chess programs with full source code available,
+it's one of the oldest for Unix-based systems and has since been ported to many
+other platforms.
-If the @command{gnuChess} program is installed and can be found in the
+If the @command{gnuchess} program is installed and can be found in the
program search path (@code{exec-path}),
the @code{chess-gnuchess} engine module will automatically detect it.
@vindex chess-gnuchess-path
-If GNU Chess is installed in a non-standard location, variable
+If @acronym{GNU} Chess is installed in a non-standard location, variable
@code{chess-gnuchess-path} can be set to point to the executable.
@kindex C-u M-x chess RET gnuchess RET
If you have multiple engines installed you can explicitly select
-to play against GNU Chess by invoking .
+to play against @acronym{GNU} Chess by invoking
+@kbd{C-u M-x chess @key{RET} gnuchess @key{RET}}.
@node Phalanx, Sjeng, GNU Chess, Engines
@section Phalanx
@@ -1968,7 +1967,7 @@ to play against Sjeng by invoking @kbd{C-u M-x chess
@key{RET} sjeng @key{RET}}.
chess engines in the world, appearing near or at the top of most chess engine
rating lists.
Stockfish is also free software, licensed under the terms of the
-GNU General Public License.
+@acronym{GNU} General Public License.
If the @command{stockfish} program is installed and can be found in the
program search path (@code{exec-path}),
@@ -2011,6 +2010,21 @@ You can have several active chess sessions.
In fact, some features later described in this manual make use
of this, @xref{Internet Chess Servers}.
+@kindex M-x chess RET
+@vindex chess-default-display
+@vindex chess-default-engine
+To interactively start a chess session, invoke
+@kbd{M-x chess @key{RET}}. This uses @code{chess-default-display}
+to determine the chessboard display to use, and
+@code{chess-default-engine} to determine an opponent.
+
+@kindex C-u M-x chess RET
+If you want to play against a specific engine, provide
+a prefix argument as in @kbd{C-u M-x chess @key{RET}}, which will
+prompt for an engine module. The module name has the common
+prefix @samp{chess-} stripped. So you enter @samp{gnuchess}
+to indicate you'd like to play against the @code{chess-gnuchess} module.
+
@node Internet Chess Servers, Concept Index, Chess Session, Top
@chapter Internet Chess Servers
