X-Git-Url: http://winboard.nl/cgi-bin?a=blobdiff_plain;f=polyglot.pod;h=71fd17ca5bc9969909d7bc85be62f2ea0bd8c5b6;hb=8c255c15cc55a2e5254152c8e07a8ab45b22b7af;hp=cd4cb21f6dfe1c910b3c4049e30e92cba04bb844;hpb=e7a2abd9bd4fce9ebbd70793b00d9d5f99886348;p=polyglot.git

diff --git a/polyglot.pod b/polyglot.pod
index cd4cb21..71fd17c 100644
--- a/polyglot.pod
+++ b/polyglot.pod
@@ -2,7 +2,7 @@
 
 PolyGlot -  Winboard protocol to UCI protocol adapter
          -  book engine for Polyglot books 
-         -  a collection of utilities for creating opening books
+         -  a collection of utilities for creating and analyzing opening books
          -  a utility for analyzing epd files
          -  a perft counter
 
@@ -16,6 +16,10 @@ polyglot make-book [-pgn inputfile] [-bin outputfile] [-max-ply ply] [-min-game
 
 polyglot merge-book -in1 inputfile1 -in2 inputfile2 [-out outputfile]
 
+polyglot info-book [-bin inputfile] [-exact]
+
+polyglot dumb-book [-bin inputfile] -color color [-out outputfile]
+
 polyglot [configfile] epd-test [-epd inputfile] [-min-depth depth] [-max-depth depth] [-max-time time] [-depth-delta delta] 
 
 polyglot perft [-fen fen] [-max-depth depth]
@@ -72,7 +76,33 @@ Other opening book formats such as ChessBase's .ctg format and Arena's
 by their own GUIs. 
 
 PolyGlot can compile a pgn file into a binary PolyGlot book and furthermore
-it can merge two such binary books into a third one. 
+it can merge two such binary books into a third one.
+
+PolyGlot can also extract some useful information from PolyGlot books. The utility
+"dump-book" dumps the "lines" in a book for a given color. By definition
+a line is a sequence of moves (from the starting position) in which
+the given color makes only book moves and the other color makes 
+arbitrary moves (i.e. not necessarily book moves).
+
+Since a PolyGlot book is built up from positions and not lines there
+may be (and there usually are) many positions in the book that are not
+on a "line" as defined in the previous paragraph. It is convenient
+to call such positions "isolated" positions. The utility "info-book"
+counts such isolated positions.
+
+Some of the isolated positions are provably unreachable and they
+could in principle be deleted from the book. For example if a book
+contains only the move "e4" in the starting position but also the
+position after "d4 d5" then this last position is provably unreachable
+since it requires white to make a non-book move when a book move is
+available. Such situations arise frequently from the priority rules
+in merging books.
+
+Unfortunately not all isolated positions are provably unreachable and
+it is difficult to identify the latter. If invoked with "-exact" the
+utility info-book will attempt to count the isolated positions which
+require a player to make a non-book move when a book move is available.
+Due to the possibility of transpositions this is not a fool proof method.
 
 =head2 Epd test mode
 
@@ -172,6 +202,49 @@ Input files are not symmetrical, "in1" has priority over "in2". In other
 words when a position occurs both in "in1" and "in2" only the
 moves and weights from "in1" will be retained in "out".
 
+When invoked
+as
+
+=head2 polyglot dump-book
+
+PolyGlot supports the following options
+
+=over 4
+
+=item B<-bin> (default: book.bin)
+
+Input file in PolyGlot book format.
+
+=item B<-color> 
+
+The color for whom to generate the lines.
+
+=item B<-out> (default: book_<color>.txt)
+
+The name of the output file.
+
+=back
+
+When invoked
+as
+
+=head2 polyglot info-book
+
+PolyGlot supports the following options
+
+=over 4
+
+=item B<-bin> (default: book.bin)
+
+Input file in PolyGlot book format.
+
+=item B<-exact> 
+
+Attempt to count the provably unreachable positions among the isolated ones.
+Note that this takes a very long time. 
+
+=back
+
 When invoked as
 
 =head2 polyglot epd-test
@@ -192,8 +265,9 @@ Unconditionally stop the seach after this amount of time.
 
 =item B<-depth-delta> (default: 3)
 
-Stop the search if the best move has been constant for this many depths,
-on condition that the mininal depth and minimal time have been reached.
+Stop the search if the solution as been found and the best move has
+been constant for this many depths, on condition that the mininal
+depth and minimal time have been reached.
 
 =item B<-min-depth> (default: 8)
 
@@ -238,7 +312,7 @@ The config file is in the traditional INI format.
     option = value
     ...
 
-Lines starting with "#" are ignored.
+The characters "#" and ";" serve as comment characters. 
 
 NOTE: There can be spaces in option names or values.  Do not use
 quotes. Boolean values are written as "true" or "false". 
@@ -472,12 +546,24 @@ most 30 plies.
 
     polyglot make-book -pgn games.pgn -bin book.bin -max-ply 30
 
-Merge books "in1.bin" and "in2.bin" into a book "out.bin".
+Merge books "w1.bin" and "w2.bin" into a book "w.bin".
 
     polyglot merge-book -in1 w1.bin -in2 w2.bin -out w.bin
 
+Inspect lines for white in "w.bin"
+
+    polyglot dump-book -bin w.bin -color white -out w_white.txt
+
+Test epd file "test.epd" with a (maximum) search time of 7 minutes per position
+
+    polyglot epd-test -epd test.epd -max-time 420
+
+The command line for using the UCI engine "fruit" in a GUI which uses the
+xboard protocol.
+
+    polyglot -ec fruit
 
-Here is a minimal config file
+The equivalent config file:
 
     [PolyGlot]
     EngineCommand = fruit