[gnugo-devel] doc patch and structure discussion

[Gunnar Farneback]

More doc revisions in the appended patch.

Some observations regarding the structure of the documentation:

1. There are almost more details than overview in overview.texi. I'd
like this chapter to briefly introduce the various techniques being
used in the engine, with lots of references to later chapters.

2. The board documentation is split between overview.texi, board.texi,
api.texi, incremental.texi, and arguably reading.texi. All aspects of
the board handling should be discussed in a single chapter.

3. Of the 200 and a few pages, about 33 are spent listing functions.
Sometimes I get a feeling that this is just a waste of paper. In
particular, the list in section 9.7, "Move Generation Functions", is
four pages of mostly various add_xxx_move() and set_xxx_value()
functions. I just can't see a good reason for this list.

4. The ordering of some of the chapters is a bit strange. The first
four chapters all come very naturally. The fifth (analyzing) feels somewhat
 sudden but may be okay if chapter 4 (overview) is revised to give a
better overview.

The real problem in my opinion is that chapters 6 (API) and 7 (SGF)
are completely out of place. For the understanding of the engine these
are very auxiliary and would come more naturally towards the end of
the documentation.

Chapter 8 (board) is placed okay but the title (The Board Library) is
strange. What's important in the chapter is to discuss how the board
is handled. That there happens to be a separate library for the board
code is hardly a major point.

Chapters 9 to 17 all give details about various modules. The ordering
here is maybe not critical but I think it might make some sense to try
to do it bottom-up. If so, chapter 9 (move generation) should be
postponed.


I'd like to hear what other people think about the documentation,
especially those who have actually read it in an attempt to understand
the inner workings of GNU Go. We are obviously aware that it's both
incomplete and more or less out of date in certain areas. Taking that
into account:
* How useful is it overall?
* Which parts are good and which are bad?
* Is anything so bad/useless that it would be better to omit it?
* What improvements would be most important?

/Gunnar

Index: doc/dragon.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/dragon.texi,v
retrieving revision 1.8
diff -u -r1.8 dragon.texi
--- doc/dragon.texi     19 Mar 2002 19:03:59 -0000      1.8
+++ doc/dragon.texi     22 Mar 2002 15:04:14 -0000
@@ -22,7 +22,7 @@
 @file{dragon.c}.
 
 @cindex dragon
address@hidden worm     
address@hidden worm
 @cindex string
 @cindex worm closure
 A @dfn{worm} is a maximal set of vertices on the board which are connected
@@ -208,7 +208,7 @@
 We use currently use both concepts in parallel.
 
 @itemize
address@hidden @code{cutstone}: 
address@hidden @code{cutstone} 
 @quotation
 @cindex cutting stone
 This field is equal to 2 for cutting stones, 1 for potential cutting
@@ -238,7 +238,7 @@
 For cutting strings we set @code{worm[].cutstone=2}. For
 potential cutting strings we set @code{worm[].cutstone=1}.
 @end quotation
address@hidden @code{cutstone2}: 
address@hidden @code{cutstone2} 
 @quotation
 Cutting points are identified by the patterns in the connections
 database. Proper cuts are handled by the fact that attacking and
@@ -248,7 +248,7 @@
 @end quotation
 @findex find_cuts
 @findex make_domains
address@hidden @code{genus}: 
address@hidden @code{genus} 
 @quotation
 @cindex genus (worm)
 There are two separate notions of @dfn{genus} for worms and
@@ -259,7 +259,7 @@
 of connected components of its complement, minus one. It is
 an approximation to the number of eyes of the string.
 @end quotation
address@hidden @code{inessential}: 
address@hidden @code{inessential} 
 @quotation
 @cindex inessential string
 An @dfn{inessential} string is one which meets a
@@ -283,7 +283,7 @@
 cavities in @code{make_dragons()}.
 @end quotation
 @findex unconditional_life
address@hidden @code{invincible}: 
address@hidden @code{invincible} 
 @quotation
 @cindex invincible worm
 An @dfn{invincible} worm is one which GNU Go thinks
@@ -583,12 +583,12 @@
 struct half_eye_data half_eye[MAX_BOARD];
 
 struct half_eye_data @{
-  float value;      /* Topological eye value. */
-  int type;         /* HALF_EYE or FALSE_EYE; */
-  int num_attacks;  /* number of attacking points */
-  int attack_point[4];  /* the move to attack a topological halfeye */
-  int num_defends;      /* number of defending points */
-  int defense_point[4]; /* the move to defend a topological halfeye */
+  float value;          /* Topological eye value */
+  int type;             /* HALF_EYE or FALSE_EYE */
+  int num_attacks;      /* Number of attacking points */
+  int attack_point[4];  /* The moves to attack a topological halfeye */
+  int num_defends;      /* Number of defending points */
+  int defense_point[4]; /* The moves to defend a topological halfeye */
 @};
 
 @end group
@@ -663,7 +663,7 @@
 
 The difference between the two arrays is that the @code{dragon} array 
 is indexed by the board, and there is a copy of the dragon data 
-at every stone in the dragon, while there is only one copy of of
+at every stone in the dragon, while there is only one copy of
 the dragon2 data. The dragons are numbered, and the @code{id} field
 of the dragon is a key into the dragon2 array. Two macros DRAGON
 and DRAGON2 are provided for gaining access to the two arrays.
@@ -680,11 +680,11 @@
 for example you can access its neighor dragons by
 
 @example
-   for (k = 0; k < DRAGON2(pos).neighbors; k++) @{
-      int d = DRAGON2(pos).adjacent[k];
-      int apos = dragon2[d].origin;
-      do_something(apos);      
-   @}
+for (k = 0; k < DRAGON2(pos).neighbors; k++) @{
+  int d = DRAGON2(pos).adjacent[k];
+  int apos = dragon2[d].origin;
+  do_something(apos);
address@hidden
 @end example
 
 Similarly if you know the dragon number (which is @code{dragon[pos].id})
@@ -694,14 +694,14 @@
 Here are the definitions of each field in the @code{dragon} arrray.
 
 @itemize @bullet 
address@hidden @code{color}: 
address@hidden @code{color} 
 @quotation
 @cindex color (dragon)
 For strings, this is @code{BLACK} or @code{WHITE}. 
 For caves, it is @code{BLACK_BORDER}, @code{WHITE_BORDER} or 
 @code{GRAY_BORDER}. The meaning of these concepts is the same as for worms.
 @end quotation
address@hidden @code{id}:
address@hidden @code{id}
 @quotation
 The dragon number. This is a key into the @code{dragon2} array.
 @end quotation
@@ -714,12 +714,12 @@
 copied to the dragon origins. Amalgamation of two dragons
 amounts to changing the origin of one.
 @end quotation        
address@hidden @code{size}: 
address@hidden @code{size} 
 @quotation
 @cindex size (dragon)
 This is the cardinality of the dragon.
 @end quotation
address@hidden @code{effective_size}:
address@hidden @code{effective_size}
 @quotation
 @cindex effective size (dragon)
 The sum of the effective sizes of the constituent worms.
@@ -728,7 +728,7 @@
 cardinality of the dragon plus the number of empty vertices which are
 nearer this dragon than any other.
 @end quotation
address@hidden @code{genus}: 
address@hidden @code{genus} 
 @quotation
 @cindex genus (dragon)
 The @dfn{genus} of a nonempty dragon consists of the number
@@ -737,7 +737,7 @@
 is a computable approximation to the number of eyes a dragon
 has.
 @end quotation
address@hidden @code{escape_route}:
address@hidden @code{escape_route}
 @quotation
 @cindex escape_route (dragon)
 This is a measure of the escape potential of the dragon. If
@@ -746,6 +746,7 @@
 urgent. Further documentation may be found else where
 (@pxref{Escape}).
 @end quotation
address@hidden @code{status}
 @cindex status (dragon)
 @findex compute_dragon_status
 @quotation
@@ -959,15 +960,15 @@
 @item @code{int is_worm_origin(int w, int pos)}
 @findex is_worm_origin
 @quotation
-Test whether the origin of the worm at (w) is (pos).
+Test whether the origin of the worm at @code{w} is @code{pos}.
 @end quotation
 @item @code{void change_defense(int str, int move, int dcode)}
 @findex change_defense
 @quotation
 @code{change_defense(str, move, dcode)} is used to add and remove defense
 points. It can also be used to change the defense code. The meaning
-of the call is that the string (str) can be defended by (move) with
-defense code (dcode). If (dcode) is zero, the move is removed from
+of the call is that the string @code{str} can be defended by @code{move} with
+defense code @code{dcode}. If @code{dcode} is zero, the move is removed from
 the list of defense moves if it was previously listed.
 @end quotation
 @item @code{void change_attack(int str, int move, int acode)}
@@ -975,8 +976,8 @@
 @quotation
 @code{change_attack(str, move, acode)} is used to add and remove attack
 points. It can also be used to change the attack code. The meaning
-of the call is that the string (str) can be attacked by (move) with
-attack code (acode). If (acode) is zero, the move is removed from
+of the call is that the string @code{str} can be attacked by @code{move} with
+attack code @code{acode}. If @code{acode} is zero, the move is removed from
 the list of attack moves if it was previously listed.
 @end quotation
 @item @code{void change_defense_threat(int str, int move, int dcode)}
@@ -984,8 +985,8 @@
 @quotation
 Used to add and remove defense threat points. It can also be used to
 change the defense threat code. The meaning of the call is that the
-string (str) can threaten to be defended by (move) with defense threat
-code (dcode). If (dcode) is zero, the move is removed from the list
+string @code{str} can threaten to be defended by @code{move} with defense 
threat
+code @code{dcode}. If @code{dcode} is zero, the move is removed from the list
 of defense threat moves if it was previously listed.
 @end quotation  
 @item @code{void change_attack_threat(int str, int move, int acode)}
@@ -993,33 +994,33 @@
 @quotation
 Used to add and remove attack threat points. It can also be used to
 change the attack threat code. The meaning of the call is that the
-string (str) can threaten to be attacked by (move) with attack threat
-code (acode). If (acode) is zero, the move is removed from the list
+string @code{str} can threaten to be attacked by @code{move} with attack threat
+code @code{acode}. If @code{acode} is zero, the move is removed from the list
 of attack threat moves if it was previously listed.
 @end quotation
 @item @code{int attack_move_known(int move, int str)}
 @findex attack_move_known
 @quotation
-Check whether (move) is listed as an attack point for (str) and
-return the attack code. If (move) is not listed, return 0.
+Check whether @code{move} is listed as an attack point for @code{str} and
+return the attack code. If @code{move} is not listed, return 0.
 @end quotation
 @item @code{int defense_move_known(int move, int str)}
 @findex defense_move_known
 @quotation
-Check whether (move) is listed as a defense point for (str) and
-return the defense code. If (move) is not listed, return 0.
+Check whether @code{move} is listed as a defense point for @code{str} and
+return the defense code. If @code{move} is not listed, return 0.
 @end quotation
 @item @code{int attack_threat_move_known(int move, int str)}
 @findex attack_threat_move_known
 @quotation
-Check whether (move) is listed as an attack threat point for (str)
-and return the attack threat code. If (move) is not listed, return  * 0.
+Check whether @code{move} is listed as an attack threat point for @code{str}
+and return the attack threat code. If @code{move} is not listed, return 0.
 @end quotation
 @item @code{int defense_threat_move_known(int move, int str)}
 @findex defense_threat_move_known
 @quotation
-Check whether (move) is listed as a defense threat point for (str)
-and return the defense threat code. If (move) is not listed, return 0.
+Check whether @code{move} is listed as a defense threat point for @code{str}
+and return the defense threat code. If @code{move} is not listed, return 0.
 @end quotation
 @item @code{void propagate_worm(int pos)}
 @findex propagate_worm
Index: doc/influence.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/influence.texi,v
retrieving revision 1.9
diff -u -r1.9 influence.texi
--- doc/influence.texi  16 Mar 2002 04:01:49 -0000      1.9
+++ doc/influence.texi  22 Mar 2002 15:04:14 -0000
@@ -754,12 +754,12 @@
 @item @code{int influence_get_moyo_size(int pos, int color)}
 @findex influence_get_moyo_size
 @quotation
-Return the size of the moyo around (pos).
+Return the size of the moyo around @code{pos}.
 @end quotation
 @item @code{void influence_get_moyo_segmentation(int opposite, struct 
moyo_data *moyos)}
 @findex influence_get_moyo_segmentation
 @quotation
-Export the moyo segmentation. If (opposite) is true, then
+Export the moyo segmentation. If @code{opposite} is true, then
 initial_opposite_influence is used, otherwise initial_influence.
 @end quotation
 @item @code{void compute_initial_influence(int color, int dragons_known)}
@@ -802,7 +802,7 @@
 @quotation
 Return the color who has area at @code{pos}, or EMPTY.
 @end quotation
address@hidden float @code{influence_delta_territory(int pos, int color, char 
saved_stones[BOARDMAX], float *followup_value)}
address@hidden @code{float influence_delta_territory(int pos, int color, char 
saved_stones[BOARDMAX], float *followup_value)}
 @findex influence_delta_territory
 @quotation
 Compute the difference in territory made by a move by color at @code{pos}.  
@@ -884,7 +884,7 @@
 at least one of the options below to generate any output.
 
 @itemize @bullet
address@hidden @option{-m 0x010} or @option{-m 16}.
address@hidden @option{-m 0x010} or @option{-m 16}
 @quotation
 Show colored display of territory/moyo/area regions.
 @itemize @minus
@@ -895,32 +895,32 @@
 This feature is very useful to get an immediate impression of the influence
 regions as GNU Go sees them.
 @end quotation
address@hidden @option{-m 0x20} or @option{-m 32}.
address@hidden @option{-m 0x20} or @option{-m 32}
 @quotation
 Show numerical influence values for white and black. These come in
 two separate diagrams, the first one for white, the second one for
 black. Notice that the influence values are represented by floats and
 thus have been rounded in these diagrams.
 @end quotation
address@hidden @option{-m 0x40} or @option{-m 64}.
address@hidden @option{-m 0x40} or @option{-m 64}
 @quotation
 This generates two diagrams showing the permeability for black and white
 influence on the board.
 @end quotation
address@hidden @option{-m 0x80} or @option{-m 128}.
address@hidden @option{-m 0x80} or @option{-m 128}
 @quotation
 This shows the strength of the influence sources for black and white 
 across the board. You will see sources at each lively stone (with strength
 depending on the strength of this stone), and sources contributed by
 patterns.
 @end quotation
address@hidden @option{-m 0x100} or @option{-m 256}.
address@hidden @option{-m 0x100} or @option{-m 256}
 @quotation
 This shows the attenuation with which the influence sources spread
 influence across the board. Low attenuation indicates far-reaching
 influence sources.
 @end quotation
address@hidden @option{-m 0x200} or @option{-m 512}.
address@hidden @option{-m 0x200} or @option{-m 512}
 @quotation
 This shows the territory valuation of GNU Go. Each intersection is
 shown with a value between -1.0 and +1.0 (or -2 resp. +2 if there is
Index: doc/overview.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/overview.texi,v
retrieving revision 1.7
diff -u -r1.7 overview.texi
--- doc/overview.texi   19 Mar 2002 19:03:59 -0000      1.7
+++ doc/overview.texi   22 Mar 2002 15:04:16 -0000
@@ -704,78 +704,78 @@
 
 @itemize @bullet
 
address@hidden @file{conn.db}: 
address@hidden @file{conn.db} 
 @quotation 
 Database of connection patterns.
 @end quotation
 
address@hidden @file{conn.c}: 
address@hidden @file{conn.c} 
 @quotation 
 Automatically generated file, containing connection
 patterns in form of struct arrays, compiled by @command{mkpat}
 from @file{conn.db}.
 @end quotation
 
address@hidden @file{eyes.c}: 
address@hidden @file{eyes.c} 
 @quotation 
 Automatically generated file, containing eyeshape
 patterns in form of struct arrays, compiled by @command{mkpat} 
 from @file{eyes.db}.
 @end quotation
 
address@hidden @file{eyes.h}: 
address@hidden @file{eyes.h} 
 @quotation 
 Header file for @file{eyes.c}.
 @end quotation
 
address@hidden @file{eyes.db}: 
address@hidden @file{eyes.db} 
 @quotation 
 Database of eyeshape patterns. @xref{Eyes}, for
 details.
 @end quotation
 
address@hidden @file{helpers.c}: 
address@hidden @file{helpers.c} 
 @quotation 
 These are helper functions to assist in evaluating
 moves by matchpat.
 @end quotation
 
address@hidden @file{hoshi.sgf}: 
address@hidden @file{hoshi.sgf} 
 @quotation 
 Smart Go Format file containing 4-4 point openings
 @end quotation
 
address@hidden @file{hoshi.db}: 
address@hidden @file{hoshi.db} 
 @quotation 
 Automatically generated database of 4-4 point opening
 patterns, make by compiling @file{hoshi.sgf}
 @end quotation
 
address@hidden @file{joseki.c}: 
address@hidden @file{joseki.c} 
 @quotation 
 Joseki compiler, which takes a joseki file in
 Smart Go Format, and produces a pattern database.
 @end quotation
 
address@hidden @file{komoku.sgf}:
address@hidden @file{komoku.sgf}
 @quotation  
 Smart Go Format file containing 3-4 point openings
 @end quotation
 
address@hidden @file{komoku.db}: 
address@hidden @file{komoku.db} 
 @quotation 
 Automatically generated database of 3-4 point opening
 patterns, make by compiling @file{komoku.sgf}
 @end quotation
 
address@hidden @file{mkeyes.c}: 
address@hidden @file{mkeyes.c} 
 @quotation 
 Pattern compiler for the eyeshape databases. This
 program takes @file{eyes.db} as input and produces @file{eyes.c}
 as output.
 @end quotation
 
address@hidden @file{mkpat.c}: 
address@hidden @file{mkpat.c} 
 @quotation 
 Pattern compiler for the move generation and connection
 databases. Takes the file @file{patterns.db} together with
@@ -784,47 +784,47 @@
 @file{patterns.c}, or takes @file{conn.db} and produces @file{conn.c}.
 @end quotation
 
address@hidden @file{mokuhazushi.sgf}: 
address@hidden @file{mokuhazushi.sgf} 
 @quotation 
 Smart Go Format file containing 5-3 point openings
 @end quotation
 
address@hidden @file{mokuhazushi.db}:
address@hidden @file{mokuhazushi.db}
 @quotation 
 Pattern database compiled from mokuhadzushi.sgf
 @end quotation
 
address@hidden @file{sansan.sgf}: 
address@hidden @file{sansan.sgf} 
 @quotation 
 Smart Go Format file containing 3-3 point openings
 @end quotation
 
address@hidden @file{sansan.db}: 
address@hidden @file{sansan.db} 
 @quotation 
 Pattern database compiled from @file{sansan.sgf}
 @end quotation
 
address@hidden @file{takamoku.sgf}: 
address@hidden @file{takamoku.sgf} 
 @quotation 
 Smart Go Format file containing 5-4 point openings
 @end quotation
 
address@hidden @file{takamoku.db}: 
address@hidden @file{takamoku.db} 
 @quotation 
 Pattern database compiled from takamoku.sgf.
 @end quotation
 
address@hidden @file{patterns.c}: 
address@hidden @file{patterns.c} 
 @quotation 
 Pattern data, compiled from patterns.db by mkpat.
 @end quotation
 
address@hidden @file{patterns.h}: 
address@hidden @file{patterns.h} 
 @quotation 
 Header file relating to the pattern databases.
 @end quotation
 
address@hidden @file{patterns.db} and @file{patterns2.db}:
address@hidden @file{patterns.db} and @file{patterns2.db}
 @quotation 
 These contain pattern databases in human readable form.  
 @end quotation
@@ -854,17 +854,17 @@
 add some useful facilities:
 
 @itemize @bullet
address@hidden @code{%m}: 
address@hidden @code{%m} 
 @quotation
 Takes two parameters, and displays a formatted board co-ordinate.
 @end quotation
address@hidden indentation:
address@hidden indentation
 @quotation
 Trace messages are automatically indented to reflect
 the current stack depth, so it is clear during read-ahead
 when it puts a move down or takes one back.
 @end quotation
address@hidden "outdent":
address@hidden "outdent"
 @quotation As a workaround, @code{%o} at the beginning of the
 format string suppresses the indentation.
 @end quotation
Index: doc/patterns.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/patterns.texi,v
retrieving revision 1.11
diff -u -r1.11 patterns.texi
--- doc/patterns.texi   10 Mar 2002 16:39:00 -0000      1.11
+++ doc/patterns.texi   22 Mar 2002 15:04:18 -0000
@@ -113,10 +113,11 @@
 
 @example
 
-  |?X?.?
-  |O.*oo
-  |O....
-  |o....
+  |oOO?
+  |...X
+  |..*?
+  |..o.
+  |..o?
 
   :8,ed,NULL
 @end example
@@ -290,38 +291,38 @@
 of values are as follows.
 
 @itemize @bullet
address@hidden @code{terri(x)} :
address@hidden @code{terri(x)}
 @findex terri
 @quotation
 Forces the territorial value of the move to be at least x.
 @end quotation
address@hidden @code{minterri(x)} :   
address@hidden @code{minterri(x)}
 @findex minterri
 @quotation
 Forces the territorial value of the move to be at least x.
 @end quotation
address@hidden @code{maxterri(x)}  : 
address@hidden @code{maxterri(x)}
 @findex maxterri
 @quotation
 Forces the territorial value of the move to be at most x.
 @end quotation
address@hidden @code{value(x)}     : 
address@hidden @code{value(x)}
 @findex value
 @quotation
 Forces the final value of the move to be at least x.
 @end quotation
address@hidden @code{minvalue(x)}
address@hidden @code{minvalue(x)}, @code{maxvalue(x)}
 @findex minvalue
address@hidden(x)}  : 
address@hidden maxvalue
 @quotation
 Forces the final value of the move to be at least/most x.
 @end quotation
address@hidden @code{shape(x)}     : 
address@hidden @code{shape(x)}
 @findex shape
 @quotation
 Adds x to the move's shape value.
 @end quotation
address@hidden @code{followup(x)}  : 
address@hidden @code{followup(x)}
 @findex followup
 @quotation
 Adds x to the move's followup value.
@@ -624,8 +625,7 @@
 @code{weak(x)}
 @end example
 
-True for a dragon that is perceived as weak. The definition of weak is
-given in @xref{Moyo}.
+True for a dragon that is perceived as weak.
 
 @example