[gnugo-devel] More doc revisions

[Gunnar Farneback]

Here's a doc patch. Most notably it corrects a number of function
index entries and moves the list of contents from the end to its usual
place at the beginning of the printed documentation.

/Gunnar

Index: doc/analyze.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/analyze.texi,v
retrieving revision 1.6
diff -u -r1.6 analyze.texi
--- doc/analyze.texi    24 Feb 2002 17:40:10 -0000      1.6
+++ doc/analyze.texi    19 Mar 2002 15:08:05 -0000
@@ -45,9 +45,10 @@
 this is that you may want to modify a pattern already matched 
 instead of introducing a new one.
 
-If you use the @option{-w} option, GNU Go will report the statuses
-of dragons around the board. This type of information is available
-by different methods, however (@pxref{Debugboard}, @pxref{Colored Display}).
+If you use the @option{-w} option, GNU Go will report the statuses of
+worms and dragons around the board. This type of information is
+available by different methods, however (@pxref{Debugboard},
address@hidden Display}).
 
 @node Output File, Decide string, Traces, Analyzing
 @comment  node-name,  next,  previous,  up
@@ -115,8 +116,8 @@
 
 This is to be interpreted as follows. The node in question
 was generated by the function @code{attack3()} in @file{engine/reading.c},
-which was called on the string at @code{D12}. Of the data in 
-parentheses tells you the values of @code{count_variations} and
+which was called on the string at @code{D12}. The data in 
+parentheses tell you the values of @code{count_variations} and
 @code{hashdata.hashval}. 
 
 The second value (``hash'') you probably will not need to know
Index: doc/dragon.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/dragon.texi,v
retrieving revision 1.7
diff -u -r1.7 dragon.texi
--- doc/dragon.texi     10 Mar 2002 16:37:05 -0000      1.7
+++ doc/dragon.texi     19 Mar 2002 15:08:12 -0000
@@ -941,7 +941,7 @@
 
 @itemize @bullet
 @item @code{void make_worms(int save_verbose)}
address@hidden void make_worms(int save_verbose)
address@hidden make_worms
 @quotation
 This function finds all worms and assembles some data about them.
 Each worm is marked with an origin.  This is an arbitrarily chosen
@@ -951,18 +951,18 @@
 stones lie in the same worm, compare their origins.
 @end quotation
 @item @code{int is_same_worm(int w1, int w2) }
address@hidden int is_same_worm(int w1, int w2) 
address@hidden is_same_worm
 @quotation
 Test whether two worms are the same. Used by autohelpers.
 Before this function can be called, build_worms must have been run.
 @end quotation 
 @item @code{int is_worm_origin(int w, int pos)}
address@hidden int is_worm_origin(int w, int pos)
address@hidden is_worm_origin
 @quotation
 Test whether the origin of the worm at (w) is (pos).
 @end quotation
 @item @code{void change_defense(int str, int move, int dcode)}
address@hidden void change_defense(int str, int move, int dcode)
address@hidden 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
@@ -971,7 +971,7 @@
 the list of defense moves if it was previously listed.
 @end quotation
 @item @code{void change_attack(int str, int move, int acode)}
address@hidden void change_attack(int str, int move, int acode)
address@hidden change_attack
 @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
@@ -980,7 +980,7 @@
 the list of attack moves if it was previously listed.
 @end quotation
 @item @code{void change_defense_threat(int str, int move, int dcode)}
address@hidden void change_defense_threat(int str, int move, int dcode)
address@hidden change_defense_threat
 @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
@@ -989,7 +989,7 @@
 of defense threat moves if it was previously listed.
 @end quotation  
 @item @code{void change_attack_threat(int str, int move, int acode)}
address@hidden void change_attack_threat(int str, int move, int acode)
address@hidden change_attack_threat
 @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
@@ -998,31 +998,31 @@
 of attack threat moves if it was previously listed.
 @end quotation
 @item @code{int attack_move_known(int move, int str)}
address@hidden int attack_move_known(int move, int str)
address@hidden 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.
 @end quotation
 @item @code{int defense_move_known(int move, int str)}
address@hidden int defense_move_known(int move, int str)
address@hidden 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.
 @end quotation
 @item @code{int attack_threat_move_known(int move, int str)}
address@hidden int attack_threat_move_known(int move, int str)
address@hidden 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.
 @end quotation
 @item @code{int defense_threat_move_known(int move, int str)}
address@hidden int defense_threat_move_known(int move, int str)
address@hidden 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.
 @end quotation
 @item @code{void propagate_worm(int pos)}
address@hidden void propagate_worm(int pos)
address@hidden propagate_worm
 @quotation
 propagate_worm() takes the worm data at one stone and copies it to 
 the remaining members of the worm.
Index: doc/gnugo.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/gnugo.texi,v
retrieving revision 1.6
diff -u -r1.6 gnugo.texi
--- doc/gnugo.texi      4 Mar 2002 06:49:08 -0000       1.6
+++ doc/gnugo.texi      19 Mar 2002 15:08:12 -0000
@@ -49,6 +49,8 @@
 
 @end titlepage
 
address@hidden
+
 @node Top, Introduction, (dir), (dir)
 @comment node-name, next,         previous, up
 @ifinfo
@@ -253,9 +255,4 @@
 
 @printindex fn
 
address@hidden
 @bye
-
-
-
-
Index: doc/move_generation.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/move_generation.texi,v
retrieving revision 1.10
diff -u -r1.10 move_generation.texi
--- doc/move_generation.texi    10 Mar 2002 16:37:05 -0000      1.10
+++ doc/move_generation.texi    19 Mar 2002 15:08:15 -0000
@@ -748,7 +748,7 @@
 Flag that this move is worthwhile to play as a pure threat move.
 @end quotation
 @item @code{float compute_shape_factor(int pos) }
address@hidden float compute_shape_factor
address@hidden compute_shape_factor
 @quotation
 This function computes the shape factor, which multiplies the score of
 a move. We take the largest positive contribution to shape and add 1
@@ -928,13 +928,13 @@
 
 @itemize @bullet
 @item @code{static void find_more_attack_and_defense_moves(int color)}
address@hidden static void find_more_attack_and_defense_moves(int color)
address@hidden find_more_attack_and_defense_moves
 @quotation
 Test all moves which defend, attack, connect or cut to see if they
 also attack or defend some other worm.
 @end quotation
 @item @code{static void find_more_owl_attack_and_defense_moves(int color)}
address@hidden static void find_more_owl_attack_and_defense_moves(int color)
address@hidden find_more_owl_attack_and_defense_moves
 @quotation
 Test certain moves to see whether they (too) can owl attack or
 defend an owl critical dragon. Tested moves are
@@ -946,7 +946,7 @@
 @end enumerate
 @end quotation
 @item @code{static int strategically_sound_defense(int aa, int tt)}
address@hidden static int strategically_sound_defense(int aa, int tt)
address@hidden strategically_sound_defense
 @quotation
 It's often bad to run away with a worm that is in a strategically
 weak position. This function gives heuristics for determining
@@ -954,7 +954,7 @@
 strategically sound.
 @end quotation
 @item @code{static void induce_secondary_move_reasons(int color)}
address@hidden static void induce_secondary_move_reasons(int color)
address@hidden induce_secondary_move_reasons
 @quotation
 Any move that captures or defends a worm also connects or cuts
 the surrounding dragons. Find these secondary move reasons.
@@ -964,7 +964,7 @@
 capturing has already been taken into account elsewhere.
 @end quotation
 @item @code{static void examine_move_safety(int color)}
address@hidden static void examine_move_safety(int color)
address@hidden examine_move_safety
 @quotation
 Examine the strategical and tactical safety of the moves. This is
 used to decide whether or not the stone should generate influence
@@ -973,7 +973,7 @@
 dragons. This sets the move.move_safety field.
 @end quotation
 @item @code{static float dragon_safety(int dr, int ignore_dead_dragons)}
address@hidden static float dragon_safety(int dr, int ignore_dead_dragons)
address@hidden dragon_safety
 @quotation
 An attempt to estimate the safety of a dragon. Safety values are:
 @itemize @minus
@@ -991,7 +991,7 @@
 @end itemize
 @end quotation
 @item @code{static float connection_value(int dragona, int dragonb, int tt, 
float margin)}
address@hidden static float connection_value(int dragona, int dragonb, int tt, 
float margin)
address@hidden connection_value
 @quotation
 Strategical value of connecting (or cutting) the dragon at (dragona)
 to the dragon at (dragonb). Notice that this function is assymetric.
@@ -1005,7 +1005,7 @@
 impact values. (See @file{value_moves.c} for more information.)
 @end quotation
 @item @code{static float adjusted_worm_attack_value(int pos, int ww)}
address@hidden static float adjusted_worm_attack_value(int pos, int ww)
address@hidden adjusted_worm_attack_value
 @quotation
 Usually the value of attacking a worm is twice its effective size,
 but when evaluating certain move reasons we need to adjust this to
@@ -1024,44 +1024,44 @@
 most one adjustment of each type.
 @end quotation
 @item @code{static void estimate_territorial_value(int pos, int color, float 
score)}
address@hidden static void estimate_territorial_value(int pos, int color, float 
score)
address@hidden estimate_territorial_value
 @quotation
 Estimate the direct territorial value of a move at (pos).
 @end quotation
 @item @code{static void estimate_strategical_value(int pos, int color, float 
score)}
address@hidden static void estimate_strategical_value(int pos, int color, float 
score)
address@hidden estimate_strategical_value
 @quotation
 Estimate the strategical value of a move at (pos).
 @end quotation
 @item @code{static int compare_move_reasons(const void *p1, const void *p2)}
address@hidden static int compare_move_reasons(const void *p1, const void *p2)
address@hidden compare_move_reasons
 @quotation
 Compare two move reasons, used for sorting before presentation. */
 @end quotation
 @item @code{static float value_move_reasons(int pos, int color, float 
pure_threat_value, float score)}
address@hidden static float value_move_reasons(int pos, int color, float 
pure_threat_value, float score)
address@hidden value_move_reasons
 @quotation
 Combine the reasons for a move at (pos) into a simple numerical value.
 @end quotation
 @item @code{static void value_moves(int color, float pure_threat_value, float 
score)}
address@hidden static void value_moves(int color, float pure_threat_value, 
float score)
address@hidden value_moves
 @quotation
 Loop over all possible moves and value the move reasons for each.
 @end quotation
 @item @code{static void print_top_moves(void)}
address@hidden static void print_top_moves(void)
address@hidden print_top_moves
 @quotation
 Search through all board positions for the 10 highest valued
 moves and print them.
 @end quotation
 @item @code{static void reevaluate_ko_threats(int ko_move, int color)}
address@hidden static void reevaluate_ko_threats(int ko_move, int color)
address@hidden reevaluate_ko_threats
 @quotation
 This function is called if the biggest move on board was an illegal
 ko capture.
 @end quotation
 @item @code{static void redistribute_points(void)}
address@hidden static void redistribute_points(void)
address@hidden redistribute_points
 @quotation
 Redistribute points. When one move is declared a replacement for
 another by a replacement move reason, the move values for the
Index: doc/overview.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/overview.texi,v
retrieving revision 1.6
diff -u -r1.6 overview.texi
--- doc/overview.texi   24 Feb 2002 17:40:10 -0000      1.6
+++ doc/overview.texi   19 Mar 2002 15:08:15 -0000
@@ -67,8 +67,9 @@
  7|  64  65  66  67  68  69  70  71  72
 @end example
 
-To convert between a 1D index pos and a 2D index @code{(i,j)}, the macros
address@hidden, @code{I}, and @code{J} are provided, defined as below:
+To convert between a 1D index @code{pos} and a 2D index @code{(i,j)},
+the macros @code{POS}, @code{I}, and @code{J} are provided, defined as
+below:
 
 @example
 #define POS(i, j)    ((MAX_BOARD + 2) + (i) * (MAX_BOARD + 1) + (j))
@@ -112,7 +113,7 @@
 @end example
 
 Navigation on the board is done by the @code{SOUTH}, @code{WEST},
address@hidden, and @code{EAST}macros,
address@hidden, and @code{EAST} macros,
 
 @example
 #define NS           (MAX_BOARD + 1)
@@ -141,8 +142,9 @@
 one is useful for assertion tests.
 
 @strong{Important}: The 2D coordinate @code{(-1,-1)}, which is used for
-pass and sometimes to indicate no point, maps to the 1D coordinate 0,
-not to -1.
+pass and sometimes to indicate no point, maps to the 1D coordinate
address@hidden, not to @code{-1}. Instead of a plain @code{0}, use one of the
+macros @code{NO_MOVE} or @code{PASS_MOVE}.
 
 A loop over multiple directions is straightforwardly written:
 
@@ -157,7 +159,7 @@
 allocation of arrays with a 1-1 mapping to the board.
 
 @example
-#define BOARDSIZE    ((MAX_BOARD + 2) * (MAX_BOARD + 1))
+#define BOARDSIZE    ((MAX_BOARD + 2) * (MAX_BOARD + 1) + 1)
 #define BOARDMIN     (MAX_BOARD + 2)
 #define BOARDMAX     (MAX_BOARD + 1) * (MAX_BOARD + 1)
 @end example
@@ -174,7 +176,7 @@
   int m, n;
   for (m = 0; m < board_size; m++)
     for (n = 0; n < board_size; n++) @{
-        do_something(POS(m, n));
+      do_something(POS(m, n));
     @}
 @end example
 
@@ -184,7 +186,7 @@
   int pos;
   for (pos = BOARDMIN; pos < BOARDMAX; pos++) @{
     if (ON_BOARD(pos))
-        do_something(pos);
+      do_something(pos);
   @}
 @end example
 
@@ -193,7 +195,7 @@
 @section Move Generation Basics
 @cindex move generation
 
-The engine of GNU Go takes a positions and a color to move and
+The engine of GNU Go takes a position and a color to move and
 generates the (supposedly) optimal move.  This is done by the function
 @code{genmove()} in @file{engine/genmove.c}.
 @findex genmove
@@ -201,9 +203,9 @@
 The move generation is done in three passes:
 
 @enumerate
address@hidden information gathering
address@hidden different modules propose moves
address@hidden The values of the moves are weighted together and the best move 
is selected
address@hidden Information gathering.
address@hidden Different modules propose moves.
address@hidden The values of the moves are weighted together and the best move 
is selected.
 @end enumerate
 
 @subsection Information gathering
@@ -214,7 +216,7 @@
 which will be discussed in greater detail in the next section.
 Such information could be life and death of the groups, information
 about moyos, connection of groups and so on. Information gathering is
-performed by @code{examine_position}, which in turn calls:
+performed by @code{examine_position()}, which in turn calls:
 
 @itemize @bullet
 @item @code{make_worms()}
@@ -353,7 +355,7 @@
 are selected by the function @code{review_move_reasons}. This
 function also does some analysis to try to turn up other moves
 which may have been missed. The modules @code{revise_semeai()} and
address@hidden are only run if no good move has been
address@hidden()} are only run if no good move has been
 discovered by the other modules.
 
 @node  Examining the Position, Sequence of Events, Move Generation Basics, 
Overview
@@ -482,10 +484,11 @@
 
 The GNU Go engine is contained in two directories, @file{engine/} and
 @file{patterns/}. Code related to the user interface, reading and
-writing of smart go format files and testing are found in 
-the directories @file{interface/}, @file{sgf/}, and
address@hidden/}. Code borrowed from other GNU programs is
-contained in @file{utils/}. Documentation is in @file{doc/}.
+writing of smart go format files, and testing are found in the
+directories @file{interface/}, @file{sgf/}, and @file{regression/}. Code
+borrowed from other GNU programs is contained in @file{utils/}. That
+directory also includes some code developed within GNU Go which is not
+go specific. Documentation is in @file{doc/}.
 
 In this document we will describe some of the individual files comprising
 the engine code in @file{engine/} and @file{patterns/}. In @file{interface/} 
@@ -930,7 +933,7 @@
 root directory @file{gnugo-3.2.x/} and execute the command:
 
 @example
-find . -print|grep "\.[ch]$"|xargs etags
+find . -print|grep "\.[ch]$" | xargs etags
 @end example
 
 This will build a file called @file{gnugo-3.2.x/TAGS}. Now to
Index: doc/sgf.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/sgf.texi,v
retrieving revision 1.5
diff -u -r1.5 sgf.texi
--- doc/sgf.texi        10 Mar 2002 16:37:05 -0000      1.5
+++ doc/sgf.texi        19 Mar 2002 15:08:16 -0000
@@ -487,14 +487,14 @@
 
 @item @code{SGFNode *sgftreeCircle  (SGFTree *tree, SGFNode *node, int
 i, int j)}
address@hidden sgftreeCircle  
address@hidden sgftreeCircle
 @quotation
 Add a circle property at @code{(i, j)} to the tree.
 @end quotation
 
 @item @code{SGFNode *sgftreeSquare  (SGFTree *tree, SGFNode *node, int
 i, int j)}
address@hidden sgftreeSquare  
address@hidden sgftreeSquare
 @quotation
 Add a square property at @code{(i, j)} to the tree.
 @end quotation
@@ -507,7 +507,7 @@
 @end quotation
 
 @item @code{SGFNode *sgftreeMark(SGFTree *tree, SGFNode *node, int i, int j)}
address@hidden sgftreeMark    
address@hidden sgftreeMark
 @quotation
 Add a mark property at @code{(i, j)} to the tree.
 @end quotation
Index: doc/using.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/using.texi,v
retrieving revision 1.5
diff -u -r1.5 using.texi
--- doc/using.texi      24 Feb 2002 17:40:10 -0000      1.5
+++ doc/using.texi      19 Mar 2002 15:08:16 -0000
@@ -408,11 +408,11 @@
 (@pxref{Reading Basics}).
 
 @itemize @bullet
address@hidden @option{owl-branch} Below this depth Owl only considers one 
move. Default 8.
address@hidden @option{owl-reading} Below this depth Owl assumes the dragon has 
escaped.
address@hidden @option{--owl-branch} Below this depth Owl only considers one 
move. Default 8.
address@hidden @option{--owl-reading} Below this depth Owl assumes the dragon 
has escaped.
 Default 20.
address@hidden @option{owl-node-limit} If the number of variations exceeds this 
limit,
-Owl assumes the dragon can make life. Default 10000.  We caution the user that
address@hidden @option{--owl-node-limit} If the number of variations exceeds 
this limit,
+Owl assumes the dragon can make life. Default 1000.  We caution the user that
 increasing @code{owl_node_limit} does not necessarily increase the strength of
 the program.
 @item @option{--level @var{amount}}
@@ -455,7 +455,7 @@
 Move 13 (white): GNU Go plays C6 (20.60) - Game move F4 (20.60) 
 @end example
 
-This option is useful if one wants to confirm that a change such as an
+This option is useful if one wants to confirm that a change such as a
 speedup or other optimization has not affected the behavior of the
 engine. Note that when the several moves have the same top value (or
 nearly equal) the move generated is not deterministic (though it can be
Index: doc/utils.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/utils.texi,v
retrieving revision 1.5
diff -u -r1.5 utils.texi
--- doc/utils.texi      10 Mar 2002 09:42:44 -0000      1.5
+++ doc/utils.texi      19 Mar 2002 15:08:16 -0000
@@ -354,12 +354,12 @@
 A wrapper around @code{abort()} which shows the state variables at the time
 of the problem. @code{(i, j)} are typically a related move, or @code{(-1, -1)}.
 @end quotation
address@hidden @code{const char * color_to_string(int color)}
address@hidden @code{const char *color_to_string(int color)}
 @findex color_to_string
 @quotation
 Convert a color value to a string.
 @end quotation
address@hidden @code{const char * location_to_string(int pos)}
address@hidden @code{const char *location_to_string(int pos)}
 @findex location_to_string
 @quotation
 Convert a location to a string.
@@ -369,22 +369,22 @@
 @quotation
 Convert a location to a string, writing to a buffer
 @end quotation
address@hidden @code{const char * status_to_string(int status)}
address@hidden @code{const char *status_to_string(int status)}
 @findex status_to_string
 @quotation
 Convert a status value to a string.
 @end quotation
address@hidden @code{const char * safety_to_string(int status)}
address@hidden @code{const char *safety_to_string(int status)}
 @findex safety_to_string
 @quotation
 Convert a safety value to a string.
 @end quotation
address@hidden @code{const char * routine_to_string(int routine)}
address@hidden @code{const char *routine_to_string(int routine)}
 @findex routine_to_string
 @quotation
 Convert a routine to a string.
 @end quotation
address@hidden @code{const char * result_to_string(int result)}
address@hidden @code{const char *result_to_string(int result)}
 @findex result_to_string
 @quotation
 Convert a read result to a string.