[elpa] 01/01: Work on the manual.

[Mario Lang]

mlang pushed a commit to branch externals/chess
in repository elpa.

commit aeb61ff63801e85ac5e3cbc621fbaf763d9c297f
Author: Mario Lang <address@hidden>
Date:   Thu Jun 12 05:21:48 2014 +0200

    Work on the manual.
---
 chess.info     |  150 ++++++++++++++++++++++++++++++++------------------------
 doc/chess.texi |   51 ++++++++++---------
 2 files changed, 112 insertions(+), 89 deletions(-)

diff --git a/chess.info b/chess.info
index f5b462e..57be241 100644
--- a/chess.info
+++ b/chess.info
@@ -552,11 +552,30 @@ File: chess.info,  Node: Ply details,  Next: The "next" 
position,  Prev: Creatin
  -- Function: chess-ply-set-pos ply position
      Set the base position of PLY.
 
+ -- Function: chess-ply-changes
+     Return the coordinate transformations and keywords associated with
+     this PLY.
+
+     A list of a pair of indices (or two, in case of castling) followed
+     by optional keywords.
+
+ -- Function: chess-ply-set-changes
+     Set the coordinate transformations and keywords associated with
+     this PLY.
+
  -- Function: chess-ply-source ply
-     Returns the source square index value of PLY.
+     Return the source square index value of PLY.
 
  -- Function: chess-ply-target ply
-     Returns the target square index value of PLY.
+     Return the target square index value of PLY.
+
+   For example, here is how to find the source square of a freshly
+created ply:
+
+     (chess-ply-source (chess-ply-create chess-starting-position nil
+                                         (chess-coord-to-index "e2")
+                                         (chess-coord-to-index "e4")))
+     ⇒ 52
 
 
 File: chess.info,  Node: The "next" position,  Next: Algebraic notation,  
Prev: Ply details,  Up: Plies
@@ -2048,6 +2067,7 @@ Concept Index
 
 * algebraic notation, entering moves with: Entering moves with algebraic 
notation.
                                                                (line  6)
+* algebraic notation, searching moves:   Basic operations.     (line 13)
 * bishop:                                Position coordinates. (line 49)
 * Chess ICS mode:                        Chess ICS Mode.       (line  6)
 * Comint mode:                           Chess ICS Mode.       (line 79)
@@ -2228,13 +2248,15 @@ Function and Variable Index
                                                               (line  26)
 * chess-plain-white-square-char:         Plain ASCII diagram displays.
                                                               (line  20)
+* chess-ply-changes:                     Ply details.         (line  12)
 * chess-ply-create:                      Creating plies.      (line   6)
 * chess-ply-final-p:                     The "next" position. (line   9)
 * chess-ply-next-pos:                    The "next" position. (line   6)
 * chess-ply-pos:                         Ply details.         (line   6)
+* chess-ply-set-changes:                 Ply details.         (line  19)
 * chess-ply-set-pos:                     Ply details.         (line   9)
-* chess-ply-source:                      Ply details.         (line  12)
-* chess-ply-target:                      Ply details.         (line  15)
+* chess-ply-source:                      Ply details.         (line  23)
+* chess-ply-target:                      Ply details.         (line  26)
 * chess-ply-to-algebraic:                Algebraic notation.  (line  22)
 * chess-polyglot-book:                   Polyglot opening book format support.
                                                               (line  14)
@@ -2440,66 +2462,66 @@ Node: Opcode "bm" best move(s)17655
 Node: Plies18050
 Node: Creating plies19193
 Node: Ply details20376
-Node: The "next" position20856
-Node: Algebraic notation21214
-Node: Variations22753
-Node: Creating variations23852
-Node: Variation positions24160
-Node: Variation plies24766
-Node: Making a move in a variation25212
-Node: Games25765
-Node: Creating games27347
-Node: Game tags27792
-Node: Game positions28401
-Node: Game plies29035
-Node: Making a move29304
-Node: PGN notation29735
-Node: PGN mode30469
-Node: Collections30730
-Node: Opening Databases31509
-Node: Querying Databases31897
-Node: Modifying Databases32523
-Node: Finalising Databases32795
-Node: Database Modules32970
-Node: chess-file33228
-Node: chess-scid33878
-Node: Chess Opening Books34117
-Node: ECO Classification34436
-Node: Polyglot opening book format support34879
-Node: Modules36744
-Node: Chessboard displays43520
-Node: Generic display manipulation functions44154
-Node: Chess display mode46985
-Node: Basic operations47791
-Node: Selecting pieces with the keyboard49407
-Node: Selecting pieces with the mouse49999
-Node: Entering moves with algebraic notation50565
-Node: Plain ASCII diagram displays51583
-Node: ICS1 style ASCII displays53022
-Node: Graphical displays53329
-Node: Engines53963
-Node: Common functions54479
-Node: AI55527
-Node: Crafty56506
-Node: Fruit57293
-Node: Glaurung58189
-Node: GNU Chess58829
-Node: Phalanx59712
-Node: Sjeng60344
-Node: Stockfish61083
-Node: Chess Session61898
-Node: Internet Chess Servers63137
-Node: Connecting to a server64294
-Node: Chess ICS Mode64850
-Node: Command History68363
-Node: ICS Command Ring68984
-Node: ICS History Copying72197
-Node: Seeking an opponent for a new game73715
-Node: The sought game display74364
-Node: Watching other games75392
-Node: Concept Index76874
-Node: Function and Variable Index78660
-Node: Key Index95539
+Node: The "next" position21498
+Node: Algebraic notation21856
+Node: Variations23395
+Node: Creating variations24494
+Node: Variation positions24802
+Node: Variation plies25408
+Node: Making a move in a variation25854
+Node: Games26407
+Node: Creating games27989
+Node: Game tags28434
+Node: Game positions29043
+Node: Game plies29677
+Node: Making a move29946
+Node: PGN notation30377
+Node: PGN mode31111
+Node: Collections31372
+Node: Opening Databases32151
+Node: Querying Databases32539
+Node: Modifying Databases33165
+Node: Finalising Databases33437
+Node: Database Modules33612
+Node: chess-file33870
+Node: chess-scid34520
+Node: Chess Opening Books34759
+Node: ECO Classification35078
+Node: Polyglot opening book format support35521
+Node: Modules37386
+Node: Chessboard displays44162
+Node: Generic display manipulation functions44796
+Node: Chess display mode47627
+Node: Basic operations48433
+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 displays53664
+Node: Graphical displays53971
+Node: Engines54605
+Node: Common functions55121
+Node: AI56169
+Node: Crafty57148
+Node: Fruit57935
+Node: Glaurung58831
+Node: GNU Chess59471
+Node: Phalanx60354
+Node: Sjeng60986
+Node: Stockfish61725
+Node: Chess Session62540
+Node: Internet Chess Servers63779
+Node: Connecting to a server64936
+Node: Chess ICS Mode65492
+Node: Command History69005
+Node: ICS Command Ring69626
+Node: ICS History Copying72839
+Node: Seeking an opponent for a new game74357
+Node: The sought game display75006
+Node: Watching other games76034
+Node: Concept Index77516
+Node: Function and Variable Index79375
+Node: Key Index96400
 
 End Tag Table
 
diff --git a/doc/chess.texi b/doc/chess.texi
index 7a0a084..7b508d0 100644
--- a/doc/chess.texi
+++ b/doc/chess.texi
@@ -560,17 +560,17 @@ 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
+A ply may be represented in @acronym{ASCII} by printing the @acronym{FEN} 
string
+of the base position, and then printing the positional transformation in 
algebraic
+notation.  Since the starting position is usually known, the @acronym{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.,
+Plies may be sent over network connections, postal mail, e-mail, @abbr{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
+Transmitting the base position's @acronym{FEN} string along with the ply 
offers a
 form of confirmation during the course of a game.
 
 @menu
@@ -583,8 +583,6 @@ form of confirmation during the course of a game.
 @node Creating plies, Ply details, Plies, Plies
 @subsection Creating plies
 
address@hidden lispfun chess-ply-create
-
 @defun chess-ply-create position &optional valid-p &rest changes
 Create a ply from the given @var{position} by applying the supplied 
@var{changes}.
 This function will guarantee the resulting ply is legal, and will also
@@ -595,8 +593,6 @@ Note: Do not pass in the rook move if @var{changes} 
represents a castling
 maneuver.
 @end defun
 
address@hidden lispfun chess-legal-plies
-
 @defun chess-legal-plies position &rest keywords
 Return a list of all legal plies in @var{position}.
 @var{keywords} allowed are:
@@ -612,52 +608,56 @@ Return a list of all legal plies in @var{position}.
 These will constrain the plies generated to those matching the above
 criteria.
 
address@hidden: All of the returned plies will reference the same copy of the
+NOTE: All of the returned plies will reference the same copy of the
 position object passed in.
 @end defun
 
 @node Ply details, The "next" position, Creating plies, Plies
 @subsection Ply details
 
address@hidden lispfun chess-ply-pos
-
 @defun chess-ply-pos ply
 Returns the base position associated with @var{ply}.
 @end defun
 
address@hidden lispfun chess-ply-set-pos
-
 @defun chess-ply-set-pos ply position
 Set the base position of @var{ply}.
 @end defun
 
address@hidden lispfun chess-ply-changes
address@hidden chess-ply-changes
+Return the coordinate transformations and keywords associated with this 
@var{ply}.
 
address@hidden lispfun chess-ply-set-changes
+A list of a pair of indices (or two, in case of castling) followed by
+optional keywords.
address@hidden defun
 
address@hidden lispfun chess-ply-source
address@hidden chess-ply-set-changes
+Set the coordinate transformations and keywords associated with this @var{ply}.
address@hidden defun
 
 @defun chess-ply-source ply
-Returns the source square index value of @var{ply}.
+Return the source square index value of @var{ply}.
 @end defun
 
address@hidden lispfun chess-ply-target
-
 @defun chess-ply-target ply
-Returns the target square index value of @var{ply}.
+Return the target square index value of @var{ply}.
 @end defun
 
+For example, here is how to find the source square of a freshly created ply:
+
address@hidden
+(chess-ply-source (chess-ply-create chess-starting-position nil
+                                    (chess-coord-to-index "e2")
+                                    (chess-coord-to-index "e4")))
address@hidden 52
address@hidden lisp
+
 @node The "next" position, Algebraic notation, Ply details, Plies
 @subsection The "next" position
 
address@hidden lispfun chess-ply-next-pos
-
 @defun chess-ply-next-pos ply
 Return the position that results from executing @var{ply}.
 @end defun
 
address@hidden lispfun chess-ply-final-p
-
 @defun chess-ply-final-p ply
 Return non-nil if this is the last ply of a game/variation.
 @end defun
@@ -1482,6 +1482,7 @@ Invert the perspective of the current chess board.
 @findex chess-display-move-backward
 Show the previous move in the current game.
 
address@hidden algebraic notation, searching moves
 @kindex C-r
 @item C-r
 @findex chess-display-search-backward