sgf2misc
Documentation

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.6
    cd		sgf2misc-2.6
    gunzip <	../sgf2misc-2.6.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)

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

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.
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).
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

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.
graphic
Another interesting feature of the new program is that you can quickly browse through the game (on the screen using curses).
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.
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.
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).
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):

The replay instructions are removed from the output
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.
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  ()
```
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).
The above strategy means that our move lists will look like:
```
	move[0]		# possible header information
	move[1]		# 1st move
	move[2]		# 2nd move
	...
```

Page creation: Jan van der Steen

sgf2miscDocumentation