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:

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


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


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:
and the library files (PostScript prolog, fonts, and such) in:
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: 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.


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
[-to dev_spec]      Output format                               pstex
[-paper paper_spec] Paper Size                                  default
[-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	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	Produce game diagram after move 25,50,75 and 100

    -fig%50		Produce game diagram every 50 moves


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 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:

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 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:

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


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

Inside details

Page creation: Jan van der Steen