[gnugo-devel] minor doc revisions

[Arend Bayer]

Various minor doc revisions. I think the worst chapter currently is
the overview chapter, would be nice to have this reworked for 3.4.

Arend


Index: doc/influence.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/influence.texi,v
retrieving revision 1.13
diff -u -p -r1.13 influence.texi
--- doc/influence.texi  12 Jan 2003 20:44:43 -0000      1.13
+++ doc/influence.texi  3 Jun 2003 11:27:15 -0000
@@ -24,10 +24,9 @@ We define call stones @dfn{lively} if th
 attacked, or if they have a tactical defense and belong to the player
 whose turn it is. Similarly, stones that cannot be strategically attacked
 (in the sense of the life-and-death analysis), or that have a strategical
-defense and belong to the player to move, are called @dfn{alive} while all
-other stones are called @dfn{alive}. If we want to use the influence
-function before deciding the strategical status, all lively stones count
-as alive.
+defense and belong to the player to move, are called @dfn{alive}.
+If we want to use the influence function before deciding the strategical
+status, all lively stones count as alive.

 Every alive stone on the board works as an influence source, with
 influence of its color radiating outwards in all directions. The
@@ -42,26 +41,17 @@ stones can be captured. Notice that it d
 connection between the two stones can be broken, since in that case
 there would come influence from both directions anyway.

-We define @dfn{territory} to be the intersections where one color has no
-influence at all and the other player does have. We can introduce moyo
-and area concepts similar to those provided by the Bouzy algorithms in
-terms of the influence values for the two colors. ``Territory'' refers
-to certain or probable territory while ``Moyo'' refers to an area of
-dominant influence which is not necessarily guaranteed territory.
-``Area'' refers to the breathing space around a group in which it
-can manoever if it is attacked.
+From the influence of both colors we compute a territorial value between
+-1.0 and +1.0 for each intersection, which can be seen as the likely hood
+of it becoming territory for either color.

 In order to avoid finding bogus territory, we add extra influence
 sources at places where an invasion can be launched, e.g. at 3-3 under
 a handicap stone, in the middle of wide edge extensions and in the
 center of large open spaces anywhere. Similarly we add extra influence
 sources where intrusions can be made into what otherwise looks as
-solid territory, e.g. monkey jumps.
-
-Walls typically radiate an influence that is stronger than the sum of
-the influence from the stones building the wall. To accommodate for this
-phenomenon, we also add extra influence sources in empty space at
-certain distances away from walls.
+solid territory, e.g. monkey jumps. These intrusions depend on whose
+turn we assume it to be.

 All these extra influence sources, as well as connections, are controlled
 by a pattern database, which consists of the two files patterns/influence.db
@@ -90,8 +80,8 @@ done by the owl code (see @ref{Pattern B
 moyo size of only 5 will be considered weak, even if the owl code has
 decided that it cannot be killed.

-As a tool for the owl code, an "escape" influence gets computed for each
-dragon going through the life-and-death analysis (@ref{Escape}).
+As a tool for both the owl code and the strength estimate of dragons,
+an "escape" influence gets computed for each dragon @xref{Escape}.

 Once all dragons have been evaluated, the influence module is called again
 and the variables @code{initial_influence} and
@@ -104,7 +94,7 @@ dragon.
 The result of this run is the most important tool for move evaluation. All
 helper functions of patterns as explained in @ref{Patterns} that
 refer to influence results (e. g. @code{olib(*)} etc.) actually use these
-results. More important, @code{initial_influence} serves as the reference for
+results. Further, @code{initial_influence} serves as the reference for
 computing the territorial value of a move. That is, from the influence
 strengths stored in @code{initial_influence}, a territory value is
 assigned to each intersection. This value is supposed to estimate the
Index: doc/owl.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/owl.texi,v
retrieving revision 1.8
diff -u -p -r1.8 owl.texi
--- doc/owl.texi        26 Dec 2002 04:33:48 -0000      1.8
+++ doc/owl.texi        3 Jun 2003 11:27:16 -0000
@@ -88,9 +88,9 @@ principally the first two.
 @findex owl_defend
 @findex compute_eyes_pessimistic
 A node of the move tree is considered @code{terminal} if no further moves
-are found from @file{apats.db} or @file{dpats.db}, or if the function
address@hidden()} reports that the group is definitely
-alive or dead. At this point, the status of the group is evaluated.
+are found from @file{owl_attackpats.db} or @file{owl_defendpats.db}, or if
+the function @code{compute_eyes_pessimistic()} reports that the group is
+definitely alive. At this point, the status of the group is evaluated.
 The functions @code{owl_attack()} and @code{owl_defend()}, with
 usage similar to @code{attack()} and @code{find_defense()}, make
 use of the owl pattern databases to generate the move tree and decide
@@ -146,11 +146,11 @@ Only dragons with small escape route are
 functions are called from @code{make_dragons()}.

 The owl code can be conveniently tested using the
address@hidden @var{location}} This should be used with
address@hidden @var{location}} This should be used with
 @option{-t} to produce a useful trace, @option{-o} to produce
 an SGF file of variations produced when the life and death of
 the dragon at @var{location} is checked, or both.
address@hidden performs the same analysis for all
address@hidden performs the same analysis for all
 dragons with small escape route.

 @node Owl Functions, Combinations, The Owl Code, Pattern Based Reading
Index: doc/reading.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/reading.texi,v
retrieving revision 1.10
diff -u -p -r1.10 reading.texi
--- doc/reading.texi    24 Feb 2003 03:25:39 -0000      1.10
+++ doc/reading.texi    3 Jun 2003 11:27:17 -0000
@@ -12,8 +12,8 @@ opponent to learn the result of differen
 "reading". GNU Go does three distinct types of reading: @dfn{tactical
 reading} which typically is concerned with the life and death of
 individual strings, @dfn{Owl reading} which is concerned
-with the life and death of dragons, and @dfn{life reading}
-which attempts evaluate eye spaces. In this Chapter, we document
+with the life and death of dragons, and @dfn{connection reading}.
+In this Chapter, we document
 the tactical reading code, which is in @file{engine/reading.c}.
 For a summary of the reading functions see @xref{Reading Functions}.

@@ -34,9 +34,23 @@ For a summary of the reading functions s
 @comment  node-name,  next,  previous,  up
 @section Reading Basics

-In GNU Go, tactical reading is done by the functions in
address@hidden/reading.c}. Each of these functions has a separate goal to fill,
-and they call each other recursively to carry out the reading process.
+What we call @emph{Tactical Reading} is the analysis whether there is
+a direct capture of a single string, or whether there is a move to prevent
+such a direct capture.
+
+If the reading module finds out that the string can get captured, this
+answer should (usually) be trusted. However, if it says it can be defended,
+this does not say as much. It is often the case that such a string has
+no chance to make a life, but that it cannot be captured within the
+horizon (and the cutoff heuristics) of the tactical reading.
+
+The tactical reading is done by the functions in @file{engine/reading.c}.
+It is a minimax search that declares win for the attacker once he can
+physically take the string off board, whereas the defense is considered
+successful when the string has sufficiently many liberties. A string with
+five liberties is always considered alive. At higher depth within the
+search tree even fewer liberties cause GNU Go to give up the attack,
address@hidden

 The reading code makes use of a stack onto which board positions can
 be pushed. The parameter @code{stackp} is zero if GNU Go is
@@ -50,21 +64,29 @@ The most important public reading functi
 functions @code{do_attack} and @code{do_find_defense} call each other
 recursively.

address@hidden Organization of the reading code
+
+The function @code{do_attack} and @code{do_find_defense} are wrappers
+themselves and call @code{attack1}, @code{attack2}, @code{attack3} or
address@hidden resp.  @code{defend1}, @code{defend1}, @code{defend1}
+or @code{defend1} depending on the number of liberties.
+
+These are fine-tuned to generate and try out the moves in an efficient
+order. They generate a few moves themselves (mostly direct liberties
+of the string), and then call helper functions called @code{..._moves}
+which suggest less obvious moves. Which of these functions get called
+depends on the number of liberties and of the current search depth.
+
address@hidden Return codes
address@hidden
 @cindex return codes
 @cindex reading return codes

 The return codes of the reading (and owl) functions and owl can
-be 0, 1, 2 or 3. Each reading function determines whether a
-particular player (assumed to have the move) can solve a
-specific problem, typically attacking or defending a string.
-
-The nonzero return codes are called these names in the source:
-
address@hidden
-   #define WIN  3
-   #define KO_A 2
-   #define KO_B 1
address@hidden example
+be @code{0}, @code{KO_B}, @code{KO_A} or @code{WIN}. Each reading
+function determines whether a particular player (assumed to have the
+move) can solve a specific problem, typically attacking or defending
+a string.

 A return code of @code{WIN} means success, 0 failure, while @code{KO_A} and
 @code{KO_B} are success conditioned on ko. A function returns @code{KO_A}
@@ -73,13 +95,9 @@ will get the first ko capture (so the op
 first ko threat). A return code of @code{KO_B} means that the player
 to move will have to make the first ko threat.

-Many of the reading functions make use of @dfn{null pointers}.
-For example, a call to @code{attack(str, &apos)} will return @code{WIN}
-if the string at @code{str} can be captured. The point of attack
-(in case it is vulnerable) is returned in @code{apos}. However
-many times we do not care about the point of attack. In this
-case, we can substitute a null pointer: @code{attack(str,
-NULL)}.
+
address@hidden Reading cutoff and depth parameters
address@hidden

 Depth of reading is controlled by the parameters @code{depth}
 and @code{branch_depth}. The @code{depth} has a default value
@@ -99,14 +117,14 @@ Between @code{branch_depth} and @code{de
 3 liberties are considered, but branching is inhibited, so fewer
 variations are considered.

address@hidden small_semeai
-Currently the reading code does not try to defend a string by
-attacking a boundary string with more than two liberties. Because
-of this restriction, it can make oversights. A symptom of this is
-two adjacent strings, each having three or four liberties, each
-classified as @code{DEAD}. To resolve such situations, a function
address@hidden()} (in @file{engine/semeai.c}) looks for such
-pairs of strings and corrects their classification.
address@hidden small_semeai
+%Currently the reading code does not try to defend a string by
+%attacking a boundary string with more than two liberties. Because
+%of this restriction, it can make oversights. A symptom of this is
+%two adjacent strings, each having three or four liberties, each
+%classified as @code{DEAD}. To resolve such situations, a function
address@hidden()} (in @file{engine/semeai.c}) looks for such
+%pairs of strings and corrects their classification.

 The @code{backfill_depth} is a similar variable with a default 12. Below
 this depth, GNU Go will try "backfilling" to capture stones.
@@ -148,28 +166,23 @@ Functions} for a fuller list).
 @item @code{int attack(int str, int *move)}
 @findex attack
 @quotation
-This basic function determines if the string at @code{str} can
+Determines if the string at @code{str} can
 be attacked, and if so, @code{*move} returns the attacking move,
 unless @code{*movei} is a null pointer. (Use null pointers if
 you are interested in the result of the attack but not the
-attacking move itself.) Returns 1 if the attack succeeds,
-otherwise 0. Returns @code{KO_A} or @code{KO_B} if the result depends on ko:
-returns @code{KO_A} if the attack succeeds provided attacker is willing
-to ignore any ko threat. Returns @code{KO_B} if attack succeeds
-provided attacker has a ko threat which must be answered.
+attacking move itself.) Returns @code{WIN}, if the attack succeeds,
+0 if it fails, and @code{KO_A} or @code{KO_B} if the result depends on ko
address@hidden
 @end quotation
 @findex find_defense
 @item @code{find_defense(int str, int *move)}
 @quotation
 Attempts to find a move that will save the string at @code{str}. It
 returns true if such a move is found, with @code{*move} the location
-of the saving move (unless @code{*move} are null pointers). It is not
+of the saving move (unless @code{*move} is a null pointer). It is not
 checked that tenuki defends, so this may give an erroneous answer if
 @code{!attack(str)}.  Returns @code{KO_A} or @code{KO_B} if the
-result depends on ko. Returns @code{KO_A} if the string can be
-defended provided @code{color} is willing to ignore any ko
-threat. Returns @code{KO_B} if @code{color} has a ko threat which must be
-answered.
+result depends on ko @xref{retcodes}.
 @end quotation
 @findex safe_move
 @item @code{safe_move(int str, int color)} :