[gnugo-devel] Doc patch

[Gunnar Farneback]

Here's a doc patch, mostly with improved markup.

A question: Should KO_A be tagged as @code{KO_A} or not? Current use
is inconsistent. The same goes of course for KO_B and WIN. The
situation for DEAD, ALIVE, CRITICAL and UNKNOWN is similar.

/Gunnar

Index: doc/owl.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/owl.texi,v
retrieving revision 1.5
diff -u -r1.5 owl.texi
--- doc/owl.texi        4 Mar 2002 06:49:08 -0000       1.5
+++ doc/owl.texi        10 Mar 2002 07:47:44 -0000
@@ -167,10 +167,10 @@
 @item @code{void owl_analyze_semeai(int apos, int bpos, int *resulta, int 
*resultb, int *move, int owl)}
 @findex owl_analyze_semeai
 @quotation
-Called when (apos) and (bpos) point to adjacent dragons
-of the opposite color, both with matcher_status DEAD or
+Called when @code{apos} and @code{bpos} point to adjacent dragons
+of the opposite color, both with @code{matcher_status} DEAD or
 CRITICAL, analyzes the semeai, assuming that the player
-of the (apos) dragon moves first.
+of the @code{apos} dragon moves first.
 @end quotation
 @item @code{int owl_attack(int target, int *attack_point, int *certain)}
 @findex owl_attack
@@ -180,7 +180,7 @@
 @code{attack_point} can be a null pointer if only the result is needed.
 The array goal marks the extent of the dragon. This must
 be maintained during reading. Call this function only when
address@hidden; otherwise you can call do_owl_attack but you must
address@hidden; otherwise you can call @code{do_owl_attack} but you must
 set up the goal and boundary arrays by hand first.
 @end quotation
 @item @code{int owl_threaten_attack(int target, int *attack1, int *attack2)}
@@ -267,7 +267,7 @@
 @item @code{int owl_topological_eye(int pos, int color)}
 @findex owl_topological_eye
 @quotation
-Retrieve topological eye values stored in the half_eye[] array of
+Retrieve topological eye values stored in the @code{half_eye[]} array of
 the current owl data.
 @end quotation
 @end itemize
Index: doc/patterns.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/patterns.texi,v
retrieving revision 1.8
diff -u -r1.8 patterns.texi
--- doc/patterns.texi   4 Mar 2002 06:49:08 -0000       1.8
+++ doc/patterns.texi   10 Mar 2002 07:47:44 -0000
@@ -353,28 +353,28 @@
 As an example to show how to write a helper function, we consider
 a hypothetical helper called @code{wedge_helper}. Such a helper
 used to exist, but has been replaced by a constraint. Due to
-its simplicity it's still a good example.) The helper begins with a
+its simplicity it's still a good example. The helper begins with a
 comment:
 
 @example
 /*
 
 ?O.           ?Ob
-.X*           aXt
+.X*           aX*
 ?O.           ?Oc
 
 :8,C,wedge_helper
 */
 @end example
 
-The image on the left is the actual pattern. On the right we've
-taken this image and added letters to label (ti, tj), (ai, aj)
-and (bi, bj). Of course t is always at *, the point where GNU
-Go will move if the pattern is adopted.
+The image on the left is the actual pattern. On the right we've taken
+this image and added letters to label @code{apos}, @code{bpos}, and
address@hidden The position of *, the point where GNU Go will move if the
+pattern is adopted, is passed through the parameter @code{move}.
 
 @example
 int 
-wedge_helper (ARGS)
+wedge_helper(ARGS)
 @{
   int apos, bpos, cpos;
   int other = OTHER_COLOR(color);
@@ -409,7 +409,7 @@
 @code{TRYMOVE} macro to place an @samp{O} at @samp{move} and let
 @samp{X} draw back to @samp{a}. Then we ask whether @samp{O} can capture
 these stones by calling @code{attack()}. The test if there is a stone at
-a before calling @code{attack()} is in this position not really
address@hidden before calling @code{attack()} is in this position not really
 necessary but it's good practice to do so, because if the attacked stone
 should happen to already have been captured while placing stones, GNU Go
 would crash with an assertion failure.
@@ -703,7 +703,7 @@
 experiments in the constraints. All of them work so that first the
 sequence of moves @samp{a},@samp{b},@samp{c},... is played through with
 alternating colors, starting with @samp{X} or @samp{O} as indicated by
-the name. Then it is tested whether the worm at z can be attacked or
+the name. Then it is tested whether the worm at @samp{z} can be attacked or
 defended, respectively. It doesn't matter who would be in turn to move,
 a worm of either color may be attacked or defended. For attacks the
 opposite color of the string being attacked starts moving and for
@@ -711,7 +711,7 @@
 worm cannot be attacked in the position or if it can be attacked but
 also defended.  The attack functions return true if there is a way to
 capture the worm, whether or not it can also be defended. If there is no
-stone present at z after the moves have been played, it is assumed that
+stone present at @samp{z} after the moves have been played, it is assumed that
 an attack has already been successful or a defense has already failed.
 If some of the moves should happen to be illegal, typically because it
 would have been suicide, the following moves are played as if nothing
@@ -737,20 +737,20 @@
 
 These functions are similar to the previous ones. The difference is
 that the last *two* arguments denote worms to be attacked or defended
-simultaneously. Obviously y and z must have the same color. If either
+simultaneously. Obviously @samp{y} and @samp{z} must have the same color. If 
either
 location is empty, it is assumed that an attack has been successful or
 a defense has failed. The typical use for these functions is in
 cutting patterns, where it usually suffices to capture either
 cutstone.
 
 The function @code{xplay_defend_both} plays alternate moves
-beginning with an X at @samp{a}. Then it passes the last
+beginning with an @samp{X} at @samp{a}. Then it passes the last
 two arguments to @code{defend_both} in
 @file{engine/utils.c}. This function checks to determine
 whether the two strings can be simultaneously defended.
 
 The function @code{xplay_attack_either} plays alternate
-moves beginning with an X move at @samp{a}. Then it passes
+moves beginning with an @samp{X} move at @samp{a}. Then it passes
 the last two arguments to @code{attack_either} in
 @file{engine/utils.c}. This function looks for a move
 which captures at least one of the two strings. In its
@@ -819,7 +819,7 @@
 @code{marginal_eye(x)}
 @end example
 
-True if x is an eye space for either color, a non-marginal eye space
+True if @samp{x} is an eye space for either color, a non-marginal eye space
 for either color, or a marginal eye space for either color,
 respectively.
 
@@ -827,7 +827,7 @@
 @code{antisuji(x)}
 @end example
 
-Tell the move generation that x is a substandard move that never should
+Tell the move generation that @samp{x} is a substandard move that never should
 be played.
 
 @example
@@ -835,7 +835,7 @@
 same_worm(x,y)
 @end example
 
-Return true if x and y are the same dragon or worm respectively.
+Return true if @samp{x} and @samp{y} are the same dragon or worm respectively.
 
 @example
 @code{dragonsize(x)}
@@ -871,7 +871,7 @@
 @code{potential_cutstone(x)}
 @end example
 
-True if cutstone2 field from worm data is larger than one. This
+True if @code{cutstone2} field from worm data is larger than one. This
 indicates that saving the worm would introduce at least two new
 cutting points.
 
@@ -882,7 +882,7 @@
 Prevents the misreporting of @samp{x} as lunch for @samp{y}.
 For example, the following pattern tells GNU Go that even
 though the stone at @samp{a} can be captured, it should not
-be considered "lunch" for the dragon at @samp{b}, because
+be considered ``lunch'' for the dragon at @samp{b}, because
 capturing it does not produce an eye:
 
 @example
@@ -913,7 +913,7 @@
 @code{amalgamate_most_valuable(x,y,z)}
 @end example
 
-Called when (x,y,z) point to three (preferably distinct)
+Called when @samp{x}, @samp{y}, @samp{z} point to three (preferably distinct)
 dragons, in situations such as this:
 
 @example
@@ -924,7 +924,7 @@
 
 @end example
 
-In this situation, the opponent can play at *, preventing
+In this situation, the opponent can play at @samp{*}, preventing
 the three dragons from becoming connected. However @samp{O}
 can decide which cut to allow. The helper amalgamates the
 dragon at @samp{y} with either @samp{x} or @samp{z}, 
@@ -971,9 +971,7 @@
 @end example
 
 Returns the escape value at @samp{x}. This is only useful in owl
-attack and defense patterns and only if the
address@hidden option is turned on. Otherwise 0 is
-returned.
+attack and defense patterns.
 
 @node  Attack and Defense DB, Connections Database, Autohelper Functions, 
Patterns
 @comment  node-name,  next,  previous,  up
@@ -997,7 +995,7 @@
 For each @samp{X} worm in the pattern, it's tested whether the move
 at @samp{*} captures the worm. If that is the case, this is
 registered as a reason for the move at @samp{*}. The attack point of
-the worm is set to * and if it wasn't attacked before, a
+the worm is set to @samp{*} and if it wasn't attacked before, a
 defense is searched for.
 @end table
 
@@ -1078,7 +1076,7 @@
 X.OO
 @end example
 @noindent
-The previous pattern is matched here twice, yet X can push
+The previous pattern is matched here twice, yet @samp{X} can push
 in and break one of the connections. To fix this, we include
 a pattern:
 
@@ -1116,7 +1114,7 @@
         struct pattern *pattern, int ll, void *data)}
 @findex cut_connect_callback
 @quotation
-Try to match all (permutations of) connection patterns at (m,n).
+Try to match all (permutations of) connection patterns at @code{(m,n)}.
 For each match, if it is a B pattern, set cutting point in worm
 data structure and make eye space marginal for the connection
 inhibiting entries of the pattern. If it is a C pattern, amalgamate
@@ -1168,19 +1166,19 @@
 ``tuning'' them. Here are some suggestions.
 
 If you want to experiment with modifying the pattern database, invoke
-with the -a option. This will cause every pattern to be evaluated,
+with the @option{-a} option. This will cause every pattern to be evaluated,
 even when some of them may be skipped due to various optimizations.
 
 You can obtain a Smart Go Format (SGF) record of your game in at least
 two different ways. One is to use CGoban to record the game. You can
-also have GNU Go record the game in Smart Go Format, using the -o
-option. It is best to combine this with -a. Do not try to read the SGF
+also have GNU Go record the game in Smart Go Format, using the @option{-o}
+option. It is best to combine this with @option{-a}. Do not try to read the SGF
 file until the game is finished and you have closed the game
 window. This does not mean that you have to play the game out to its
 conclusion. You may close the CGoban window on the game and GNU Go
 will close the SGF file so that you can read it.
 
-If you record a game in SGF form using the -o option, GNU Go will add
+If you record a game in SGF form using the @option{-o} option, GNU Go will add
 labels to the board to show all the moves it considered, with their
 values. This is an extremely useful feature, since one can see at a
 glance whether the right moves with appropriate weights are being
@@ -1207,7 +1205,7 @@
 digits. Grab the lower right margin of the CGoban window and pull it
 until the window is large. All three digits should be visible.
 
-If you are playing a game without the -o option and you wish to
+If you are playing a game without the @option{-o} option and you wish to
 analyze a move, you may still use CGoban's ``Save Game'' button to get
 an SGF file. It will not have the values of the moves labelled, of
 course.
@@ -1228,9 +1226,9 @@
 emacs, it's a good idea to run GNU Go in a shell in a buffer (M-x
 shell) since this gives good navigation and search facilities.
 
-Instead of a move number, you can also give a board coordinate to -L
+Instead of a move number, you can also give a board coordinate to @option{-L}
 in order to stop at the first move played at this location. If you
-omit the -L option, the move after those in the file will be
+omit the @option{-L} option, the move after those in the file will be
 considered. 
 
 If a bad move is proposed, this can have several reasons. To begin
@@ -1256,7 +1254,8 @@
 effectively connected, there may be missing patterns in @file{conn.db}.
 Similarly, worms may be incorrectly amalgamated due to some too
 general or faulty pattern in @file{conn.db}. To get trace output from the
-matching of patterns in @file{conn.db} you need to add a second -t option.
+matching of patterns in @file{conn.db} you need to add a second
address@hidden option.
 
 If a move reason is missing, there may be a hole in the database. It
 could also be caused by some existing pattern being needlessly
@@ -1300,7 +1299,7 @@
 actual points on the board. These values are also additive so the same
 care must be taken to avoid unintended multiple matches.
 
-You can also get a visual display of the dragons using the -T
+You can also get a visual display of the dragons using the @option{-T}
 option. The default GNU Go configuration tries to build a
 version with color support using either curses or the
 ansi escape sequences. You are more likely to find color
@@ -1332,7 +1331,7 @@
 
 If you want to get the same game over and over again, you can
 eliminate the randomness in GNU Go's play by providing a fixed
-random seed with the -r option.
+random seed with the @option{-r} option.
 
 
 @node PM Implementation, Symmetry & transformations, Tuning, Patterns
@@ -1354,12 +1353,12 @@
 Each pattern is compiled to a header, and a sequence of elements,
 which are (notionally) checked sequentially at every position and
 orientation of the board. These elements are relative to the pattern
-'anchor' (or origin).  One X or O stone is (arbitrarily) chosen to
+'anchor' (or origin).  One @samp{X} or @samp{O} stone is (arbitrarily) chosen 
to
 represent the origin of the pattern. (We cannot dictate one or the
 other since some patterns contain only one colour or the other.)  All
 the elements are in co-ordinates relative to this position. So a
-pattern matches "at" board position (m,n,o) if the the pattern anchor
-stone is on (m,n), and the other elements match the board when the
+pattern matches "at" board position @code{(m,n,o)} if the the pattern anchor
+stone is on @code{(m,n)}, and the other elements match the board when the
 pattern is transformed by transformation number @samp{o}. (See below for
 the details of the transformations, though these should not be
 necessary)
@@ -1418,7 +1417,8 @@
 can choose to reflect about the axis of symmetry (which causes no
 net change) and can therefore conclude that each of e-h is
 equivalent to the reflection (no-op) followed by a-d.  This argument
-therefore extends to include - and / as well as | and \.
+therefore extends to include @samp{-} and @samp{/} as well as @samp{|}
+and @samp{\}.
 
 @node  Details, grid optimization, Symmetry & transformations, Patterns
 @comment  node-name,  next,  previous,  up
@@ -1428,11 +1428,11 @@
 @cindex grid optimization
 
 @enumerate
address@hidden An entry in the pattern header states whether the anchor is an X 
or
-an O. This helps performance, since all transformations can be
address@hidden An entry in the pattern header states whether the anchor is an 
@samp{X} or
+an @samp{O}. This helps performance, since all transformations can be
 rejected at once if the anchor stone does not match. (Ideally, we
-could just define that the anchor is always O or always X, but some
-patterns contain no O's and some contain no X's.)
+could just define that the anchor is always @samp{O} or always @samp{X}, but 
some
+patterns contain no @samp{O} and some contain no @samp{X}.)
 
 @item The pattern header contains the size of the pattern (ie the
 co-ordinates of the top left and bottom right elements) relative to
@@ -1467,7 +1467,7 @@
 
 @item The actual tests are performed using an 'and-compare'
 sequence. Each board position is a 2-bit quantity.
-%00 for empty, %01 for O, %10 for X.
+%00 for empty, %01 for @samp{O}, %10 for @samp{X}.
 We can test for an exact match by and-ing with %11 (no-op),
 then comparing with 0, 1 or 2. The test for @samp{o} is the
 same as a test for 'not-X', ie not %10. So and with %01
Index: doc/reading.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/reading.texi,v
retrieving revision 1.6
diff -u -r1.6 reading.texi
--- doc/reading.texi    4 Mar 2002 06:49:08 -0000       1.6
+++ doc/reading.texi    10 Mar 2002 07:47:44 -0000
@@ -83,7 +83,7 @@
 
 Depth of reading is controlled by the parameters @code{depth}
 and @code{branch_depth}. The @code{depth} has a default value
address@hidden (in @file{liberty.h}), which is set to 14 in the
address@hidden (in @file{liberty.h}), which is set to 16 in the
 distribution, but it may also be set at the command line using
 the @option{-D} or @option{--depth} option.  If @code{depth} is
 increased, GNU Go will be stronger and slower. GNU Go will read
@@ -108,7 +108,7 @@
 @code{small_semeai()} (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 10. Below
+The @code{backfill_depth} is a similar variable with a default 12. Below
 this depth, GNU Go will try "backfilling" to capture stones.
 For example in this situation:
 
@@ -127,7 +127,7 @@
 parameter @code{backfill_depth} may be set using the @option{-B}
 option.
 
-The @code{fourlib_depth} is a parameter with a default of only 5.
+The @code{fourlib_depth} is a parameter with a default of only 7.
 Below this depth, GNU Go will try to attack strings with
 four liberties. The @code{fourlib_depth} may be set using the
 @option{-F} option.
@@ -187,7 +187,7 @@
 
 @cindex Hashing of positions
 @cindex Reading optimisation
address@hidden speedup of reading process
address@hidden Speedup of reading process
 @cindex Zobrist hashing algorithm
 @cindex Transposition table
 
@@ -728,39 +728,39 @@
 other one, so we allow this.
 
 If the komaster's opponent takes a ko, then both players have taken
-one ko. In this case `komaster' is set to GRAY and after this further
+one ko. In this case @code{komaster} is set to @code{GRAY} and after this 
further
 ko captures are not allowed.
 
 If the ko at @code{kom_pos} is filled, then the komaster
-reverts to EMPTY.
+reverts to @code{EMPTY}.
 
 The komaster scheme may be summarized as follows. It is assumed
 that @samp{O} is about to move.
 
 @itemize @bullet
address@hidden 1. Komaster is EMPTY.
address@hidden 1. Komaster is @code{EMPTY}.
 @itemize @minus
address@hidden Unconditional ko capture is allowed. Komaster remains EMPTY.
address@hidden Unconditional ko capture is allowed. Komaster remains 
@code{EMPTY}.
 @item Conditional ko capture is allowed. Komaster is set to @samp{O} and
 @code{kom_pos} to the location of the ko, where a stone was
 just removed.
 @end itemize
address@hidden Komaster is O:
address@hidden Komaster is @samp{O}:
 @itemize @minus 
 @item Only nested ko captures are allowed.
 @item If komaster fill the ko at @code{kom_pos} then komaster reverts to
-EMPTY.
address@hidden
 @end itemize
address@hidden Komaster is X:
address@hidden Komaster is @samp{X}:
 @itemize @minus
 @item
 Play at @code{kom_pos} is not allowed. Any other ko capture
-is allowed. If @samp{O} takes another ko, komaster becomes GRAY.
+is allowed. If @samp{O} takes another ko, komaster becomes @code{GRAY}.
 @end itemize
address@hidden Komaster is GRAY:
address@hidden Komaster is @code{GRAY}:
 @itemize @minus
 @item Ko captures are not allowed. If the ko at @code{kom_pos} is
-filled then the komaster reverts to EMPTY.
+filled then the komaster reverts to @code{EMPTY}.
 @end itemize
 @end itemize
 
@@ -836,7 +836,7 @@
 @end group
 @end example
 
-W takes the ko at B3 after which the komaster is GRAY and
+W takes the ko at B3 after which the komaster is @code{GRAY} and
 ko recaptures are not allowed.
 
 @example
@@ -855,7 +855,7 @@
 @end group
 @end example
 
-Since X is not allowed any ko recaptures, there is nothing
+Since B is not allowed any ko recaptures, there is nothing
 he can do and he is found dead. Thus the komaster scheme
 produces the correct result.
 
@@ -865,7 +865,7 @@
 @section Another Ko Example
 
 We now consider an example to show why the komaster is reset
-to EMPTY if the ko is resolved in the komaster's favor. This
+to @code{EMPTY} if the ko is resolved in the komaster's favor. This
 means that the ko is filled, or else that is becomes no longer
 a ko and it is illegal for the komaster's opponent to play
 there.
@@ -894,7 +894,7 @@
 gnugo -l ko5.sgf --quiet --decidestring L1 -o vars.sgf
 @end example
 
-The correct resolution is that H1 attacks L1 while K2
+The correct resolution is that H1 attacks L1 unconditionally while K2
 defends it with ko (code KO_A).
 
 After Black (X) takes the ko at K3, white can do nothing
@@ -1045,50 +1045,55 @@
 @item @code{int attack(int str, int *move)}
 @findex attack
 @quotation
-Determines if the string at (str) can be captured, and if so, (*move) returns
-the attacking move, unless (move) is a null pointer. Use a null pointer if you
-are interested in the result of the attack but not the attacking move itself.
+Determines if the string at @code{str} can be captured, and if so,
address@hidden returns the attacking move, unless @code{move} is a null
+pointer. Use a null pointer if you are interested in the result of the
+attack but not the attacking move itself.
 @end quotation
 @item @code{int find_defense(int str, int *move)}
 @findex find_defense
 @quotation
-Attempts to find a move that will save the string at (str). It returns WIN if
-such a move is found, with (*move) the location of the saving move, unless
-(move) is a null pointer. It is not checked that tenuki defends, so this may
-give an erroneous answer if !attack(str).
+Attempts to find a move that will save the string at @code{str}. It
+returns WIN if such a move is found, with @code{*move} the location 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
address@hidden(str)}.
 @end quotation
 @item @code{int attack_and_defend(int str, int *attack_code, int 
*attack_point, int *defend_code, int *defense_point)}
 @findex attack_and_defend
 @quotation
-This is a frontend to the @code{attack()} and @code{find_defense()} functions,
-which guarantees a consistent result. If a string cannot be attacked, 0 is
-returned and acode is 0. If a string can be attacked and defended, @code{WIN}
-is returned, acode and dcode are both non-zero, and (attack_point),
-(defense_point) both point to vertices on the board. If a string can be
-attacked but not defended, 0 is again returned, acode is non-zero, dcode is 0,
-and (attack_point) points to a vertex on the board. This function in
+This is a frontend to the @code{attack()} and @code{find_defense()}
+functions, which guarantees a consistent result. If a string cannot be
+attacked, 0 is returned and @code{*attack_code} is 0. If a string can be
+attacked and defended, @code{WIN} is returned, @code{*attack_code} and
address@hidden are both non-zero, and @code{*attack_point},
address@hidden both point to vertices on the board. If a string
+can be attacked but not defended, 0 is again returned,
address@hidden is non-zero, @code{*defend_code} is 0, and
address@hidden points to a vertex on the board. This function in
 particular guarantees that if there is an attack, it will never return
address@hidden@code{NO_MOVE}, which means the string is safe without
-defense. Separate calls to @code{attack()} and @code{find_defense()} may
-occasionally give this result, due to irregularities introduced by the
-persistent reading cache.
address@hidden = NO_MOVE}, which means the string is safe
+without defense. Separate calls to @code{attack()} and
address@hidden()} may occasionally give this result, due to
+irregularities introduced by the persistent reading cache.
 @end quotation
 @item @code{int attack_either(int astr, int bstr)}
 @findex attack_either
 @quotation
-Returns true if there is a move which guarantees that at least one of the
-strings (astr) and (bstr) can be captured. A typical application for this is
-in connection patterns, where after a cut it suffices to capture one of the
-cutting stones. The current implementation only looks for uncoordinated
-attacks. This is insufficient to find double ataris or 
-moves such as @samp{a} in positions like
+Returns true if there is a move which guarantees that at least one of
+the strings @code{astr} and @code{bstr} can be captured. A typical
+application for this is in connection patterns, where after a cut it
+suffices to capture one of the cutting stones. The current
+implementation only looks for uncoordinated attacks. This is
+insufficient to find double ataris or moves such as @samp{a} in
+positions like
 @example
        XOOOOOOOX
        XOXXOXXOX
        XX..a..XX
        ---------
 @end example
-where neither of the threatened X stones can be captured outright.
+where neither of the threatened @samp{X} stones can be captured outright.
 Still either can be captured by a move down to @samp{a}.
 @end quotation
 @item @code{int defend_both(int astr, int bstr)}
@@ -1104,31 +1109,33 @@
 @item @code{int break_through(int apos, int bpos, int cpos)}
 @findex break_through
 @quotation
-returns WIN if a position can succesfully be broken through and CUT if it can
-be cut. The position is assumed to have the shape (the colors may be reversed)
+returns @code{WIN} if a position can succesfully be broken through and
address@hidden if it can be cut. The position is assumed to have the shape
+(the colors may be reversed)
 @example
 .O.       dbe
 OXO       aFc
 @end example
-It is X to move and try to capture at least one of a, b, and c. If
-this succeeds, X is said to have broken through the position.
-Otherwise X may try to cut through the position, which means
-keeping F safe and getting a tactically safe string at either d or
-e. @strong{Important}: a, b, and c must be given in the correct order.
+It is @samp{X} to move and try to capture at least one of @samp{a},
address@hidden, and @samp{c}. If this succeeds, @samp{X} is said to have
+broken through the position. Otherwise @samp{X} may try to cut through
+the position, which means keeping @samp{F} safe and getting a tactically
+safe string at either @samp{d} or @samp{e}. @strong{Important}:
address@hidden, @samp{b}, and @samp{c} must be given in the correct order.
 @end quotation
 @item @code{int attack_threats(int str, int max_points, int moves[], int 
codes[])}
 @findex attack_threats
 @quotation
-Return up to max_threats threats to capture the string at str. If the string
-is directly attackable the number of threats is reported to be 0. NOTE: You
-can call attack_threats with moves[] and codes[] already partly filled in. So
-if you want to get the threats from scratch, you have to set them to 0
-yourself.
+Return up to max_threats threats to capture the string at @code{str}. If
+the string is directly attackable the number of threats is reported to
+be 0. NOTE: You can call attack_threats with @code{moves[]} and
address@hidden already partly filled in. So if you want to get the
+threats from scratch, you have to set them to 0 yourself.
 @end quotation
 @item @code{int safe_move(int move, int color)}
 @findex safe_move
 @quotation
-Checks whether a move at (move) is illegal or can immediately be captured. If
+Checks whether a move at @code{move} is illegal or can immediately be 
captured. If
 @code{stackp==0} the result is cached. If the move only can be captured by a
 ko, it's considered safe.
 @end quotation
Index: doc/utils.texi
===================================================================
RCS file: /cvsroot/gnugo/gnugo/doc/utils.texi,v
retrieving revision 1.4
diff -u -r1.4 utils.texi
--- doc/utils.texi      4 Mar 2002 06:49:08 -0000       1.4
+++ doc/utils.texi      10 Mar 2002 07:47:44 -0000
@@ -22,31 +22,31 @@
 @item @code{void change_matcher_status(int dr, int status)}
 @findex change_matcher_status
 @quotation
-Change the status of all the stones in the dragon at (dr).
+Change the status of all the stones in the dragon at @code{dr}.
 @end quotation
 @item @code{int defend_against(int move, int color, int apos)}
 @findex defend_against
 @quotation
-Check whether a move at (move) stops the enemy from playing at (apos).
+Check whether a move at @code{move} stops the enemy from playing at (apos).
 @end quotation
 @item @code{int cut_possible(int pos, int color)}
 @quotation
-Returns true if color can cut at (pos), or if connection through (pos)
-is inhibited. This information is collected by find_cuts(), using the B
+Returns true if color can cut at @code{pos}, or if connection through 
@code{pos}
+is inhibited. This information is collected by @code{find_cuts()}, using the B
 patterns in the connections database.
 @end quotation
 @item @code{int does_attack(int move, int str)}
 @findex does_attack
 @quotation
-returns true if the move at (move) attacks (str). This means that it captures
-the string, and that (str) is not already dead.  
+returns true if the move at @code{move} attacks @code{str}. This means that it 
captures
+the string, and that @code{str} is not already dead.  
 @end quotation
 @item @code{int does_defend(int move, int str)}
 @findex does_defend
 @quotation
-does_defend(move, str) returns true if the move at (move)
-defends (str). This means that it defends the string, and that
-(str) can be captured if no defense is made.
address@hidden(move, str)} returns true if the move at @code{move}
+defends @code{str}. This means that it defends the string, and that
address@hidden can be captured if no defense is made.
 @end quotation
 @item @code{int somewhere(int color, int last_move, ...)}
 @findex somewhere
@@ -60,7 +60,7 @@
 @quotation
 Plays a sequence of moves, alternating between the players and starting with
 color. After having played through the sequence, the three last coordinate
-pairs gives a position to be analyzed by break_through(), to see whether
+pairs gives a position to be analyzed by @code{break_through()}, to see whether
 either color has managed to enclose some stones and/or connected his own
 stones. If any of the three last positions is empty, it's assumed that the
 enclosure has failed, as well as the attempt to connect. If one or more of the
@@ -86,7 +86,7 @@
 @item @code{int play_attack_defend2_n(int color, int do_attack, int num_moves, 
...)}
 @findex play_attack_defend2_n
 @quotation
-The function play_attack_defend2_n() plays a sequence of moves, alternating
+Plays a sequence of moves, alternating
 between the players and starting with color. After having played through the
 sequence, the two last coordinate pairs give two targets to simultaneously
 attack or defend, depending on the value of do_attack. If there is no stone
@@ -100,9 +100,9 @@
 @item @code{void set_depth_values(int level)}
 @findex set_depth_values
 @quotation
-Set the various reading depth parameters. If mandated_depth_value
+Set the various reading depth parameters. If @code{mandated_depth_value}
 is not -1 that value is used; otherwise the depth values are
-set as a function of level. The parameter mandated_depth_value
+set as a function of level. The parameter @code{mandated_depth_value}
 can be set at the command line to force a particular value of
 depth; normally it is -1.
 @end quotation
@@ -147,7 +147,7 @@
 could backfire, so the function checks that no friendly worm which was
 formerly not attackable becomes attackable, and it checks that no opposing
 worm which was not defendable becomes defendable. Only worms with
-worm.size>size are checked. The arrays @code{saved_dragons[]} and 
address@hidden>size} are checked. The arrays @code{saved_dragons[]} and 
 @code{saved_worms[]} should be one for stones belonging to dragons or worms
 respectively, which are supposedly saved by @code{move}. These may be 
 @code{NULL} if no stones are supposed to gaving been saved.  For use when
@@ -252,17 +252,17 @@
 This function computes the superstring at @code{str} as described above,
 but omitting connections of type 5. Then it constructs a list of
 liberties of the superstring which are not already liberties of
address@hidden If liberty_cap is nonzero, only liberties of substrings of the
-superstring which have fewer than liberty_cap liberties are
address@hidden If @code{liberty_cap} is nonzero, only liberties of substrings 
of the
+superstring which have fewer than @code{liberty_cap} liberties are
 generated.
 @end quotation
 @item @code{void find_proper_superstring_liberties(int str, int *num_libs, int 
*libs, int liberty_cap)}
 @findex find_proper_superstring_liberties
 @quotation
-This function is the same as find_superstring_liberties, but it omits those
+This function is the same as @code{find_superstring_liberties()}, but it omits 
those
 liberties of the string @code{str}, presumably since those have already been
-treated elsewhere. If liberty_cap is nonzero, only liberties of substrings of
-the superstring which have at most liberty_cap liberties are generated.
+treated elsewhere. If @code{liberty_cap} is nonzero, only liberties of 
substrings of
+the superstring which have at most @code{liberty_cap} liberties are generated.
 @end quotation
 @item @code{void find_superstring_stones_and_liberties(int str, int 
*num_stones, int *stones, int *num_libs, int *libs, int liberty_cap)}
 @findex find_superstring_stones_and_liberties
@@ -270,16 +270,18 @@
 This function computes the superstring at @code{str} as described above,
 but omitting connections of type 5. Then it constructs a list of
 liberties of the superstring which are not already liberties of
address@hidden If liberty_cap is nonzero, only liberties of substrings of the
-superstring which have fewer than liberty_cap liberties are
address@hidden If @code{liberty_cap} is nonzero, only liberties of substrings 
of the
+superstring which have fewer than @code{liberty_cap} liberties are
 generated.
 @end quotation
-void
-superstring_chainlinks(int str, int *num_adj, int adjs[MAXCHAIN], int 
liberty_cap)
address@hidden @code{void superstring_chainlinks(int str, int *num_adj, int 
adjs[MAXCHAIN], int liberty_cap)}
address@hidden superstring_chainlinks
address@hidden
 Analogous to chainlinks, this function finds boundary chains of the
 superstring at @code{str}, including those which are boundary chains of
 @code{str} itself. If @code{liberty_cap != 0}, only those boundary chains with
 @code{<= liberty_cap} liberties are reported.
address@hidden quotation
 @item @code{void proper_superstring_chainlinks(int str, int *num_adj, int 
adjs[MAXCHAIN], int liberty_cap)}
 @findex proper_superstring_chainlinks
 @quotation
@@ -337,11 +339,11 @@
 @item @code{void  gfprintf(FILE *outfile, const char *fmt, ...)}
 @findex gfprintf
 @quotation
-Wrapper around vgprintf, writes to outfile.
+Wrapper around @code{vgprintf}, writes to outfile.
 @end quotation
 void
 mprintf(const char *fmt, ...)
-Wrapper around vgprintf, in contrast to gprintf this one
+Wrapper around @code{vgprintf}, in contrast to @code{gprintf} this one
 writes to stdout.
 TRACE(const char *fmt, ...)
 Like @code{gprintf}, but silent if the global variable @code{verbose} is
@@ -397,5 +399,3 @@
 return 0; 
 @end quotation
 @end itemize
-
-