uligo 0.3-7 / usr / share / doc / uligo / manual.html

<div style="width:600px">

<h1>uliGo Documentation</h1>

<p>
This is the documentation for uliGo 0.3 - a program to practice Go problems. 
It was written by Ulrich Goertz (<a href="mailto:u@g0ertz.de">u@g0ertz.de</a>).
uliGo is published under the GNU General Public License (see the 
file 'gpl.txt' or look at 
<a href="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</a>).
This program comes WITHOUT ANY WARRANTY.</p>

<hr>

<h2>Contents:</h2>
<ul>
<li> <a href="#gettingstarted">Getting Started</a>
<li> <a href="#problems">Solving problems</a>
<li> <a href="#stopclock">The Stop Clock</a>
<li> <a href="#orderofproblems">The Order of Problems</a>
<li> <a href="#ownproblemdatabase">Using Your Own Problem Database</a>
<li> <a href="#replaygames">Replaing games ("guess next move")</a>
<li> <a href="#menu">The Menu</a>
<li> <a href="#miscellaneous">Miscellaneous</a>
<li> <a href="#installation">Installation</a>
<li> <a href="#history">History</a>
</ul>


<h2><a name="gettingstarted">Getting started:</a></h2>

<p>
From now on I assume that you installed the program, and that 
the main window pops up when you start it. (Otherwise, read the 
section about <a href="#installation">installing uliGo</a> first.)</p>

<p>
The first thing you have to do is to load a problem collection.
Some example collections come with uliGo; see below how you
can create your own ones. So, go to the 'File' menu, and select 'Open problem collection'.
Then choose one of the sgf files that you are shown (they are in the 'sgf'
subdirectory which should automatically be selected).
Later, the program automatically loads the collection you used last. 
Of course you can always load another collection with the 'Open problem collection'
command in the File menu.</p>

<p>
I think that the user interface is pretty self-explanatory,
so I suggest that you just play around a bit with it:
press the right arrow to see the first problem. The problem (randomly
chosen from the database) will be displayed, the stop clock 
will be started (by default you have 2 min 30 sec to find the
complete answer), and you can play your move. The indicator above the
clock (and the 'cursor') shows whose turn it is. After you
enter your move, the program automatically replies (unless
your suggested move was wrong and no refutation is contained
in the database). Then enter the next move ... when the correct
solution is reached, the program shows a 'solved' indicator on the left.
After entering a wrong move, you can still try to solve the
problem, but you cannot get credit for it anymore, of course;
instead of the green "solved" you will see a blue
one when you get to a correct solution (similarly after
using undo, the 'show solution' mode or the 'try variation' mode).</p>

<p>
With the right arrow you can go to the next problem (this works at
any stage). Note that the arrow buttons do not serve to navigate within the SGF file 
(use UNDO and HINT, respectively, to do that), but to go to the next problem, or 
back to the previous one.</p>

<p>Alternatively, if you choose 'Replay game', you can load any SGF file, and
replay it by <a href="#replaygames">guessing the next move</a>. </p>


<h2><a name="problems">Solving problems</a></h2>


<h4>Next Problem</h4>

<p>
<img src="right.gif" align=RIGHT>
This button discards the current problem, and shows the next one.
This works at any stage, no matter if you solved the current problem
correctly or not, or if you tried some variation etc.
Of course, some problem collection must be open; otherwise nothing
happens.</p>

<h4>Previous problem</h4>
<p>
<img src="left.gif" align=RIGHT>
With this button, you can go back to the previous problem. Clicking it more than once goes back further,
like with the 'back' button in a web browser.
Note though that you can't go back and forth: the 'next' button will not go back to the problem you came 
from, but will give you a new problem.</p>

<h4>Restart problem</h4>
<p><img src="reload.gif" align=RIGHT>
Go back to the beginning of the problem, and start over. 
If you are at the beginning of the problem already,
this sets up the problem again at a (possibly) different position and with different colors.</p>

<h4>Hint</h4>
<p><img src="hint.gif" align=RIGHT>
Give a hint, i.e. show the next move (and the answer). Using the Hint button results in 
this problem not being counted in the statistics, i.e. it is neither a wrong nor a correct answer.</p>

<h4>Show Solution</h4>

<p><img src="showsol.gif" align=RIGHT>
This shows a solution of the current problem. (The button is
disabled if you already solved the problem correctly yourself.)
You can choose between two modes for displaying the solution
(in the Options menu: 'Show solution mode'):</p>

<ul>
<li>animate solution: the moves of the solution are played out.
  Choose the speed in the Options menu. If there are several correct 
  solutions, one is chosen randomly.
<li> navigate solution: You can 'navigate' the underlying SGF file
  with the correct and wrong variations yourself. The possible
  variations at a given move are marked by green (correct),
  red (wrong) or blue (moves of the opponent) markers. Just click
  on one of them to choose that variation. With the Undo button
  you can undo the last move. If only red markers are displayed,
  you cannot reach the correct resolution from this point anymore - 
  you went wrong earlier. Use the Undo button to go back until
  a green marker appears.
</ul>

<p>Using the Show Solution button results in 
this problem not being counted in the statistics, i.e. it is neither a wrong nor a correct answer.
</p>

<h4>Try variation</h4>

<p><img src="tryvar.gif" align=RIGHT>
At any point, you can press this button, and then play out some
variation of your own, e.g. to convince yourself that/why something
does not work. Use the Undo button to undo a move. As long as
you are in the 'Try variation' mode, the 'Show solution' mode
is disabled - it wouldn't make sense to display the solution with
your additional stones on the board. Press 'Try variation' again
to leave this mode and remove all the stones of your variation.
Once you enter this mode, you cannot get any credit for the current
problem anymore.</p>

<h4>Undo</h4>

<p><img src="undo.gif" align=RIGHT>
With this button you can undo the last two moves (the answer to your
last move and your last move) or the last move (if there was no
answer to your last move or in the Show solution/navigate mode
or in 'Try variation' mode).
If you use the undo feature, you cannot get any credit for the 
current problem anymore.</p>


<h2><a name="stopclock">The stop clock</a></h2>

<p>
The clock starts when you press the 'next problem' button.
The default time is 150 seconds. You can change it by a
right mouse click on the clock or by choosing the 'change
clock settings' command in the options menu. This only works
when the clock is not running.</p>

<p>
Set the clock to 0 seconds to turn it off.</p>

<p>
When the time for the current problem is over, it is counted
as a wrong answer.</p>


<h2><a name="orderofproblems">How the program chooses the next problem from the database
   (in random order mode)</a></h2>

<p>
Apart from the database, the program maintains a list of all
problems, together with information how often each problem
has been asked already, and with which results (this list
is stored in the xyz.dat file, where xyz is the name of the
SGF file).</p>

<p>
When you request the next problem, a problem is chosen
randomly from the first half of the list; problems from
the first third are a little bit more likely to be chosen
then others.</p>

<p>
When you answer a problem correctly, it will be moved to
the very end of the list. So it will take some time until
that problem can come up again. When you give a wrong answer,
the problem will be moved to a random location in the 
second half (more precisely: in the 4th sixth) of the list;
so this problem cannot appear again immediately, but it
could after a relatively short time, and the more problems you
answer correctly, the more likely it is that you will asked 
problems that you got wrong once for a second time.</p>

<p>
You can erase the information on your previous answers by
deleting the .dat file corresponding to a database. A new
.dat file (in which the order of problems is that of the 
SGF file) will be created when you open the database.</p>

<p>
(In case you installed uliGo system-wide under Unix, the
.dat files are in the .uligo subdirectory of your home
directory. See the file install.txt for more details.)</p>


<h2><a name="ownproblemdatabase">Using your own problem database</a></h2>

<p>
The format used for the problem database is just the SGF format.
So in order to make your own database, just put a bunch of SGF
games in one single file. Some conventions (explained below)
have to be followed, but I think they are much or less
common sense. So probably you can just enter a problem
into any SGF editor, and everything will work.</p>

<p>
The following conventions have to be satisfied: </p>

<ul>
<li> The first node(s) of the SGF file may contain anything. If
the first node contains a GN[gamename] item, the game name is
displayed. Besides that the program ignores the nodes until
a node with an AB[] (place black stone) and/or AW[] (place white stone)
item comes up. All other AB's and AW's have to follow this node
without any interruption (the program gets confused if there is
an empty node in between). After that, the program expects
nodes with a B[] ('play black stone') or W[] ('play white stone')
item, and they must alternate properly. Two black plays in a row,
for instance, are not allowed.

<li> If you want to have 'wrong variations' in your problems (as
a refutation to some answer), the first node of that variation has 
to contain a WV ('Wrong Variation', this is not an official SGF tag) 
item or a TR[] item ('triangle label').
The triangle label option is there in order to make it
easier for you to edit problems with an arbitrary SGF editor;
just place triangle labels on the first move of a wrong variation.
Of course, that also means that no other triangle labels should
appear in the SGF files. (Other labels may appear, but are ignored
at the moment.)

<li> You can insert a general comment about the collection which
is displayed after the file is loaded, but before you look at
the first problem. Just place it at the very beginning of the
SGF file. Anything before the first '(' is considered as a general
comment. The only restriction is that your comment must not 
contain a '('.
</ul>

<p>
One final remark: since every move that is not in the SGF file
is considered wrong, it is desirable to put every correct
solution into the file. Unfortunately, it is easy to miss
some alternative moves, especially after some moves have already
been played. Certainly there are some correct alternatives
missing in the problems that come with uliGo; so don't
take it too seriously if your answer is counted as wrong
although it is right ...</p>


<h2><a name="replaygames">Replaying games ("guess next move")</a></h2>

<p>
One fun way to study go is to replay professional games by guessing the
next move. You can load an SGF file with "Replay game" in the File menu. The
 stop clock will then be replaced by a few buttons and a frame with a small 
"go board".</p>

<p>
With the buttons, you can choose if you want to guess only black or only white
moves, or both. Clicks on the board will be interpreted as guesses - if 
you managed to guess the next
move in the current SGF file, that move is played; otherwise no stone is
placed on the board.</p>

<p>
In the frame below the buttons you get some feedback on your guesses. If your
guess is right, it displays a green square (and the move is played on the 
board). If the guess is wrong, it displays a red rectangle; the rectangle is
roughly centered at the position of the next move, and the closer your
guess was, the smaller, and more accurately positioned is that rectangle. 
Furthermore the number of correct guesses and the number of all guesses, 
as well as the success percentage are given.</p>

<p>
If you just can't find the next move, you can always use the
'HINT' button, and the move will be played out. You can restart the game 
with the middle button in the first row. </p>




<h2><a name="menu">The menu</a></h2>

<h4>File - Open</h4>

<p>
Load a new problem database. A database just consists of
several SGF files. Some example databases are included in
the uliGo distribution. See below for more information how
to create your own databases.</p>

<h4>File - Statistics</h4>

<p>
Open the statistics window. It shows the name of the 
current database, how many problems are in it, how many problems 
the program has asked you to answer, and how many right/wrong 
answers you have given.</p>

<h4>File - Clear Statistics</h4>

<p>Delete all information about problems done so far, and about correct and
wrong answers, and reload the problem collection from disk. In particular,
this should be used after making changes to the SGF file with 
your problem collection.

<h4>File - Exit</h4>

<p>
Quit the program.</p>

<h4>Options - Fuzzy stone placement</h4>

<p>
In order to make the board and stones look more like 'in real
life', by default the stones are not placed precisely on the 
intersections, but by a small, random amount off. 
On a smaller board this doesn't well (and maybe some people
don't like it at all?), so you can disable this fuzzy placement.</p>

<h4>Options - Shaded stone mouse pointer</h4>

<p>
Disables the shaded stone cursor which shows where the next 
move would be if you clicked at the current position.</p>

<h4>Options - Allow color switch</h4>

<p>
In order to make sure that you don't just learn one particular
problem, but rather a shape, uliGo randomly alters the position
of the problem on the go board, and also the color of the stones.
Because the latter could cause problems if your database contains
comments referring to the colors ('good for black', 'white to move'),
you can force uliGo to use the colors of the SGF file by disabling
this option.</p>

<h4>Options - Allow mirroring/rotating</h4>

<p>
With this checkbutton, you can switch off the automatical
mirroring/rotating of the problems. That might be useful,
for example, if there are comments referring to the "upper
left" or the "right side".</p>

<h4>Options - Show solution mode</h4>

<p>
Swich between animate and navigate mode. See the description
of the 'Show solution' button above.</p>

<h4>Options - Replay speed</h4>

<p>
Choose the speed for replaying the solution (in animate mode).</p>

<h4>Options - Change clock settings</h4>

<p>
Change the maximal time for solving a problem. You can achieve
the same by right clicking on the clock. (Also see below: The 
stop clock)</p>

<h4>Options - Wrong variations</h4>

This determines what uliGo does with 'wrong variations', i.e. with wrong answers
to which a refutation is given in the SGF file. You can choose if uliGo should 
tell you your move was wrong immediately when entering the variation, or only at the end of the refutation,
or if uliGo should not descend into wrong variations at all, i.e. 
just show that the move was wrong and take it back.

<h4>Options - Random/sequential order mode</h4>

<p>
Choose if the problems should be presented in</p>

<ul>
<li> random order: here, the problem is basically chosen at random,
  but problems that you have been asked already are less likely
  to be chosen, especially if your answer was correct.
  (See below for more details.)
<li> sequential order (keep track of solutions): The program 
  maintains a list of all problems in the SGF file; in this
  mode, it always presents the first problem from that list.
  If you solve the problem, it is moved to the end of the list;
  if your answer is wrong, it is moved somewhere to the second
  half of the list (so it will reappear sooner).
<li> sequential order (don't record results): In this mode,
  the problems are presented in the same order as in the
  SGF file. Correct or wrong answers are not recorded in
  any way. You can specify the starting point. If you don't
  specify it (or if the entry is invalid, e.g. not an integer),
  it starts with the first problem in the SGF file.
</ul>

<p>
The mode, together with the current position in 'sequential
order, don't record results' mode, is stored in the .dat file;
so basically each problem collection has its own mode.
If you check the "use as default" option, then the current
mode will be chosen for other collections which do not yet
have a .dat file (i.e. you use then for the first time)
or have a .dat file from version 0.1.</p>

<h4>Options - Use 3D stones</h4>

Toggle the use of the more beautiful 3D stones versus flat stones.
The 3D stones were provided by Patrice Fontaine. (Thank you!)

<h4>Help - About</h4>

<p>
Some basic information about uliGo.</p>

<h4>Help - Documentation</h4>

<p>
Open this documentation in a web browser.</p>


<h4>Help - License</h4>

<p>
The uliGo license.</p>



<h2><a name="miscellaneous">Miscellaneous</a></h2>

<p>
That's it for the moment, I think. Feel free to contact me (at
uligo@g0ertz.de) if you have any questions, or - in particular - 
if you find any bugs in the program.</p>


<h2><a name="installation">Installation</a></h2>

<p>The program is written in <a href="http://www.python.org/">Python</a>,
a high-level interpreted programming
language. If you are using Windows, you can either use the uliGo installer
which contains everything you need to run uliGo, or you install Python separately.
On other systems, you need to install Python before you
can run uliGo. Any version better than 2.0 should do; I tested
the program with Python 2.0, 2.1 and 2.2. If you have to install
Python, you should get the current version 2.2.


<h3>Windows</h3>

<p>Te easiest way is to use the installer. Since it contains the Python interpreter, there is no need to install
Python separately.  </p>

<p>
If you want to install Python separately, download the Python installer for Windows 
from the <a href="http://www.python.org/">Python website</a>. It will be very easy to install it.
Then download the uligo03-win.zip file and unpack it. You should then be able to run uliGo
by double-clicking the "uligo.pyw" file, or from the command line with "c:\python22\python uligo.pyw".</p>

<h3>Linux/Unix</h3>

<p>
It is likely that Python is already included
in your distribution. It is also easy to build it yourself with the
source from the Python website. But be sure to install
the Tkinter module which is needed for the GUI, too; look at the
in the README file coming with Python for instructions how to do that.</p>

<p>
Once you have Python working, just download and unpack the
uliGo file (uligo03.tar.gz). It will create 
a subdirectory called uligo03 in the directory where you unzip
it, and all files needed for uliGo will be placed in that
subdirectory. Then just start uligo.py:
change into the corresponding directory,
and type 'python uligo.py'. (You can also make 'uligo.py'
executable, possibly change the path in its first line to
point to your Python installation, and run it as 'uligo.py'.)</p>

<p>
You can also install uliGo system-wide; see below.</p>

<h3>Other operating systems</h3>

<p>
Python is available for many operating systems, so you should also be able to run
uliGo. See the <a href="http://www.python.org/">Python website</a> for more 
information.</p>

<h3>Upgrade from uliGo 0.1, 0.2</h3>

<p>
Basically, you should just install uliGo 0.3 from scratch,
and delete the old version (Make sure that you don't delete any sgf files
with problems ...). In particular, you should not use
the files uligo.def and uligo.opt from version 0.1 or 0.2 with
version 0.3 (these files contain the default problem collection
and the saved options, respectively).</p>

<p>
You can use the .dat files from uliGo 0.1, though (these files
contain the information about right/wrong answers etc.; for
each SGF file that you used with uliGo there is a corresponding
.dat file). Just copy the .dat files from the sgf subdirectory
of uligo01 to the sgf subdirectory of uligo03. (In case you
installed uliGo system-wide under Unix, it is slightly more
complicated; please see below.)</p>

<h3>Systemwide installation under Unix/Linux</h3>

<p>
To install uligGo system-wide (in /usr/local/share, for instance),
proceed as follows:</p>

<p>
Put the uliGo files in /usr/local/share/uligo03 (if you put them
somewhere else, you have to adapt the unixinst.py script
accordingly).</p>

<p>
Carefully read, and -if necessary- edit the script unixinst.py .
(I think that you probably will not want to change much.)
Basically, the unixinst.py script writes a 'global' uligo.def
file (in the uligo03 directory) which tells uligo to look
for individual .def files (in $HOME/.uligo ) when it is
started. So for every user who uses uligo, a subdirectory
called .uligo will be created in the user's home directory.
In this directory, the individual .def file (which stores
the path and name of the SGF file used last), the .opt
file (which stored the saved options), and the .dat files
(which store the number of correct/wrong answers for
each problem in the corresponding SGF file) are stored.
In order to avoid name conflicts between .dat files for
.sgf files in different directories, the path is shadowed
in the .uligo directory: for a .sgf file in 
/usr/local/share/uligo/sgf, for example, the corresponding
.dat file is in $HOME/.uligo/usr/local/share/uligo/sgf.</p>

<p>
Furthermore the unixinst.py script creates a link
in /usr/local/bin, pointing to uligo.py.</p>

<p>
After you edited the unixinst.py script, execute it with
'python unixinst.py'. The only other thing you might have 
to do (if your python interpreter is not in /usr/bin),
is to change the very first line of the file uligo.py,
which must contain the location of the python interpreter,
so that uligo can be started by 'uligo.py'.</p>

<h2><a name="history">History</a></h2>
<table>
<tr>
<td>May 2003:</td><td>uliGo 0.3, with a few new features, and a Windows installer.</td>
</tr><tr>
<td>June 2001:</td><td>	uliGo 0.2: some minor bugfixes, and the option
                to change the order in which the problems are
                presented (random vs. sequential)</td>
</tr>
<tr>
<td>May 2001:</td><td>uliGo 0.1 is published.</td>
</tr>
<tr>
<td>April 2001:</td><td>Started writing uliGo.</td>
</tr>
</table>

</div>