[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnugo-devel] doc patch and structure discussion
From: |
Gunnar Farneback |
Subject: |
[gnugo-devel] doc patch and structure discussion |
Date: |
Fri, 22 Mar 2002 17:31:30 +0100 |
User-agent: |
EMH/1.14.1 SEMI/1.14.3 (Ushinoya) FLIM/1.14.2 (Yagi-Nishiguchi) APEL/10.3 Emacs/20.7 (sparc-sun-solaris2.7) (with unibyte mode) |
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
- [gnugo-devel] doc patch and structure discussion,
Gunnar Farneback <=