GENERAL CONCEPTS
----------------

Leila book is built from a text file where each book line is specified
move by move in long algebraic notation or SAN (eg. e4, e2e4, Ng1f3,
Nf3, bxc4+ are all valid inputs).
It is intended to be a (small) "starting" book which is read to memory
at startup, and not a large book kept on disk and automatically built
from a collection of PGN files. A large "disk" book is not implemented
yet, but will be added in the following versions, probably using almost
the same book routines.

Since the book is currently read to memory, there are some limitations
in size: it cannot contain more than 100K unique positions, and cannot
be specified more than 20 different book moves in every single book
position.

Before it can be used, the text book must be compiled and saved to disk
in a binary format using the BUILDSB command (see below); the generated
binary book must then be loaded to memory using the READBOOK command.

In the text file, the moves of each book line must be entered one after
another separated by spaces and without move numbers; the lines must be
separated by a newline.
The only significant characters are 'a'..'h', '1'..'8', '?', '!', space
(used to separate moves) and newline (used to separate book lines). '#'
and '@' signs the beginning of a comment (cause the program to skip all
subsequent chars till the next newline).
All other characters are simply ignored.


Some miscellaneaus comments:

- In the text book you can freely mix SAN with long algebraic notation;
  but of course this behaviour is discouraged because it penalizes
  readability.

- The order of the lines in the book has no influence at all; but of
  course keeping some kind of order is greatly recommended to improve
  readability. Adding some comments, like opening names or so, is
  encouraged too.

- Leila book fully supports transpositions now, so there is no need
  to add (like in the previous versions) many lines leading to the same
  position.

- Currently there is no way to control Leila's probability to play a
  certain opening; you can only use nags ('!' and '?', see below) to
  specify if a certain move has to be played ('!') or avoided ('?').
  This will probably change in the following versions.

- Sample of valid book lines (with a few comments):

      # King openings

      e2e4! e7e5! Nc3
      e2e4! e7e5! g1f3! b8c6! c2c3!
      e2e4! e5!   Nf3!  b8c6! Bb5!  a6 b5a4! g8f6 OO! Be7 Re1! b5

      # Queen Openings

      d2d4! d7d5! c4!   dxc4?    # Never accept Queen's Gambit!
      d2d4! g8f6  c2c4!

      # Other Openings

      e3    e5!
      g1f3  d7d5! c2c3  c8f5!




USING NAGS
-----------

Each move in the book lines can be flagged by "nags". Currently, just
two nags are recognized; but this will probably change in the future,
in order to provide the user with better way to control over Leila's
opening play.

The '?' nag specifies a BAD MOVE, i.e. a move that Leila should never
play in the given book position; while the '!' nag specifies a STRONG
MOVE, i.e. a move which Leila should play in the given book position.

Of course in any book position there could be various moves flagged by
different nags; and (due to user mistakes) there could be moves which
in the same position are flagged with the '?' nag in certain lines, and
with the '!' nag in other lines. In these cases, Leila chooses the move
to play according to the following policy:

  - If in the current position book moves with the '!' flag are found,
    the move to play will be randomly chosen among them;

  - If no moves are found flagged with '!', and some moves are found
    with no flags at all, one of those moves will be randomly chosen
    and played.
    
  - If in the current position book moves with the '?' flag are found,
    these moves will *NOT* be played, unless the program is unable to
    find another move which does not lose too much material. 
    
  - If a move is flagged with a nag in a certain line, it is ininfluent
    to flag it in other lines too. In other words, if there is a book
    line starting with:

    e2e4! e7e5! g1f3! b8c6  ( ... )

    and you would like to add a line where after 1. e4 e5 2. Nf3 Black
    plays 2. Nf6, in is not strictly necessary to add the '!' nag to
    the first three moves, since nags can be found in the above line.

    So in this case adding:
    
    e2e4  e7e5  g1f3  g8f6  ( ... )
    
    is exactly the same as adding:

    e2e4! e7e5! g1f3! g8f6  ( ... )
    

  - If a move is flagged with '!' in certain lines, and with '?' in
    others, the '!' is ignored and only the '?' is considered valid.
    Example:

    e2e4! e7e5! g1f3! g8f6! ( ... )
    e2e4! e7e5! g1f3  g8f6? ( ... )
    
    The '!' nag of g8f6 in the first line is ignored, and the move
    is flagged by '?' based on the second line. This should never
    happen anyway ;-) 
    

Summarizing, Leila book algorithm is the following:

  - Look in the book for the current position; if it is not found,
    start the normal search;
  
  - If found, check for STRONG moves (moves marked with '!'): if some
    are found, randomly play one of them;
    
  - If none is found, look for NORMAL moves (moves not marked with
    either '?' or '!' nags): if some are found, randomly play one of
    them;
  
  - If none are found, start the normal search but penalize the WEAK
    book moves (moves marked with '?') so that they will not be played
    (unless no reasonable alternative is found).



A FEW NOTES ABOUT TRANSPOSITIONS
--------------------------------

As stated above, Leila correctly handles book transpositions. Anyway
it must be noted that if the current search position is in the book,
Leila will only chose between moves that are explicitly listed in the
book lines which contain the search position, and will NOT play other
moves, even if they would lead to other book lines by transposition.

This could seem obvious, but let's clarify. Let's suppose we have the
following book:

e4 e5 Nf3 Nc6 Bb5         # line 1
e4 e5 Nf3 Nc6 Be2         # line 2
e4 e5 Bb5 Nc6 f3          # line 3

In this case, after 1. e4 e5 2. Bb5 Nc6, Leila will obviously play
3. f3 and NOT 3. Nf3, although 3. Nf3 would lead to a transposition
into line 1. This way the user has a much better control on Leila
openings play; and a few nasty problems can be avoided.

On the other hand, if the current search position in NOT a known book
position, but there are moves available which would transpose back into
the book, Leila will keep searching normally and WILL NOT blindly chose
one of these moves. That allows Leila to search for possibly better
moves than the transposing ones, and avoids strange behaviours like the
following, well known problems:

- 1. e4 e5 2. Nf3 Nc6 3. Ng1 and now the engine obviously plays
  3. ... Ng8 transposing back into book
  
Or, even worse:

- 1. e4 e5 2. Bb5 a6 3. Nf3 and, instead of taking the Bishop for free,
  the engine happily plays 3. ... Nc6




BOOK COMMANDS
-------------

Currently Leila implements three commands for book handling: BUILDSB
(builds a binary book from the supplied text file), READBOOK (reads a
compiled binary book in memory), and BOOK (displays the available book
moves in the current position).


BUILDSB <in_file> <out_file> <max_moves> <max_positions>

  Pourpose:

  Builds a binary book from a book file in text format, and saves it
  to disk with the specified file name.

  Parameters:

  - in_file:    Name of the input text file       (default: book.txt)
  - out_file:   Name of the binary file to create (default: book.dat)
  - max_moves:  Max number of book moves in each unique book position
                (used to allocate memory structures for building the
                book: default is 20, maximum is 20. Never needed to
                change this value).
  - max_pos:    Max number of unique book positions (used to allocate
                memory structures: default is 35K, maximum is 100K.
                Increase it if building very large books; never mind
                to overestimate this number, since it is needed only
                by the building process, while when reading the book
                for using it the proper size will be automatically
                used).

  Examples:
  
  buildsb start.txt book.dat 20 50000
  
  
  Notes:
  
  During the build process (which is quite slow and takes some time,
  I must say) the program displays working-in-progress statistics,
  and at the end it gives a summary. Any error (invalid book lines,
  or insufficient storage space allocated) is reported along with
  simple suggestions to help solving the problem.

  IMPORTANT: After the building process is completed, the book needs
             to be read in memory with the READBOOK command before it
             will effectively be used.
             
             

READBOOK <filename>

  Pourpose:

  Reads in memory a binary book, previously built using the BUILDSB
  command. The file name must be obviously the same specified as the
  out_file parameter of the BUILDSB command, and defaults to BOOK.DAT.
  
  Notes:
  
  At startup, Leila automatically tries to load the BOOK.DAT file,
  which is the default book supplied with the executable and should be
  always located in Leila startup directory.
  If the book is not found or the format is invalid, Leila reports an
  error but continues to work: anyway the error reported in the init
  phase could lead to problems under Winboard, so it is highly
  recommended to never remove the BOOK.DAT file from Leila directory.
  
  After READBOOK is successfully executed, Leila will use the loaded
  book until a new READBOOK command is issued. 



BOOK

  Pourpose:
  
  Displays the book moves available in the current position, along
  with their nags.
  
  