mlang pushed a commit to branch externals/chess
in repository elpa.
commit 515805a6fd004f373c4acb92a8f9894301cadbd6
Author: Mario Lang <ml...@delysid.org>
Date: Thu Jun 5 02:56:21 2014 +0200
doc/chess.texi: Briefly document chess-eco.el and chess-polyglot.el.
---
chess.info | 205 +++++++++++++++++++++++++++++++++++++++-----------------
doc/chess.texi | 65 +++++++++++++++++-
2 files changed, 208 insertions(+), 62 deletions(-)
diff --git a/chess.info b/chess.info
index 05d038a..78e6402 100644
--- a/chess.info
+++ b/chess.info
@@ -50,6 +50,7 @@ File: chess.info, Node: The chess.el library, Next:
Modules, Prev: Top, Up:
* Variations::
* Games::
* Collections::
+* Chess Opening Books::
File: chess.info, Node: Positions, Next: Plies, Prev: The chess.el library,
Up: The chess.el library
@@ -833,7 +834,7 @@ File: chess.info, Node: PGN mode, Prev: PGN notation,
Up: PGN notation
require that the buffer be in PGN mode.
-File: chess.info, Node: Collections, Prev: Games, Up: The chess.el library
+File: chess.info, Node: Collections, Next: Chess Opening Books, Prev:
Games, Up: The chess.el library
1.5 Collections
===============
@@ -942,6 +943,74 @@ This modules implement basic reading and writing
functionality for SCID
(Shane's Chess Information Database) files.
+File: chess.info, Node: Chess Opening Books, Prev: Collections, Up: The
chess.el library
+
+1.6 Chess Opening Books
+=======================
+
+There are two different modules/libraries provided for looking up chess
+positions in opening books.
+
+* Menu:
+
+* ECO Classification::
+* Polyglot opening book format support::
+
+
+File: chess.info, Node: ECO Classification, Next: Polyglot opening book
format support, Prev: Chess Opening Books, Up: Chess Opening Books
+
+1.6.1 ECO Classification
+------------------------
+
+Module 'chess-eco' provides a database of well known names for chess
+opening positions. If this module is activated (see variable
+'chess-default-modules') known chess opening positions will be announced
+in the minibuffer during a game.
+
+
+File: chess.info, Node: Polyglot opening book format support, Prev: ECO
Classification, Up: Chess Opening Books
+
+1.6.2 Polyglot opening book format support
+------------------------------------------
+
+The popular and freely documented Polyglot opening book format is
+supported. There is a default polyglot book file shipped with chess.el
+to support engines which do not have built-in support for looking up
+positions in opening books (such as some UCI protocol based engines).
+
+ -- Variable: chess-polyglot-book-file
+ Path to default polyglot book file.
+
+ -- Variable: chess-polyglot-book
+ If non-nil, the buffer holding the currently loaded polyglot book
+ data.
+
+ This is used by UCI based engine modules as well as the internal
+ AI.
+
+ -- Function: chess-polyglot-book-open file
+ Open a polyglot book FILE.
+
+ Returns a buffer object which contains the binary data.
+
+ -- Function: chess-polyglot-book-plies book position
+ Return a list of plies found in BOOK for POSITION. The resulting
+ list is ordered, most interesting plies come first. The
+ ':polyglot-book-weight' ply keyword is used to store the actual
+ move weights. Use 'chess-ply-keyword' on elements of the returned
+ list to retrieve them.
+
+ -- Function: chess-polyglot-book-ply book position &optional strength
+ If non-nil a (randomly picked) ply from BOOK for POSITION. Random
+ distribution is defined by the relative weights of the found plies.
+ If non-nil, STRENGTH defines the bias towards better moves. A
+ value below 1.0 will penalize known good moves while a value above
+ 1.0 will prefer known good moves. The default is the value of
+ 'chess-polyglot-book-strength'. A strength value of 0.0 will
+ completely ignore move weights and evenly distribute the
+ probability that a move gets picked.
+
+
File: chess.info, Node: Modules, Next: Chessboard displays, Prev: The
chess.el library, Up: Top
2 Modules
@@ -1439,6 +1508,7 @@ 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-modules: ECO Classification. (line 6)
* chess-direction-east: Position coordinates. (line 37)
* chess-direction-north: Position coordinates. (line 33)
* chess-direction-northeast: Position coordinates. (line 51)
@@ -1546,6 +1616,16 @@ Function and Variable Index
* chess-ply-source: Ply details. (line 12)
* chess-ply-target: Ply details. (line 15)
* chess-ply-to-algebraic: Algebraic notation. (line 25)
+* chess-polyglot-book: Polyglot opening book format support.
+ (line 14)
+* chess-polyglot-book-file: Polyglot opening book format support.
+ (line 11)
+* chess-polyglot-book-open: Polyglot opening book format support.
+ (line 21)
+* chess-polyglot-book-plies: Polyglot opening book format support.
+ (line 26)
+* chess-polyglot-book-ply: Polyglot opening book format support.
+ (line 33)
* chess-pos-add-annotation: Annotations. (line 9)
* chess-pos-always-white: Position details. (line 93)
* chess-pos-annotations: Annotations. (line 6)
@@ -1594,65 +1674,68 @@ Key Index
Tag Table:
Node: Top437
Node: The chess.el library1190
-Node: Positions1399
-Node: Creating positions2405
-Node: Position coordinates3176
-Node: Position details5704
-Node: Annotations10157
-Node: FEN notation10499
-Node: EPD notation11996
-Node: Operations13474
-Node: Opcode "acd" analysis count depth14448
-Node: Opcode "acn" analysis count nodes14802
-Node: Opcode "acs" analysis count seconds15327
-Node: Opcode "am" avoid move(s)15847
-Node: Opcode "bm" best move(s)16288
-Node: Plies16683
-Node: Creating plies17824
-Node: Ply details19008
-Node: The "next" position19488
-Node: Algebraic notation19846
-Node: Variations21274
-Node: Creating variations22368
-Node: Variation positions22676
-Node: Varation plies23277
-Node: Making a move in a variation23718
-Node: Games24293
-Node: Creating games25867
-Node: Game tags26308
-Node: Game positions26915
-Node: Game plies27539
-Node: Making a move27808
-Node: PGN notation28235
-Node: PGN mode28969
-Node: Collections29230
-Node: Opening Databases29981
-Node: Querying Databases30365
-Node: Modifying Databases30991
-Node: Finalising Databases31263
-Node: Database Modules31438
-Node: chess-file31696
-Node: chess-scid32338
-Node: Modules32575
-Node: Chessboard displays39324
-Node: Generic display manipulation functions39935
-Node: Plain ASCII diagram displays42860
-Node: ICS1 style ASCII displays44305
-Node: Graphical displays44609
-Node: Engines44763
-Node: Common functions45265
-Node: AI46301
-Node: Crafty46772
-Node: Gnu Chess47503
-Node: Phalanx48369
-Node: Sjeng48476
-Node: Stockfish48579
-Node: Internet Chess Servers48674
-Node: Connecting to a server49580
-Node: Seeking an opponent for a new game50256
-Node: The sought game display50708
-Node: Concept Index51684
-Node: Function and Variable Index51927
-Node: Key Index63418
+Node: Positions1423
+Node: Creating positions2429
+Node: Position coordinates3200
+Node: Position details5728
+Node: Annotations10181
+Node: FEN notation10523
+Node: EPD notation12020
+Node: Operations13498
+Node: Opcode "acd" analysis count depth14472
+Node: Opcode "acn" analysis count nodes14826
+Node: Opcode "acs" analysis count seconds15351
+Node: Opcode "am" avoid move(s)15871
+Node: Opcode "bm" best move(s)16312
+Node: Plies16707
+Node: Creating plies17848
+Node: Ply details19032
+Node: The "next" position19512
+Node: Algebraic notation19870
+Node: Variations21298
+Node: Creating variations22392
+Node: Variation positions22700
+Node: Varation plies23301
+Node: Making a move in a variation23742
+Node: Games24317
+Node: Creating games25891
+Node: Game tags26332
+Node: Game positions26939
+Node: Game plies27563
+Node: Making a move27832
+Node: PGN notation28259
+Node: PGN mode28993
+Node: Collections29254
+Node: Opening Databases30033
+Node: Querying Databases30417
+Node: Modifying Databases31043
+Node: Finalising Databases31315
+Node: Database Modules31490
+Node: chess-file31748
+Node: chess-scid32390
+Node: Chess Opening Books32627
+Node: ECO Classification32946
+Node: Polyglot opening book format support33381
+Node: Modules35234
+Node: Chessboard displays41983
+Node: Generic display manipulation functions42594
+Node: Plain ASCII diagram displays45519
+Node: ICS1 style ASCII displays46964
+Node: Graphical displays47268
+Node: Engines47422
+Node: Common functions47924
+Node: AI48960
+Node: Crafty49431
+Node: Gnu Chess50162
+Node: Phalanx51028
+Node: Sjeng51135
+Node: Stockfish51238
+Node: Internet Chess Servers51333
+Node: Connecting to a server52239
+Node: Seeking an opponent for a new game52915
+Node: The sought game display53367
+Node: Concept Index54343
+Node: Function and Variable Index54586
+Node: Key Index66910
End Tag Table
diff --git a/doc/chess.texi b/doc/chess.texi
index c4b3124..3d5eb45 100644
--- a/doc/chess.texi
+++ b/doc/chess.texi
@@ -107,6 +107,7 @@ structured for use as a library, and also how to use it as
a client.
* Variations::
* Games::
* Collections::
+* Chess Opening Books::
@end menu
@node Positions, Plies, The chess.el library, The chess.el library
@@ -1028,7 +1029,7 @@ Visualize the move for the @var{pgn} game under point.
This does not require that the buffer be in @var{pgn} mode.
@end defun
-@node Collections, , Games, The chess.el library
+@node Collections, Chess Opening Books, Games, The chess.el library
@section Collections
A @dfn{collection} is a set of games archived for later perusal. A set
@@ -1139,6 +1140,68 @@ collections into one uniform concept.
This modules implement basic reading and writing functionality
for SCID (Shane's Chess Information Database) files.
+@node Chess Opening Books, , Collections, The chess.el library
+@section Chess Opening Books
+
+There are two different modules/libraries provided for looking up
+chess positions in opening books.
+
+@menu
+* ECO Classification::
+* Polyglot opening book format support::
+@end menu
+
+@node ECO Classification, Polyglot opening book format support, Chess Opening
Books, Chess Opening Books
+@subsection ECO Classification
+
+@vindex chess-default-modules
+Module @code{chess-eco} provides a database of well known names
+for chess opening positions. If this module is activated (see variable
+@code{chess-default-modules}) known chess opening positions will be announced
+in the minibuffer during a game.
+
+@node Polyglot opening book format support, , ECO Classification, Chess
Opening Books
+@subsection Polyglot opening book format support
+
+The popular and freely documented Polyglot opening book format
+is supported. There is a default polyglot book file shipped with chess.el
+to support engines which do not have built-in support for looking up positions
+in opening books (such as some UCI protocol based engines).
+
+@defvar chess-polyglot-book-file
+Path to default polyglot book file.
+@end defvar
+
+@defvar chess-polyglot-book
+If non-nil, the buffer holding the currently loaded polyglot book data.
+
+This is used by UCI based engine modules as well as the internal AI.
+@end defvar
+
+@defun chess-polyglot-book-open file
+Open a polyglot book @var{file}.
+
+Returns a buffer object which contains the binary data.
+@end defun
+
+@defun chess-polyglot-book-plies book position
+Return a list of plies found in @var{book} for @var{position}.
+The resulting list is ordered, most interesting plies come first.
+The @code{:polyglot-book-weight} ply keyword is used to store the actual move
weights.
+Use `chess-ply-keyword' on elements of the returned list to retrieve them.
+@end defun
+
+@defun chess-polyglot-book-ply book position &optional strength
+If non-nil a (randomly picked) ply from @var{book} for @var{position}.
+Random distribution is defined by the relative weights of the found plies.
+If non-nil, @var{strength} defines the bias towards better moves.
+A value below 1.0 will penalize known good moves while a value
+above 1.0 will prefer known good moves. The default is the value
+of `chess-polyglot-book-strength'.
+A strength value of 0.0 will completely ignore move weights and evenly
+distribute the probability that a move gets picked.
+@end defun
+
@node Modules, Chessboard displays, The chess.el library, Top
@chapter Modules
