
Introduction
------------
The start of some documentation. Currently only the building directives
and some bits and pieces on how to use the program. Planned are a UNIX
manual page and a LaTeX document which will describe all facets of the
program to you.


What's sgf2misc ?
-----------------
The sgf2misc program reads an SGF, Liberty or Ishi format go record and
converts it to various output media. Currently supported output media are:

	* LaTeX text with PostScript diagrams
	* LaTeX text with LaTeX font diagrams
	* Screen (using the curses library)
	* GIF    (using the netpbm filters)
	* HTML   (with GIF diagram images)
	* ASCII (both text and diagrams)
	* Smart Go Format (SGF)
	* Ishi Format (SF)
	* db dump (just the game header information)
	* Plain PostScript (with script "n-up/mkrawps")
	* Null device (no output whatsoever)

The output is tunable by setting command line options (see below) and by
changing settings and macros defined in sgf.sty.


Thanks
------
I want to thank Jim Yu for encouragement and initial beta testing of
the program. Wasn't it for Jim, the program would have never been born.
I also would like to thank Jim Mattson (it's in the name :-) for his
suggestions and patches (for example: handicap/komi in the header and no
"snap" for "rlineto" operations in gopro.eps).


Installing
----------
You can build the program from compressed tar file by:

    mkdir	sgf2misc-2.7.0
    cd		sgf2misc-2.7.0
    gunzip <	../sgf2misc-2.7.0.tar.gz | tar -xvf -
    make	depend

Now, before you execute the following two comamnd you might want
to take a look at the destination directory in the Makefile:

    HOME = /usr/local

This implies that the "make install" procedure will try to install
the program in:

    /usr/local/bin/sgf2misc

and the library files (PostScript prolog, fonts, and such) in:

    /usr/local/lib/sgf2misc/...

If you prefer another place, please adjust the HOME variable.
Next, build the program with:

    make	sgf2misc

and install it with:

    make	install

I strongly believe in portable software so I've written the source
of sgf2misc with such portability in mind. During the development
of the program the code has been constantly tested on these
architectures:

	* SGI workstation (running IRIX-4.x, IRIX-5.x)
	* Sun workstation (running SunOS-4.1.x, Solaris-2.x)
	* Atari-STe       (running TOS 1.4)
	* PC-486i         (running Linux-1.2.9)

Hints for Sun System:

    For Solaris systems first try:
	make CC=/opt/SUNWspro/bin/cc
    next try:
	make CC=/usr/ucb/cc XCFLAGS=-Dconst= XINC=-I/usr/ucbinclude
    For SunOS-4.1.3 systems try:
	make CC=/usr/ucb/cc XCFLAGS=-Dconst=

There are three problems (that I know of) which you might encounter
while trying to build sgf2misc:

1. The function vprintf() not available

   For this I can only advise you to contact your system administrator
   and have it fixed. It means that the C-library is way out of date.

2. No curses library on your system

   This second problem might occur especially on MSDOS or similar
   systems (Amiga). In this case you can still use the program (check
   out the Makefile, it has provisions for you).

3. The compiler states it's an ANSI-C compiler but actually it isn't.

   The source is fully ANSI-C compliant while doing prototyping
   conditionally (dependent on the compilers capabilities). Sometimes
   the compiler lies: it says it "can read" ANSI-C but actually it can't
   (!). Don't worry, in the Makefile there is a provision for you. Check
   it out.


Usage
-----
Here's the usage (you get it with "sgf2misc -help"):

Usage: sgf2misc [options] [file]
------------------------------------------------------------------------
Option              Description                                 Default
------------------------------------------------------------------------
[-from fmt_spec]    Input Go game format                        sgf file
                    [sgf,liberty,sf]                            
[-to dev_spec]      Output format                               pstex
                    [pstex,tex,ascii,graphic,sgf,sf,db,gif,null]
[-paper paper_spec] Paper Size                                  default
                    [default,letter,a4wide,a4]                  
[-tmp path]         EPS directory                               /tmp
[-scale size]       Diagram size [72 = 1in]                     0
[-max moves]        Limit moves per figure                      unlimited
[-figures  list]    Emit figures  in list                       automatic
[-diagrams list]    Emit diagrams in list                       all
[-output file]      Emit output to file                         stdout
[-coordinates]      Don't print coordinates                     on
[-text_output]      Don't print text output                     on
[-labels]           Don't label moves                           on
[-caching]          Caching   mode                              off
[-verbose]          Verbose   mode                              off
[-sequent]          Variation(1) mode                           off
[-flatten]          Variation(2) mode                           off
[-kibitz]           Kibitz    mode                              off
[-zhuge_mode]       Zhuge     mode                              off
[-statistics]       Emit kibitz statistics                      off
[-short_keys]       Don't use long SGF keys                     off
[-ppm path]         Path to ppm directory                       /ufs/jansteen/lib/sgf2misc/ppm
[-pbmbin path]      Path to pbmplus tools                       /usr/local/pbmplus
[-rgbb color]       GIF Color for Black                         rgb\:00/00/00
[-rgbw color]       GIF Color for White                         rgb\:ff/ff/ff
[-rgbg color]       GIF Color for Board                         rgb\:ff/e1/4b
[-rgbo color]       GIF Color for Outside                       rgb\:ff/e1/4b
[-rgbr color]       GIF Color for Region                        rgb\:ff/ff/7f
[-fontsize bits]    GIF image unit size                         15
[-version]          Print program version                       
[-help]             Print usage                                 

The recognised syntax for the "-figures list" command line option:

    -fig25-50-75-100
    -fig25+50+75+100	Produce game diagram after move 25,50,75 and 100
    -fig25,50,75,100	and one for the remaining moves


    -fig25-50-75-100-0
    -fig25+50+75+100+0
    -fig25,50,75,100,0	Produce game diagram after move 25,50,75 and 100

    -fig%50		Produce game diagram every 50 moves


Examples
--------
Some examples to show you what you can do with the program:

    sgf2misc -zhuge -flatten -to graphic Sakata.sgf

	Show your Go Seigen game on the screen,
	page through it using spaces, quit with 'q'

    sgf2misc -z -flatten -to ascii Sakata.sgf | mail jansteen

	Mail me the ASCII version of the same game

    sgf2misc -z -flatten -to pstex Sakata.sgf > Sakata.tex

	Create a LaTeX version of the game using
	PostScript diagram code (this is the default).
	The next step is to run LaTeX on this file and
	convert the resulting dvi file to PostScript.

    sgf2misc -kibitz -to g IGSgame.sgf

	Quickly replay an IGS game on the screen
	For abbrevity, we've used "-to g" here (i.e. the unique
	initial strings) instead of "-to graphic", you can
	do this with all command line options and arguments.


Device specific features
------------------------
1. pstex
The front end command line options allow you to scale the
diagrams to any size (well...) you want (see the -scale option
below). When you exceed the width of the text column the package
will automatically switch to single column mode. This will
definitely mean a dramatic increase of paper throughput though.

2. graphic
Another interesting feature of the new program is that you can
quickly browse through the game (on the screen using curses).

3. ascii
You can redirect the game to a file (using the ascii option)
to prepare something for rec.games.go or maybe mail somebody
something.

4. sgf
You can read and write sgf files. Use this to strip the
comments, convert to long/short notation, or get rid of long
text lines (sgf2misc emits a maximum of around 72 characters).
you can also use this option to emit sgf from Liberty or
Ishi format input games.

5. null device
This is a funny device: "no output whatsoever". Well, you can
use it to check the correctness of an inputfile (you get just
warnings and error messages), but you can use the same code to
replace one of the build-in drivers in case you don't need it
(pure TeX mode) or don't have it (curses mode).

6. GIF
The diagrams will be build from small ppm images and giving
color using various netpbm tools. Their size can be set from
the command line:

	-fontsize size    GIF image unit size

The default size (15 pixels) will create diagrams of 19*15=285
pixels. The resulting GIF image will be approx. 4-5kb. The color
of the board and outside, the board regions, and the black and
white stones can be set from the command line as well:

	-rgbb color       GIF Color for Black
	-rgbw color       GIF Color for White
	-rgbg color       GIF Color for Board
	-rgbo color       GIF Color for Outside
	-rgbr color       GIF Color for Region


On Figure breaks
----------------
If you don't force figure breaks (with the -figure command line option)
the program will try to create figures from the game itself. It will
start a new diagram after it encountered:

* letters	(unless the -text_output option is given)
* comments	(unless the -text_output option is given
		 and only in graphic mode)
* a variation	(unless variations are excluded with the -diagrams option)


On move labels
--------------
First let me explain what move labels are:

	Black 123:
	----------
	Not so good, better push at [a].

The "Black 123:" is a move label, indicating which move the comment is
talking about. You can supress move labels with the "-labels" command
line option. Otherwise, sgf2misc will create them when the comment is on
an actual move and when there is more than one move in the diagram.


Letters and Marks
-----------------
When the user selected *not* to print the comments (-text_output) the
program will automatically ignore all Mark[] and Letter[] directives in
the game.


zhuge mode (-zhuge)
-------------------
In "zhuge" mode the program automatically modifies some parts of the
text blocks (which are *very* Jim Z. Yu specific):

1. The replay instructions are removed from the output
2. The (*...*) blocks are automatic emphasises (in pstex mode)

Why zhuge mode? Well, first of all, the replacements of some of the text
is programmed specifically to deal with Jim Z. Yu's game analysis on
Go Seigen's games (posted on rec.games.go in the first part of 1993).
But besides, thanks to Jim Z. Yu's valuable beta-testing during the
development of the program, the sgf2misc project did finish in the first
place.


flatten mode (-flatten)
-----------------------
The game branches are removed from the tree:

      |g                          |g
      |---|---|                   |---|
          |g  |v1                 |g  |v1
          |                       |
          |---|---|               |---|
              |g  |v1             |g  |v1
              |                   |
              |---|---|---|       |---|---|
                  |g  |v1 |v2     |g  |v1 |v2
                  |               |

              round                flattened
              -----                ---------


sequent mode (-sequent)
-----------------------
The game branches are put after the variation branches:

      (g                              (g
       |--(---(                        |--(---(
          )v1 |g                          |g  )v1
              |                           |
              |---(---(                   |---(---(
                  )v1 |g                      |g  )v1
                      |                       |
                      |---(---(---(           |---(---(---(
                          )v1 )v2 |g              |g  )v1 )v2
                                  ))))            ))))

              sequential                   round
              ----------                   -----


Inline go stones
----------------
From sgf2misc version 2-3 on I've added inline Go widgets useable within
pstex mode. The widgets PostScript code are in sub-directory "gowidget".
The widgets are (black/white):

	plus			\blackplus
	minus			\blackminus
	triangle		\blacktriangle
	filled triangle		\blacktrianglefilled
	square			\blacksquare
	filled square		\blacksquarefilled

All the above macros are also defined for white (instead of black).


On text, newlines and paragraphs
--------------------------------
The SGF specification doesn't mention anything on the syntax of the
contents of "Comment[]" blocks (or "C[]" in short notation). The only
obvious restriction made is that any occurence of the character ']'
in the text is escaped by a preceeding '\' (to avoid that the ']' is
interpreted as the end of the list).

When sgf2misc writes out an SGF file obviously it will obey the above
syntax, but beside that it will break the lines near position 64 (to
avoid long lines) and preceed the newline with the sequence: " \",
denoting that the current line is actually continued:

Comment[
This game was full of violent and nerve-straining fights.  Both \
sides spent a great amount of energy and brain cells.  Reflecting \
onto the board, it was a seesaw game from the beginning to the end. \
This was indeed a rare masterpiece.
]

For further thoughts on paragraphs and newlines, see the file: "NEWLINES".

Problems
--------
If you encounter problems using sgf2misc please tell me which version
you are running ("sgf2misc -version") when you E-mail me the problem.

Trouble shooting
----------------
*  While running LaTeX, in case it doesn't like the sequence:

	\language\english

   then just remove it from either the TeX file produced by sgf2misc
   or from the style file sgf.sty.
   Btw, in case you're interested: the "\language\english" assignment
   selects the English hyphenation patterns for TeX with multiple
   hyphenation tables compiled in.

*  If you have the special TeX Go font (designed by Hanna Kolodziejska)
   then you could choose to typeset the diagrams using that font.
   Execute sgf2misc with the "-device tex" flag in that case.

*  When you use the "-to tex" option (TeX diagrams) then you probably
   also want the pointsize 8 font to scale the diagrams at an appropriate
   size.  These fonts are available to you at:

	ftp : ftp.nlnet.nl
	dir : pub/games/go/GoLaTeX
	file: README.jansteen	(   588 bytes)
	file: GoLaTeX.tar.Z	( 63771 bytes)
	file: GoLaTeX.fnt.tar.Z (380609 bytes)

    The file GoLaTeX.fnt.tar.Z contains 300 dpi fonts at various sizes
    (8pt, 10pt, 12pt, ...).

*  If you have suggestions or bug reports let me know (just fill in a
   copy of the file BUGREPORT and send it to me by E-mail)

Inside details
--------------
*  The way we deal with moves, marks, comments, or most notably, when
   do we allocate a new GOMOVE structure?

	  #[SGF:

    In SGF format the node indicator seperates chunks of info and
    can serve as a signal to allocate a new GOMOVE:

	(
	;
	Name[reference]
	AddWhite[ds]
	Comment[[Suppose W throws in first...\]]
	;
	AddEmpty[gs]
	Black[cs]
	)

    The ";" seperator will allocate two move structs, one with the
    game/variation info, the other with a move and a removed stone.
    Receiving data while not having a GOMOVE available is an error.
    Having empty nodes is not elegant (waste of memory and disk
    space) but not an error.

	  #]SGF: 
	  #[SF:

    In SF format the order of information is strict:

	1. Remarks
	2. Move definition (SETUP or B or W keyword)
	3. Prisoners
	   Marks
	   Commentary
	   User data
	4. Variations on the move

    1. We allocate a GOMOVE at the start of each game/variation:

		record_event ()
		record_var   ()

    2. Next, we allocate a GOMOVE for each remark/move event,
       whichever comes first...

		record_remark()
		record_move  ()

	  #]SF: 
	  #[Liberty:

    In Liberty format the user can enter data whenever he wants.
    So, it's sgf2misc's responsibility to allocate GOMOVE's at
    some appropriate times.

    1. We will allocate one when a game/diagram starts, to hold
       the header information and possible setup stones (such as
       handicap).
    2. Next, each move will allocate it's own GOMOVE which will
       contain all data following that move (until the next move).

	  #]Liberty: 

    The above strategy means that our move lists will look like:

	move[0]		# possible header information
	move[1]		# 1st move
	move[2]		# 2nd move
	...


Jan van der Steen
Thu Jul 8 15:21:55 MDT 1993
