\documentclass[11pt,twocolumn]{article}

\usepackage{lambda,ifthen,calc}
\usepackage{tabularx}
\usepackage[ps,mover]{skak}

\newcommand{\package}[1]{\textsf{#1}}
\newcommand{\pgn}{PGN\ }
\newcommand{\fen}{FEN\ }
\newcommand{\xboard}{xboard}
\newcommand{\metafont}{\textsc{Metafont}\ }
\newcommand{\file}[1]{\texttt{#1}}
%\usepackage[a5paper]{anysize}

\newcommand{\Guido}{Guido Governatori}
 
\title{Typesetting Chess in \LaTeX with the \package{skak} Package}
\author{Torben Hoffmann\\ e-mail: \texttt{toho@it.dtu.dk}}
\begin{document}
\maketitle

\begin{abstract}
  This user guide will show how to use an enhancement to the existing
  package for typesetting chess in \LaTeX (\package{skak}). The
  primary improvement over the old package is that it has become
  easier to typeset chess games with this new package, as we shall
  demonstrate in this user guide.
\end{abstract}



\section{Terms of Usage}
\label{sec:terms-usage}

This package is distributed under the terms described in the Latex
Project Public Licence, i.e.,    

\begin{quote}
  This software is copyright but you are granted a license which gives
  you, the ``user'' of the software, legal permission to copy,
  distribute, and/or modify the software. However, if you modify the
  software and then distribute it (even just locally) you must change
  the name of the software to avoid confusion.
\end{quote}

\section{Acknowledgements}
\label{sec:acknowledgements}

I would like to thank the creator of the \package{lambda} package,
Alan Jeffrey, for making a splendid package that made this package
possible.

For discussions and alpha-testing I send my thanks to \Guido --- some
of his ideas have allready been implemented; the rest? Time will show.

\section{The Old \package{chess} Package Versus the New \package{skak}
  Package}
\label{sec:old-vs-new}

The main reason for considering an improvement of the \package{chess}
package that Piet Tutelaers made back in 1991 is the cumbersome user
interface the package has when one wants to write about a chess game
and display a diagram every now and then. Typesetting the two opening
moves where white and black moves their kingside knights is done as
follows in the \package{chess} package:

\begin{verbatim}
\move g1f3 g8f6
\end{verbatim}

The package then produces a nice typesetting of these moves in
figurine notation, but it is hard to keep track of what is going on
because the one usually uses the \pgn notation to write down the moves
of a chess game. The \pgn version of the two moves above is:
\verb|1. Nf3 Nf6|, which is much clearer to most chess players. In the
\package{skak} package we allow the author of a chess article to use
the \pgn notation as input to the command that updates the chess
board. In addition to making it easier for the author to write about
chess using a familiar notation it also provides an easy way to
include moves generated by a chess program such as \xboard in the
document---most other chess programs can also output a \pgn version of
a chess game.

The \package{skak} can also input chess board positions given in the
\fen notation, which is also quite standard in the domain of chess
programs. Besides a better user interface the chess font the
\package{skak} package uses is three small modifications of the font
created by Piet Tutelaers: the knight now looks a bit more
``youthfull'', the contur of the queen has been smoothened and all the
chess pieces has been shrunk such that they do not fill as much of a
square as before. We find this font nicer to look at, but your milage
may vary.




\section{How to use the \package{skak} Package}
\label{sec:how-use-skak-package}

Writing about a chess game is straightforward:

\begin{verbatim}
\newgame

\mainline{1. e4 e5 2. Nf3 Bc5}
\end{verbatim}
 
\newgame
\noindent
starts a new game and produces the following in your document: 

\mainline{1. e4 e5 2. Nf3 Bc5}. 

So far, so good. And just like the old \package{chess} package we can
produce a chess board in our ducument: \verb|\[\showboard\]| yields

\[\showboard\]

\noindent
(the use of math \verb|\[...\]| is just to make sure the board is centered.)

The board comes in four different sizes: tiny, small, normal (which we just
saw) and large. The size used can be altered at any time in a document
using the \verb|\tinyboard|, \verb|\smallboard|, \verb|\normalboard|
and \verb|\largeboard|.

The size of the figurine notation is determined automatically for the
standard font sizes 10pt, 11pt and 12pt --- other sizes can be made
by creating a new \metafont file based on the file \file{fig10.mf}.

It is also possible to use ones native language as input to
\verb|mainline|. First create a new language:
\verb|\newskaklanguage{danish}{KDTLSB}|, the first argument is the
name of the language and the second argument is the uppercase letters
used in that language to denote a king, queen, rook, bishop, knight
and pawn. The newlanguage can then be activated using
\verb|\skaklanguage[danish]|, and the package will take care of the
translation to english piece names. An example:
\verb|\mainline{3. De2 De7}| will now move the white queen to e2.

\newskaklanguage{danish}{KDTLSB}
\skaklanguage[danish]

\styleA


\mainline{3. De2 De7}


Notice that we have changed the typesetting of the moves from the more
modern way of showing the figurine notation to the traditional
german/danish way of doing it.  This is done with the command
\verb|\styleA| --- switching back is done with \verb|\styleB|.

There is another style available as well, \verb|\styleC|, which will
be demonstrated below.

\[\showboard\]


Going back to english is easy: just type \verb|\skaklanguage| (english
is the default arugment). \skaklanguage Now \verb|\mainline{4. Nc3 b7}|
will give us (in \verb|\styleC|): 
\styleC

\mainline{4. Nc3 b7}

\styleB
Notice that we used \verb|...| instead of \verb|.| after the number to
denote that is a black move we start with; if the input move colour
does not match the state of the game the package will issue a error
message. Another thing to notice is that the move is not separated
from the periods by a space --- this feature is due to some programs
that output \pgn writes the move directly after the period(s)
(observation by \Guido).

Some input errors will be detected and an error message will be
issued, but with regards to the validity of the moves used as argument
to \verb|\mainline| only the valid moves are guaranteed to
work---invalid moves will produce error messages or spurious chess
positions!

\styleC
It is often the case that one wants to comment on a small variation of
the move sequence played, and for that purpose we have the
\verb|\variation| which displays the moves but it does not update the
chess board. So \verb|\variation{3... Qf6 4. Nc3 b7}| produces
\variation{3... Qf6 4. Nc3 b7} in the document, but the chess board
remains unchanged (see below). If one wants to use a different
typesetting style for the variations one has to redefine the
\verb|\mainlinestyle| and \verb|\variationstyle| commands, eg,

\begin{verbatim}
\def\mainlinestyle{\styleC\bfseries%
       \let\Fig=\Figb} %\styleC added
\def\variationstyle{\styleB\let\Fig=\Fign}
\end{verbatim}

\def\mainlinestyle{\styleC\bfseries\let\Fig=\Figb}
\def\variationstyle{\styleB\let\Fig=\Fign}

This will use the more spaceconsuming style for the mainline and the
more textlike for the variations --- this style is often used in books.

\[\showinverseboard\]



\noindent apart from the obvious fact that we have just shown the
board from the perspective of black--- this is done using the
\verb|\showinverseboard| command. Speaking of showing the board: it is
also possible to toggle the use of rank and file names besides the
board. \verb|\notationOff| turns them off and \verb|\notationOn| turns
them back on. Let's try turning them off:

\notationOff \[\showboard\] 


\subsection{Updating the Board}
\label{sec:updating-board}

The command \verb|\hidemoves| updates the board but does \emph{not}
update the board --- this could come in handy in situations where you
have the \pgn of a game available but only wants to focus on the game
after some moves. 

Another way of setting up the board is using the \fen notation as
argument to the \verb|\fenboard| command. The \verb|\newgame| command
uses this command to setup the board in the first place like this: 
\begin{verbatim}
\def\newgame{%
\fenboard{rnbqkbnr/pppppppp/8/8/8/8/
     PPPPPPPP/RNBQKBNR w KQkq - 0 1}}
\end{verbatim}

The first part of the \fen string is the rows (from 8 to 1) separated
by \verb|/|; the black pieces uses small letters and the uppercase
letters denotes white picecs; numbers denote empty squares. After the
position has been stated the player to move is denoted using \verb|w|
or \verb|b|, then we have the castling posibilities, followed by a
square where one can make an \emph{en passant} capture. The numbers
denote the number of plies since a capture or pawn-move (used in the
50-moves rule) and finaly we have the move number.


\subsection{Game storage}
\label{sec:game-storage}


Chess positions can be imported and exported using the \fen notation:
\verb|\savegame{game1}| will save the current position in the file
\verb|game1.fen| and \verb|\load{game1}| will set the chess board to
the position described in the file \verb|game1.fen|. We save the
position now\savegame{game1}, make a move \mainline{5. b3}, loads
the saved game\loadgame{game1} and the board has not changed one bit:

\[\showboard\]

Games can also be stored and restored without resorting to files using
the \verb|\storegame| and \verb|\restoregame| commands. We test the
functionality of these commands right here:
\verb|\storegame{Joe-Mike,991010}|\storegame{Joe-Mike,991010} followed
by \mainline{5. b3 d6 6. a3} and
\verb|\restoregame{Joe-Mike,991010}|\restoregame{Joe-Mike,991010}---notice
the free form naming of games.


\subsection{Ornaments}
\label{sec:ornaments}


The command \verb|\showmoverOff| will turn of the showing of how is to move:
\showmoverOff

\[\showboard\]

It can be turned on again with \verb|\showmoverOn|.

Finally, it is also possible to show only some of the pieces on the
board with the commands \verb|\showonlywhite|, \verb|\showonlyblack|,
\verb|\showonlypawns| and the general \verb|\showonly| which takes a
comma separated list of piece names (in english! I have not had the
time to do it for the current language --- volunteer work apreciated
here). Showing all pieces again is done with \verb|\showall|.

\showonlywhite
\[\showboard\]

\showall


\[\showboard\]


Furthermore, it is possible to highlight squares on the board, e.g.,
\verb|\highlight{a2,b3}| will highlight the squares a2 and b3.

\[\showboard\]
\highlight{a2,b3}
\printknightmove{g1}{f3} \printarrow{f1}{b5} \printarrow{a1}{a8}

Note, that \verb|\highlight| is called after \verb|\showboard|. Some
\texttt{dvi}-viewers (e.g.,\texttt{xdvi}) will not show the
highlighting box properly, but the \textsc{PostScript}-file will be
allright.

The arrows in on the board has been generated using the commands
\verb|\printknightmove{g1}{f3}|, \verb|\printarrow{f1}{b5}| and
\verb|\printarrow{a1}{a8}|. The \verb|\printknightmove| command only
behaves well for prober input, i.e., the two arguments describe a
valid move by a knight. \verb|\printarrow| draws a arrow between any
two squares on the board --- I think that only diagonals, ranks and
files are needed, but the general solution was easier to implement.

Missing from the documentation:
\begin{itemize}
\item how to define your own typesetting of moves
\item list of options to the class
\item a rewrite of the documentation in order to present the many
  posibilities on more pages.
\end{itemize}



\section{Installing the \package{skak} Package}
\label{sec:install}

I could not get the makefile to do the job, so if someone could help
me out on this I would be very glad indeed.

Basically all you have to do is to follow the guidelines in the
makefile. First you create all the required directories (stated in the
\texttt{install} section of the makefile) and then you run the
\texttt{make install} command. Remember to run \texttt{texhash} after
you have updated your texmf tree.

Sorry that is not working $100\%$--- I just do not have the time for
it right now.

If you cannot get the things working just put the files where \TeX and
the other tools can find them and you will be just fine. 


\subsection{Using the \package{lambda} Package}
\label{sec:using-lambda}

The \package{skak} package uses the \package{lambda} package to do
some of the hard processing necessary to allow the \pgn notation as
input --- since it is not standard in \LaTeX distributions it is
included in the distribution of the \package{skak} package.



\section{Future Additions}
\label{sec:future-additions}

It would be nice if one could choose the language for the
\verb|mainline|, \verb|variation| and \verb|\hidemoves| for each invocation
as it allows for easier inclusion of analysis from chess programs when
using a non-english language.


 
\end{document}





