[gnugo-devel] doc patch

[Gunnar Farneback]

This patch corrects a number of errors (mostly @code improperly used
instead of @file) in several of the doc files and heavily revises
eyes.texi, including a new section about Eye Topology with Ko. As a
unique exception to the rule, this makes the doc better updated than
the code itself. :-) This is expected to return to normal once I
finish my code changes in optics.c.

- doc revisions

/Gunnar

Index: doc/board.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/board.texi,v
retrieving revision 1.3
diff -u -r1.3 board.texi
--- doc/board.texi      2001/09/06 21:34:19     1.3
+++ doc/board.texi      2001/11/28 16:19:44
@@ -481,7 +481,7 @@
 
 Hashing of go positions in a hash table (sometimes also called a
 transposition table) is implemented in @code{libboard}, in @file{hash.c}
-and @code{cache.c} to be exact.  
+and @file{cache.c} to be exact.  
 
 To use the hash function, you must include @file{hash.h} and to use the
 entire hash table, you must include @file{cache.h} in your program.  The
Index: doc/dfa.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/dfa.texi,v
retrieving revision 1.3
diff -u -r1.3 dfa.texi
--- doc/dfa.texi        2001/09/06 21:34:19     1.3
+++ doc/dfa.texi        2001/11/28 16:19:44
@@ -241,7 +241,7 @@
 To each state we associate an often empty
 list of attributes which is the  
 list of pattern indexes recognized when this state is reached.
-In '@code{dfa.h}' this is basically represented by two stuctures:
+In '@file{dfa.h}' this is basically represented by two stuctures:
 
 @example
 @group
@@ -273,7 +273,7 @@
 
 Recognizing with a DFA is very simple
 and thus very fast 
-(See '@code{scan_for_pattern()}' in the '@code{engine/matchpat.c}' file).
+(See '@code{scan_for_pattern()}' in the '@file{engine/matchpat.c}' file).
 
 
 Starting from the start state, we only need to read the board
Index: doc/dragon.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/dragon.texi,v
retrieving revision 1.3
diff -u -r1.3 dragon.texi
--- doc/dragon.texi     2001/09/06 21:34:19     1.3
+++ doc/dragon.texi     2001/11/28 16:19:45
@@ -549,7 +549,7 @@
 
 The fields @code{black_eye.cut} and @code{white_eye.cut} are set where the
 opponent can cut, and this is done by the B (break) class patterns in
address@hidden  There are two important uses for this field, which can be
address@hidden  There are two important uses for this field, which can be
 accessed by the autohelper functions @code{xcut()} and @code{ocut()}. The
 first use is to stop amalgamation in positions like
 
Index: doc/eyes.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/eyes.texi,v
retrieving revision 1.3
diff -u -r1.3 eyes.texi
--- doc/eyes.texi       2001/09/06 21:34:19     1.3
+++ doc/eyes.texi       2001/11/28 16:19:45
@@ -1,12 +1,9 @@
 The purpose of this Chapter is to describe the algorithm used in
 GNU Go 3.0 to determine eyes. There are actually two alternative
-algorithms: the graph-based algorithm in @code{optics.c}, and
-the algorithm based on reading in @code{life.c}. The life
-code is slower than the graph based algorithm, but more 
-accurate. You can make it the default by using the option
address@hidden Otherwise, GNU Go will only call the life
-code if the graph based algorithm decides that it needs
-an expert opinion.
+algorithms: the graph-based algorithm in @file{optics.c}, and
+the algorithm based on reading in @file{life.c}. The life
+code is slower than the graph based algorithm, but sometimes more 
+accurate. You can enable it by using the option @option{--life}.
 
 @menu
 * Local Games::                 Local games
@@ -16,6 +13,7 @@
 * Graphs::                      Underlying graphs
 * Eye Shape::                   Pattern matching
 * Eye Topology::                False eyes and half eyes
+* Eye Topology with Ko::        False eyes and half eyes with ko
 * False Margins::               False margins
 * Eye Functions::               Functions in @file{optics.c}
 @end menu
@@ -130,7 +128,7 @@
 The precise algorithm by which the eye spaces are determined is
 somewhat complex. Documentation of this algorithm is in the
 comments in the source to the function @code{make_domains()} in
address@hidden/optics.c}.
address@hidden
 
 The eyespaces can be conveniently displayed using a colored 
 ascii diagram by running @command{gnugo -E}.
@@ -148,25 +146,25 @@
 
 @end example
 
-Tables of many eyespaces are found in the database @file{patterns/eyes.db}.
-Each of these may be thought of as a local game. The result of this
-game is listed after the eyespace in the form :max,min, where max is
-the number of eyes the pattern yields if @samp{O} moves first, while
-min is the number of eyes the pattern yields if @samp{X} moves
-first. The player who owns the eye space is denoted @samp{O}
-throughout this discussion.  Since three eyes are no better than two,
-there is no attempt to decide whether the space yields two eyes or
-three, so max never exceeds 2. Patterns with min>1 are omitted from
-the table.
+Tables of many eyespaces are found in the database
address@hidden/eyes.db}. Each of these may be thought of as a local
+game. The result of this game is listed after the eyespace in the form
address@hidden:max,min}, where @code{max} is the number of eyes the pattern
+yields if @samp{O} moves first, while @code{min} is the number of eyes
+the pattern yields if @samp{X} moves first. The player who owns the eye
+space is denoted @samp{O} throughout this discussion. Since three eyes
+are no better than two, there is no attempt to decide whether the space
+yields two eyes or three, so max never exceeds 2. Patterns with min>1
+are omitted from the table.
 
 For example, we have:
 
 @example
 @group
-Pattern 1
+Pattern 548
 
-  x
-!x*x
+ x
+x*x!
 
 :2,1
 
@@ -181,15 +179,15 @@
 and @samp{X} take turns moving, or either may pass.
 
 RULE 1: @samp{O} for his move may remove any vertex marked @samp{!}
-or marked @samp{.} .
+or marked @samp{.}.
 
 RULE 2: @samp{X} for his move may replace a @samp{.} by an @samp{X}. 
 
 RULE 3: @samp{X} may remove a @samp{!}. In this case, each @samp{.}
-adjacent to the "!" which is removed becomes a "!" . If an
-"@samp{X}" adjoins the "!" which is removed, then that "@samp{X}" and any
-which are connected to it are also removed. Any @samp{.} which
-are adjacent to the removed @samp{X}'s then become @samp{.}
+adjacent to the @samp{!} which is removed becomes a @samp{!} . If an
address@hidden adjoins the @samp{!} which is removed, then that @samp{X}
+and any which are connected to it are also removed. Any @samp{.} which
+are adjacent to the removed @samp{X}'s then become @samp{.}.
 
 Thus if @samp{O} moves first he can transform the eyeshape in
 the above example to:
@@ -217,7 +215,7 @@
 hence has a half eye to the left of 2.  This is subtle, and there are
 other such subtleties which our abstraction will not capture. Some of
 these at least can be dealt with by a refinements of the scheme, but
-we will content ourselves for the time being with a simplified
+we will content ourselves for the time being with a simplified model.
 
 @example
 @group
@@ -356,15 +354,12 @@
 eyeshapes in the database @file{patterns/eyes.db}.
 
 A further simplification is obtained through our treatment of
-half eyes and false eyes. Such patterns are tabulated in the
-database hey.h. During make_worms, which runs before the
-eye space analysis, the half eye and false eye patterns are
-tabulated in the array @code{half_eye}.
+half eyes and false eyes. Such patterns are identified by the
+topological analysis (@pxref{Eye Topology}).
 
 A half eye is isomorphic to the pattern @code{(!.)} . To see this,
 consider the following two eye shapes:
 
-
 @example
 @group 
 XOOOOOO
@@ -378,7 +373,7 @@
 XXOOOOO
 XOa...O
 XbOOOOO
-XXXXXX
+XXXXXXX
 
 @end group
 @end example
@@ -392,33 +387,42 @@
 
 @end example
 
-The second eyeshape has a half eye at a which is taken when @samp{O} 
+The second eyeshape has a half eye at @samp{a} which is taken when @samp{O} 
 or @samp{X} plays at @samp{b}. This is found by the topological
 criterion (@pxref{Eye Topology}).
 
+The graph of the eye_shape, ostensibly @samp{....} is modified by replacing
+the left @samp{.} by @samp{!.} during graph matching.
+
+
+A false eye is isomorphic to the pattern @code{(!)} . To see this,
+consider the following eye shape:
+
 @example
address@hidden
-ooo      half eye
-OhO
-*OX
address@hidden group
+
+XXXOOOOOO
+X.Oa....O
+XXXOOOOOO
+
 @end example
 
address@hidden
-and it is recorded in the half_eye array as follows. If @code{(i,j)}
-are the coordinates of the point @samp{a}, @code{half_eye[i][j].type==HALF_EYE}
-and @code{(half_eye[i][j].ki, half_eye[i][j].kj)} are the coordinates
-of @samp{b}.
+This is equivalent to the two previous eyeshapes, with an isomorphic
+local game @{2|address@hidden
 
-The graph of the eye_shape, ostensibly @samp{....} is modified by replacing
-the left @samp{.} by @samp{!}.
+This eyeshape has a false eye at @samp{a}. This is also found by the
+topological criterion.
+
+The graph of the eye_shape, ostensibly @samp{.....} is modified by replacing
+the left @samp{.} by @samp{!}. This is made directly in the eye data,
+not only during graph matching.
+
 
 @node Eye Shape, Eye Topology, Graphs, Eyes
 @comment  node-name,  next,  previous,  up
 @section Eye shape analysis
 
 The patterns in @file{patterns/eyes.db} are compiled into graphs
-represented essentially by linked lists in @file{patterns/eyes.c}.
+represented essentially by arrays in @file{patterns/eyes.c}.
 
 Each actual eye space as it occurs on the board is also
 compiled into a graph. Half eyes are handled as follows.
@@ -440,12 +444,12 @@
 vertices are adjacent if they are physically adjacent, 
 or if one is a half eye and the other is its key point.
 
-In recognize_eyes, each such graph arising from an actual eyespace is
+In @code{recognize_eyes()}, each such graph arising from an actual eyespace is
 matched against the graphs in @file{eyes.c}.  If a match is found, the
 result of the local game is known. If a graph cannot be matched, its
 local game is assumed to be @{2|address@hidden
 
address@hidden Eye Topology, False Margins, Eye Shape, Eyes
address@hidden Eye Topology, Eye Topology with Ko, Eye Shape, Eyes
 @comment  node-name,  next,  previous,  up
 @section Topology of Half Eyes and False Eyes
 
@@ -455,14 +459,14 @@
 @example
 @group
 
-   OOOX
-   O..X
-   OOOX
+   OOXX
+   O.O.
+   OO.X
 
 @end group
 @end example
 
-A FALSE EYE is a cave which cannot become an eye. Here is are
+A FALSE EYE is a cave which cannot become an eye. Here are
 two examples of false eyes for @code{O}:
 
 @example
@@ -476,7 +480,7 @@
 @end example
 
 We describe now the topological algorithm used to find half eyes
-and false eyes.
+and false eyes. In this section we ignore the possibility of ko.
 
 False eyes and half eyes can locally be characterized by the status of
 the diagonal intersections from an eye space. For each diagonal
@@ -512,13 +516,254 @@
 For all eye space points with at most one neighbor in the eye space,
 evaluate the status of the diagonal intersections according to the
 criteria above and classify the point from the sum of the values.
+
address@hidden  Eye Topology with Ko, False Margins, Eye Topology, Eyes
address@hidden  node-name,  next,  previous,  up
+
address@hidden Eye Topology with Ko
+
+This section extends the topological eye analysis to handle ko. We
+distinguish between a ko in favor of @samp{O}' and one in favor of @samp{X}:
+
address@hidden
address@hidden
+.?O?   good for O
+OO.O
+O.O?
+XOX.
+.X..
+
address@hidden group
address@hidden
+.?O?   good for X
+OO.O
+OXO?
+X.X.
+.X..
address@hidden group
address@hidden example
+
+Preliminarily we give the former the symbolic diagonal value @code{a}
+and the latter the diagonal value @code{b}. We should clearly have
address@hidden < a < 1 < b < 2}. Letting @code{e} be the topological eye value
+(still the sum of the four diagonal values), we want to have the
+following properties:
+
address@hidden
+e <= 2     - proper eye
+2 < e < 3  - worse than proper eye, better than half eye
+e = 3      - half eye
+3 < e < 4  - worse than half eye, better than false eye
+e >= 4     - false eye
address@hidden example
+
+In order to determine the appropriate values of @code{a} and @code{b} we
+analyze the typical cases of ko contingent topological eyes:
+
address@hidden
address@hidden
+      .X..      (slightly) better than proper eye
+(a)   ..OO          e < 2
+      OO.O
+      O.OO      e = 1 + a
+      XOX.
+      .X..
+
address@hidden group
+
address@hidden      
+      .X..      better than half eye, worse than proper eye
+(a')  ..OO      2 < e < 3
+      OO.O
+      OXOO      e = 1 + b
+      X.X.
+      .X..
+
address@hidden group
+      
address@hidden
+      .X..      better than half eye, worse than proper eye
+(b)   .XOO      2 < e < 3
+      OO.O
+      O.OO      e = 2 + a
+      XOX.
+      .X..
+
address@hidden group
+      
address@hidden
+      .X..      better than false eye, worse than half eye
+(b')  .XOO      3 < e < 4
+      OO.O
+      OXOO      e = 2 + b
+      X.X.
+      .X..
+
address@hidden group
+      
address@hidden
+      .X..
+      XOX.      (slightly) better than proper eye
+(c)   O.OO          e < 2
+      OO.O
+      O.OO      e = 2a
+      XOX.
+      .X..
+
address@hidden group
+      
address@hidden
+      .X..
+      XOX.      proper eye, some aji
+(c')  O.OO      e ~ 2
+      OO.O
+      OXOO      e = a + b
+      X.X.
+      .X..
+
address@hidden group
+      
address@hidden
+      .X..
+      X.X.      better than half eye, worse than proper eye
+(c'') OXOO      2 < e < 3
+      OO.O
+      OXOO      e = 2b
+      X.X.
+      .X..
+
address@hidden group
+      
address@hidden
+      .X...
+      XOX..     better than half eye, worse than proper eye
+(d)   O.O.X     2 < e < 3
+      OO.O.
+      O.OO.     e = 1 + 2a
+      XOX..
+      .X...
+
address@hidden group
+      
address@hidden
+      .X...
+      XOX..     half eye, some aji
+(d')  O.O.X     e ~ 3
+      OO.O.
+      OXOO.     e = 1 + a + b
+      X.X..
+      .X...
+
address@hidden group
+      
address@hidden
+      .X...
+      X.X..     better than false eye, worse than half eye
+(d'') OXO.X     3 < e < 4
+      OO.O.
+      OXOO.     e = 1 + 2b
+      X.X..
+      .X...
+
address@hidden group
+      
address@hidden
+      .X...
+      XOX..     better than false eye, worse than half eye
+(e)   O.OXX     3 < e < 4
+      OO.O.
+      O.OO.     e =  2 + 2a
+      XOX..
+      .X...
+
address@hidden group
+      
address@hidden
+      .X...
+      XOX..     false eye, some aji
+(e')  O.OXX     e ~ 4
+      OO.O.
+      OXOO.     e = 2 + a + b
+      X.X..
+      .X...
 
address@hidden False Margins, Eye Functions, Eye Topology, Eyes
address@hidden group
+      
address@hidden
+      .X...
+      X.X..     (slightly) worse than false eye
+(e'') OXOXX     4 < e
+      OO.O.
+      OXOO.     e = 2 + 2b
+      X.X..
+      .X...
+
address@hidden group
address@hidden example      
+
+It may seem obvious that we should use
address@hidden
+(i)   a=1/2, b=3/2
address@hidden example
+but this turns out to have some drawbacks. These can be solved by
+using either of
address@hidden
+(ii)  a=2/3, b=4/3
+(iii) a=3/4, b=5/4
+(iv)  a=4/5, b=6/5
+
address@hidden example
+
+Summarizing the analysis above we have the following table for the
+four different choices of @code{a} and @code{b}.
+
address@hidden
+case    symbolic        a=1/2   a=2/3   a=3/4   a=4/5   desired
+        value           b=3/2   b=4/3   b=5/4   b=6/5   interval
+(a)     1+a             1.5     1.67    1.75    1.8         e < 2
+(a')    1+b             2.5     2.33    2.25    2.2     2 < e < 3
+(b)     2+a             2.5     2.67    2.75    2.8     2 < e < 3
+(b')    2+b             3.5     3.33    3.25    3.2     3 < e < 4
+(c)     2a              1       1.33    1.5     1.6         e < 2
+(c')    a+b             2       2       2       2           e ~ 2
+(c'')   2b              3       2.67    2.5     2.4     2 < e < 3
+(d)     1+2a            2       2.33    2.5     2.6     2 < e < 3
+(d')    1+a+b           3       3       3       3           e ~ 3
+(d'')   1+2b            4       3.67    3.5     3.4     3 < e < 4
+(e)     2+2a            3       3.33    3.5     3.6     3 < e < 4
+(e')    2+a+b           4       4       4       4           e ~ 4
+(e'')   2+2b            5       4.67    4.5     4.4     4 < e
+
address@hidden example
+
+We can notice that (i) fails for the cases (c''), (d), (d''), and (e).
+The other three choices get all values in the correct intervals. The
+main distinction between them is the relative ordering of (c'') and (d)
+(or analogously (d'') and (e)). If we do a more detailed analysis of
+these we can see that in both cases @samp{O} can secure the eye
+unconditionally if he moves first while @samp{X} can falsify it with ko
+if he moves first. The difference is that in (c''), @samp{X} has to make
+the first ko threat, while in (d), O has to make the first ko threat.
+Thus (c'') is better for O and ought to have a smaller topological eye
+value than (d). This gives an indication that (iv) is the better choice.
+
+We can notice that any value of @code{a}, @code{b} satisfying
address@hidden and @code{3/4<a<1} would have the same qualities as choice
+(iv) according to the analysis above. One interesting choice is
address@hidden/8, b=9/8} since these allow exact computations with floating
+point values having a binary mantissa. The latter property is shared by
address@hidden/4} and @code{a=1/2}.
+
+When there are three kos around the same eyespace, things become
+more complex. This case is, however, rare enough that we ignore it.
+
+
address@hidden False Margins, Eye Functions, Eye Topology with Ko, Eyes
 @comment  node-name,  next,  previous,  up
 @section False Margins
 
-The following situation is rare but special enough to warrant
-separate attention:
+The following situation is rare but special enough to warrant separate
+attention:
 
 @example
    OOOOXX
@@ -538,134 +783,68 @@
 @comment  node-name,  next,  previous,  up
 @section Functions in @file{optics.c}
 
-Here are the public functions in @file{optics.c}. The statically
-declared functions are documented in the source code.
+Here are the public functions in @file{optics.c}, except some simple
+access functions used by autohelpers. The statically declared functions
+are documented in the source code.
 
 @itemize @bullet 
address@hidden @code{void make_domains(struct eye_data 
b_eye[MAX_BOARD][MAX_BOARD], struct eye_data w_eye[MAX_BOARD][MAX_BOARD])}
address@hidden @code{void make_domains(struct eye_data b_eye[BOARDMAX], struct 
eye_data w_eye[BOARDMAX], int owl_call)}
 @findex make_domains
 @quotation
-This function is called from make_dragons(). It marks the black
-and white domains (eyeshape regions) and collects some statistics
-about each one.
+This function is called from @code{make_dragons()} and from
address@hidden()}. It marks the black and white domains
+(eyeshape regions) and collects some statistics about each one.
 @end quotation
address@hidden @code{void originate_eye(int i, int j, int m, int n, int *esize, 
int *msize, struct eye_data eye[MAX_BOARD][MAX_BOARD])}
address@hidden originate_eye
address@hidden
-originate_eye(i, j, i, j, *size) creates an eyeshape with origin (i, j).
-the last variable returns the size. The repeated variables (i, j) are due
-to the recursive definition of the function.
address@hidden quotation
address@hidden @code{static void print_eye(struct eye_data 
eye[MAX_BOARD][MAX_BOARD], int i, int j)}
address@hidden print_eye
address@hidden
-Print debugging data for the eyeshape at (i,j). Useful with GDB.
address@hidden quotation
address@hidden @code{void compute_eyes(int i, int  j, int *max, int *min, 
-       int *attacki, int *attackj, struct eye_data eye[MAX_BOARD][MAX_BOARD],
-       int add_moves, int color)}
address@hidden @code{void compute_eyes(int pos, int *max, int *min, int 
*attack_point, int *defense_point, struct eye_data eye[BOARDMAX], struct 
half_eye_data heye[BOARDMAX], int add_moves, int color)}
 @findex compute_eyes
 @quotation
-Given an eyespace with origin (i,j), this function computes the
-minimum and maximum numbers of eyes the space can yield.
-If @code{add_moves==1}, this function may add a move_reason for @code{color} at
-a vital point which is found by the function. If @code{add_moves==0},
-set @code{color==EMPTY}.
+Given an eyespace with origin @code{pos}, this function computes the
+minimum and maximum numbers of eyes the space can yield. If max and
+min are different, then vital points of attack and defense are also
+generated.
 @end quotation
address@hidden @code{void compute_eyes_pessimistic(int i, int  j, int *max, int 
*min, int *pessimistic_min, int *attacki, int *attackj, int *defendi, int 
*defendj, struct eye_data eye[MAX_BOARD][MAX_BOARD], struct half_eye_data 
heye[MAX_BOARD][MAX_BOARD])}
address@hidden @code{void compute_eyes_pessimistic(int pos, int *max, int *min, 
int *pessimistic_min, int *attack_point, int *defense_point, struct eye_data 
eye[BOARDMAX], struct half_eye_data heye[BOARDMAX])}
 @findex compute_eyes_pessimistic
 @quotation
-This function works like compute_eyes(), except that it also gives
-a pessimistic view of the chances to make eyes. Since it is intended
-to be used from the owl code, the option to add move reasons has
-been removed.
+This function works like @code{compute_eyes()}, except that it also gives
+a pessimistic view of the chances to make eyes.
 @end quotation
address@hidden @code{void propagate_eye (int i, int j, struct eye_data 
eye[MAX_BOARD][MAX_BOARD])}
address@hidden propogate_eye
address@hidden @code{void propagate_eye(int origin, struct eye_data 
eye[BOARDMAX])}
address@hidden propagate_eye
 @quotation
-Copies the data at the origin (i, j) to the rest of the eye (certain fields 
only).
+Copies the data at @code{origin} to the rest of the eye (invariant
+fields only).
 @end quotation
address@hidden @code{static int recognize_eye(int i, int j, int *ai, int *aj, 
int *di, int *dj, int *max, int *min, struct eye_data 
eye[MAX_BOARD][MAX_BOARD], struct half_eye_data heye[MAX_BOARD][MAX_BOARD], int 
add_moves, int color)}
address@hidden @code{static int recognize_eye(int pos, int *attack_point, int 
*defense_point, int *max, int *min, struct eye_data eye[BOARDMAX], struct 
half_eye_data heye[BOARDMAX], int add_moves, int color)}
 @quotation
 Declared static but documented here because of its importance. The life
 code supplies an alternative version of this function called
address@hidden()}.  Here @code{(i,j)} is the origin of an
-eyespace. Returns 1 if there is a pattern in @file{eyes.c} matching the
address@hidden()}.  Here @code{pos} is the origin of an
+eyespace. Returns 1 if there is a pattern in @file{eyes.db} matching the
 eyespace, or 0 if no match is found. If there is a key point for attack,
address@hidden(*ai, *aj)} are set to its location, or @code{(-1, -1)} if there 
is
-none.  Similarly @code{(*di, *dj)} is the location of a vital defense
address@hidden is set to its location, or @code{NO_MOVE} if there is
+none.  Similarly @code{*defense_point} is the location of a vital defense
 point. @code{*min} and @code{*max} are the minimum and maximum number of eyes
 that can be made in this eyespace respectively. Vital attack/defense points
 exist if and only if @code{*min != *max}. If @code{add_moves==1}, this
-function may add a move_reason for (color) at a vital point which is found by
-the function. If @code{add_moves==0}, set @code{color==EMPTY}.
address@hidden quotation
address@hidden @code{ void add_half_eye(int m, int n, struct eye_data 
eye[MAX_BOARD][MAX_BOARD], struct half_eye_data hey[MAX_BOARD][MAX_BOARD])}
address@hidden add_half_eye
address@hidden
-This function adds a half eye or false eye to an eye shape.
+function may add a move_reason for @code{color} at a vital point which
+is found by the function. If @code{add_moves==0}, set @code{color==EMPTY}.
 @end quotation
address@hidden @code{int eye_space(int i, int j)}
address@hidden eye_space
address@hidden @code{void add_false_eye(int pos, struct eye_data eye[BOARDMAX], 
struct half_eye_data heye[BOARDMAX])}
address@hidden add_false_eye
 @quotation
-Used from constraints to identify eye spaces, primarily for late endgame moves.
-This returns true if the location is an eye space of either color.
+This function turns a proper eyespace into a margin.
 @end quotation
address@hidden @code{int proper_eye_space(int i, int j)}
address@hidden proper_eye_space
address@hidden
-Used from constraints to identify proper eye spaces, primarily for late
-endgame moves. Returns true if the location is an eye space of either
-color and is not marginal.
address@hidden quotation
address@hidden @code{int marginal_eye_space(int i, int j)}
address@hidden marginal_eye_space
address@hidden
-Used from constraints to identify marginal eye spaces, primarily for late
-endgame moves. Returns true if the location is a marginal eye space of either
-color.
address@hidden quotation
address@hidden @code{void make_proper_eye_space(int i, int j, int color)}
address@hidden
-Turn a marginal eye space into a proper eye space.
address@hidden quotation
address@hidden @code{void remove_half_eye(int m, int n, int color)}
address@hidden remove_half_eye
address@hidden
-Remove a halfeye from an eye shape.
address@hidden quotation
address@hidden @code{void remove_eyepoint(int m, int n, int color)}
address@hidden remove_eyepoint
address@hidden
-Remove an eye point. This function can only be used before the
-segmentation into eyespaces.
address@hidden quotation
address@hidden @code{int topological_eye(int m, int n, int color, int *ai, int 
*aj, int *di, int *dj, struct eye_data b_eye[MAX_BOARD][MAX_BOARD], struct 
eye_data w_eye[MAX_BOARD][MAX_BOARD], struct half_eye_data 
heye[MAX_BOARD][MAX_BOARD])}
address@hidden @code{float topological_eye(int pos, int color, struct eye_data 
b_eye[BOARDMAX], struct eye_data w_eye[BOARDMAX], struct half_eye_data 
heye[BOARDMAX])}
 @findex topological_eye
 @quotation 
-See @xref{Eye Topology}. Evaluate the eye space at @code{(m, n)} topologically
-(@pxref{Eye Topology}). Returns 2 or less if @code{(m, n)} is a proper eye for
-(color); 3 if @code{(m, n)} is a half eye; 4 if @code{(m, n)} is a false eye.
address@hidden(*ai, *aj)} and @code{(*di, *dj)} return the coordinates of an 
unsettled
-diagonal intersection, or an attack or defense point of defense of an opponent
-stone occupying a diagonal intersection.
address@hidden quotation
address@hidden @code{int evaluate_diagonal_intersection(int m, int n, int 
color, int *vitali, int *vitalj)}
address@hidden evaluate_diagonal_intersection
address@hidden
-Evaluate an intersection which is diagonal to an eye space
-(@pxref{Eye Topology}).  Returns 0 if the opponent cannot safely
-play at the vertex; Returns 1 if empty and the opponent can
-safely play on it, or if the vertex is occupied by an opponent
-stone which can be either attacked or defended. Returns 2 if
-safely occupied by the opponent.  Exception: if one coordinate is
-off the board, returns 1; if both are off the board, returns
-0. This guarantees correct behavior for diagonal intersections of
-points on the edge or in the corner. If the return value is 1,
address@hidden(*vitali, *vitalj)} returns @code{(m, n)} if the vertex is
-empty, or the vital point of defense if it is occupied by an
-opponent stone.
+See @xref{Eye Topology}. Evaluate the eye space at @code{pos}
+topologically (@pxref{Eye Topology}). Returns 2 or less if @code{pos}
+is a proper eye for @code{color}; between 2 and 3 if the eye can be made
+false only by ko; 3 if @code{pos} is a half eye; between 3 and 4 if the
+eye can be made real only by ko; 4 if @code{pos} is a false eye. Attack
+and defense points for control of the diagonals are stored in the
address@hidden array.
 
 @end quotation
 @end itemize
-
Index: doc/incremental.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/incremental.texi,v
retrieving revision 1.3
diff -u -r1.3 incremental.texi
--- doc/incremental.texi        2001/09/06 21:34:20     1.3
+++ doc/incremental.texi        2001/11/28 16:19:45
@@ -1,4 +1,4 @@
-The algorithms in @code{board.c} implement a method of incremental board
+The algorithms in @file{board.c} implement a method of incremental board
 updates that keeps track of the following information for each string:
 
 @itemize @bullet
Index: doc/overview.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/overview.texi,v
retrieving revision 1.4
diff -u -r1.4 overview.texi
--- doc/overview.texi   2001/11/23 17:47:39     1.4
+++ doc/overview.texi   2001/11/28 16:19:46
@@ -581,7 +581,7 @@
 @end quotation
 @item @file{hash.h} and @file{cache.h}
 @quotation
-Header files for @code{hash.c} and @code{cache.c}.
+Header files for @file{hash.c} and @file{cache.c}.
 @end quotation
 @item @file{influence.c} and @file{influence.h}.
 @quotation
@@ -693,7 +693,7 @@
 @end itemize
 
 The following list contains, in addition to distributed source files 
-some intermediate automatically generated files such as patterns.c.
+some intermediate automatically generated files such as @file{patterns.c}.
 These are C source files produced by "compiling" various pattern
 databases, or in some cases (such as @file{hoshi.db}) themselves 
 automatically generated pattern databases produced by "compiling"
@@ -775,9 +775,9 @@
 @item @file{mkpat.c}: 
 @quotation 
 Pattern compiler for the move generation and connection
-databases. Takes the file @code{patterns.db} together with
-the autogenerated Joseki pattern files @code{hoshi.db}, @code{komoku.db},
address@hidden, @file{mokuhadzushi.db}, @file{takamoku.db} and produces 
+databases. Takes the file @file{patterns.db} together with
+the autogenerated Joseki pattern files @file{hoshi.db}, @file{komoku.db},
address@hidden, @file{mokuhadzushi.db}, @file{takamoku.db} and produces 
 @file{patterns.c}, or takes @file{conn.db} and produces @file{conn.c}.
 @end quotation
 
Index: doc/owl.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/owl.texi,v
retrieving revision 1.3
diff -u -r1.3 owl.texi
--- doc/owl.texi        2001/09/06 21:34:20     1.3
+++ doc/owl.texi        2001/11/28 16:19:46
@@ -56,7 +56,7 @@
 eyespace is sometimes wrong. The problem is when the optics code says
 that a dragon definitely has 2 eyes, but it isn't true due to 
 shortage of liberties, so the ordinary owl patterns never get into play.
-In such situations @code{owl_vital_apats.db} is the only available measure
+In such situations @file{owl_vital_apats.db} is the only available measure
 to correct mistakes by the optics. Currently the patterns in
 @file{owl_vital_apats.db} are only matched when the level is 9 or
 greater.
@@ -237,7 +237,7 @@
 @findex owl_lively
 @quotation
 True unless @code{(i, j)} is @code{EMPTY} or occupied by a lunch for the goal
-dragon. Used during @code{make_domains()} (see @code{optics.c}: lively macro).
+dragon. Used during @code{make_domains()} (see @file{optics.c}: lively macro).
 @end quotation
 @end itemize
 
Index: doc/patterns.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/patterns.texi,v
retrieving revision 1.4
diff -u -r1.4 patterns.texi
--- doc/patterns.texi   2001/11/17 19:47:56     1.4
+++ doc/patterns.texi   2001/11/28 16:19:47
@@ -38,7 +38,7 @@
 files @file{hoshi.sgf} (@pxref{Joseki Compiler}). There is no essential
 difference between these files, except that the ones in @file{patterns.db} and
 @file{patterns2.db} are hand written. They are concatenated before being
-compiled by @code{mkpat} into @code{patterns.c}. The purpose of the separate
+compiled by @code{mkpat} into @file{patterns.c}. The purpose of the separate
 file @file{patterns2.db} is that it is handy to move patterns into a new
 directory in the course of organizing them. The patterns in @file{patterns.db}
 are more disorganized, and are slowly being moved to @file{patterns2.db}.
@@ -83,7 +83,7 @@
 board itself---this is an edge pattern. Corners can also be indicated.
 Elements are not generated for '?' markers, but they are not
 completely ignored - see below.
-       
+        
 The line beginning @samp{:} describes various attributes of the pattern, such
 as its symmetry and its class. Optionally, a function called a
 ``helper'' can be provided to assist the matcher in deciding whether
@@ -388,11 +388,11 @@
   if (TRYMOVE(ti, tj, color)) @{
     if (TRYMOVE(ai, aj, other)) @{
       if (!p[ai][aj] || attack(ai, aj, NULL, NULL))
-       success = 1;
+        success = 1;
       else if (TRYMOVE(bi, bj, color)) @{
-       if (!safe_move(ci, cj, other))
-         success = 1;
-       popgo();
+        if (!safe_move(ci, cj, other))
+          success = 1;
+        popgo();
       @}
       popgo();
     @}
@@ -1107,7 +1107,7 @@
 
 @itemize @bullet
 @item @code{static void cut_connect_callback(int m, int n, int color, 
-       struct pattern *pattern, int ll, void *data)}
+        struct pattern *pattern, int ll, void *data)}
 @findex cut_connect_callback
 @quotation
 Try to match all (permutations of) connection patterns at (m,n).
Index: doc/sgf.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/sgf.texi,v
retrieving revision 1.3
diff -u -r1.3 sgf.texi
--- doc/sgf.texi        2001/09/06 21:34:20     1.3
+++ doc/sgf.texi        2001/11/28 16:19:47
@@ -9,7 +9,7 @@
 GNU Go contains a library to handle go game records in the SGF format in
 memory and to read and write SGF files. This library - @code{libsgf.a} -
 is in the @code{sgf} subdirectory. To use the SGF routines, include the
-file @code{sgftree.h}.
+file @file{sgftree.h}.
 
 Each game record is stored as a tree of @dfn{nodes}, where each node
 represents a state of the game, often after some move is made. Each node