path: root/macros/latex/contrib/texmate/texmate2manual.tex

\documentclass[12pt]{ltxdoc}
\usepackage{array}
\usepackage{makeidx}
\usepackage[dvipdfm,bookmarks=true,hyperindex=false]{hyperref}
%\usepackage{fourier}
%\usepackage{doc}
%\usepackage{shortvrb}
\usepackage[skaknew]{chessfss}
\usepackage{texmate}
\makeindex
\PageIndex
\begin{document}
\setcounter{IndexColumns}{2}
\IndexPrologue{\section*{Index of user commands}}
\renewcommand\usage{}
\title{\TeXmate\,2: User's manual}
\author{Federico Garcia}
\maketitle
\tableofcontents
\MakeShortVerb{\"}
\DeleteShortVerb{\|}
\makeatletter
\DeclareRobustCommand\SMC{%
  \ifx\@currsize\normalsize\small\else
   \ifx\@currsize\small\footnotesize\else
    \ifx\@currsize\footnotesize\scriptsize\else
     \ifx\@currsize\large\normalsize\else
      \ifx\@currsize\Large\large\else
       \ifx\@currsize\LARGE\Large\else
        \ifx\@currsize\scriptsize\tiny\else
         \ifx\@currsize\tiny\tiny\else
          \ifx\@currsize\huge\LARGE\else
           \ifx\@currsize\Huge\huge\else
            \small\SMC@unknown@warning
 \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
}
\newcommand\SMC@unknown@warning{\PackageWarning{\acro}{\string\SMC: unrecognised
    text font size command -- using \string\small}}
\newcommand\textSMC[1]{{\SMC #1}}
\newcommand\acro[1]{\textSMC{#1}\@}

\section{Introduction}

Since the appearance last year of \TeXmate\ in its  first version, the \LaTeX-chess community has been very active. Now there are new versions of Torben~Hoffmann's \textsf{skak} and of its fonts. There are new packages of immense scope and utility: Ulrike~Fischer's \textsf{chessfss} and \textsf{chessboard}. 

To an important degree, all these efforts have grown together. And \TeXmate\ now incorporates the chess-playing capabilities of \textsf{skak}, somewhat achieving what back in the day was a dream of having the best of both worlds, a dream that arose from the enthusiastic reception of the first \TeXmate. Now \TeXmate\ uses \textsf{skak} to follow the game, helping to catch input mistakes, and, above all, drawing the diagram of the current position automatically. In addition, font handling is completely delegated to \textsf{chessfss}, and for now all packages appear to be satisfactorily compatible.

My thanks then to Ulrike and Torben, but also Ulrich~Dirr, for their constant interest and feedback. I am indebted for the final encouragement to Frank~Mittelbach as well.

Future plans include a \acro{PGN}-to-\TeX\ translator. As for \TeXmate, it's probably too early to know where it's going, but one thing seems clear: \TeXmate\ might interfere with other complicated packages. The problem lies in the change of category codes for some characters. This is certainly something to look into. (Quick and dirty try, though: modify "\@nochesscodes" according to the other packages you are loading\dots)

\pagebreak
\section{Basic usage}

\subsection{A short game}\label{first}
\makebarother
\begin{verbatim}
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 0-0 d6 d3 Nf6 Bg5
h6 Bh4 g5 Bg3 h5 Nxg5 h4 Nxf7 hxg3 
Nxd8 Bg4 Qe1 Nd4 Nc3 Nf3+ gxf3 Bxf3|
\end{verbatim}

This input stream gives \TeXmate\ the moves of a beautiful miniature (probably home-prepared, though) by Steinitz. 

The only two conventions are the inclusion of all moves between two \DescribeMacro{|}\SpecialIndex{|}"|"'s (``chess mode''), and the separation of moves by spaces. Beyond that, the user is free to add punctuation marks, as inconsistently as he wants, and \TeXmate\ will always produce the same output. (In particular, \acro{PGN} move notation is supported without any change.)

In normal conditions, the "|" is set by default to delimit chess mode. The user commands "\makebarother" and "\makebarchess"\DescribeMacro{\makebarchess}\DescribeMacro{\makebarother} toggle the meaning of that character between chess mode and nothing special. 

However, if \TeXmate\ finds that another package has a special use for "|", it will refrain from using it. In that case, chess mode should be entered with through an alternative (which is always available, in any case): the \texttt{texmate} environment ("\begin{texmate}"--"\end{texmate}"). Even then, a "\makebarchess" (by the user) will make "|" open and close chess mode. 

\bigskip\noindent
With default settings, the result of the quoted input is:

\begin{texmate}
1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5 d6 O-O h6 Bh4 g5 Bg3 h5 Nxg5 h4 Nxf7 hxg3 Nxd8 Bg4 Qe1 Nd4 Nc3 Nf3+ gxf3 Bxf3
\end{texmate}

And White cannot avoid being mated.

\subsection{Game title}\label{markup}

The game was played between Dubois and Steinitz in London in 1862. So:

\begin{verbatim}
\whitename{Dubois}
\blackname{Steinitz}
\chessevent{London 1862}
\ECO{C50}
\chessopening{Giucco Pianissimo}
\end{verbatim}

\SpecialIndex{\whitename}\SpecialIndex{\blackname}\SpecialIndex{\ECO}\SpecialIndex{\chessopening}
\SpecialIndex{\chessevent}
\DescribeMacro{\welo}\DescribeMacro{\belo}("\chessevent" is a safer command name than `place,' and for games of chess, they are usually interchangeable.) All these commands are not required, and there are two more: "\welo" and "\belo" for ratings or other information about the players.

\whitename{Dubois}
\blackname{Steinitz}
\chessevent{London 1862}
\ECO{C50}
\chessopening{Giucco Pianissimo}

Now, before the game is input, we can issue \DescribeMacro{\makegametitle}"\makegametitle". If in addition we type \DescribeMacro{\resigns}"\resigns" when its White's turn (so the game input is \makebarother"|1 e4 e5 Nf3"\dots"Bxf3 \resigns|"), the result is:

\makebarchess
\makegametitle
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5 d6 0-0 h6 Bh4 g5 Bg3 h5 Nxg5 h4 Nxf7 hxg3 Nxd8 Bg4 Qe1 Nd4 Nc3 Nf3 gxf3 Bxf3 \resigns|

\bigskip\noindent
\DescribeMacro{\newgame}"\makegametitle" includes the all-important command "\newgame", that sets the stage for \TeXmate\ (and \textsf{skak}) to start a game afresh. It is the safest way to start from scratch (for example, for quoting a related game in commentary) if there is no interest in the game title as defined in \TeXmate. (See also sections \ref{cosmetics}~and~\ref{skak}.)

\subsection{Basic Annotations}\label{annotation}

Here we will add  more things:

\begin{description}
\item[Symbols] after the moves: !, ?, etc. These pose no complication at all---\TeXmate\ treats them as part of moves, just as if they were letters. The same applies to chess symbols like "\betteris", or "\onlymove".
\item[Simple threats] with the command \DescribeMacro{\threat}"\threat<"\meta{threat}">". \TeXmate\ inserts the symbol \withidea\ and typesets the \meta{threat} without regard to move numbers, etc. 
\item[Variations] with the `commentary' markers \DescribeMacro{[}"[" and "]".
\end{description}

\makebarother
\begin{verbatim}
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [Nc3] 
d6 O-O?! h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! 
Nxd8 [Nxh8 Qe7! \threat<Qh7> Nf7 Bxf2+ Rxf2 
gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 
Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 
Bf3\#] Nf3+! gxf3 Bxf3 \resigns|
\end{verbatim}

\makebarchess
\makegametitle
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [Nc3] d6 O-O?! h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! Nxd8 [Nxh8 Qe7! \threat<Qh7> Nf7 Bxf2+ Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 Bf3\#] Nf3+! gxf3 Bxf3 \resigns|

\subsection{Diagrams}\label{diagrams}
\TeXmate\,2 makes use of the chess engine of the package \textsf{skak} to `follow' the game as it is input, so that it can, at any point, insert a diagram with the current position. This can be done simply by \textsf{skak}'s command \SpecialIndex{\showboard}"\showboard". At this very moment, the final position of the game is in memory, so, in a paragraph by itself, the command will produce:

\showboard

\noindent All \textsf{skak} commands apply. For example, "\showonlypanws\showboard" produces:

\showonlypawns\showboard\showall

\bigskip\noindent
\TeXmate\ provides tools for the handling of diagrams. \DescribeMacro{\toD}"\toD" (meaning something like ``refer to Diagram'') inserts `\textit{(D)}' in the chess text, and saves the position in memory. \DescribeMacro{\makediagrams}Many positions (by default 3, but extendable) can be held in memory, and they are actually typeset by the command "\makediagrams".

"\toD" has an argument: the last move. \TeXmate\ will typeset the last move and put it (by default) below the diagram. Note that it will \emph{not} typeset the move directly in the running chess text (thus the move can be different in running text---where it can have annotation symbols---and in the diagram).

\bigskip\noindent
Adding this to the game, the complete input is:

\makebarother
\begin{verbatim}
\whitename{Dubois}
\blackname{Steinitz}
\chessevent{London 1862}
\ECO{C50}
\chessopening{Giucco Pianissimo}

\makegametitle
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [Nc3] 
d6 O-O?! h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! 
\toD{hxg3!!} Nxd8 [Nxh8 Qe7! \threat<Qh7> Nf7 Bxf2+ 
Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 
Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 
Bf3\#] Nf3+! gxf3 Bxf3 \toD{Bxf3} \resigns|

\begin{figure}[h]
\makediagrams
\end{figure}
\end{verbatim}

\noindent And the complete output is:
\makebarchess
\whitename{Dubois}
\blackname{Steinitz}
\chessevent{London 1862}
\ECO{C50}
\chessopening{Giucco Pianissimo}

\makegametitle

|e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [Nc3] d6 O-O?! h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! \toD{hxg3!!} Nxd8 [Nxh8 Qe7! \threat<Qh7> Nf7 Bxf2+ Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 
Bf3\#] Nf3+! gxf3 Bxf3 \toD{Bxf3} \resigns|

\begin{figure}
\makediagrams
\end{figure}

This will insert the diagrams at a reasonable (in \LaTeX-insertion scales) place. The appearance of the diagrams can be customized to some extent, as treated in section~\ref{custdiagrams}. "\makediagrams" will center the diagrams automatically, so "\begin{center}" is not necessary.

On the other hand, the starred \DescribeMacro{\toD*}"\toD*"\meta{last move} will not insert ``\textit{(D)}'', but will otherwise do the same as "\toD".

\bigskip\noindent
\DescribeMacro{\preparediagram}There is an alternative way of preparing a diagram for typesetting:

"\preparediagram""{"\meta{diagram header}"}{"\meta{diagram footer}"}"\\
sends the current position into diagram cache, not with the usual header and footer (which by default are the players' names and the last move, as explained in section~\ref{custdiagrams}), but with those set directly by the user. This can be done at any point, but it is useful particularly in connection with "\position" (section~\ref{position}).


\subsection{Text and chess}\label{text}

Regular, running text can be inserted at any point into a game, by simply exiting chess mode and entering it before the game resumes.

\makebarother
\begin{verbatim}
\whitename{Dubois}
\blackname{Steinitz}
\chessevent{London 1862}
\ECO{C50}
\chessopening{Giucco Pianissimo}

\makegametitle
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [Nc3] 
d6 O-O?!| Black has not yet castled, so he can storm with the 
Kingside pawns, taking advantage of the aggressive but 
unfortunate position of White's bishop. |h6 Bh4 g5 Bg3 h5! 
Nxg5 h4! Nxf7 hxg3!! Nxd8 [Nxh8 Qe7! \threat<Qh7> Nf7 Bxf2+ 
Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 Qe1 Nd4 
Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 Bf3\#] Nf3+! gxf3 
Bxf3\resigns|
\end{verbatim}


\makebarchess
\whitename{Dubois}
\blackname{Steinitz}
\chessevent{London 1862}
\ECO{C50}
\chessopening{Giucco Pianissimo}

\makegametitle
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [Nc3] d6 O-O?!| Black has not yet castled, so he can storm with the Kingside pawns, taking advantage of the aggressive but unfortunate position of White's bishop. | h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! Nxd8 [Nxh8 Qe7! \threat<Qh7> Nf7 Bxf2+ Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 Bf3\#] Nf3+! gxf3 Bxf3 \resigns|

\subsection{Text and annotation}\label{textann}
When text and annotation (chess variations that are not the main line of the game) are used at the same time, the symbol `[', inserted by default for variations, can be redundant. \SkakOff We don't want something like ``|\white 5 Bg5?![|The development of the Knight with |Nc3| is more urgent. |] d6|.'' But exiting and re-entering chess mode is not enough, for \TeXmate\ needs to know that this is a variation (otherwise it will typeset \makebarother"|Nc3|" as belonging to the game, and \textsf{skak} will try to update the board  and get confused). 

The solution is to open the annotation not with the commentary character, but with the commentary \emph{control~sequence}: \DescribeMacro{\[}"\[". Thus:

\begin{verbatim}
|e4 e5 Nf3 Nc5 Bc4 Bc5 d3 Nf5 Bg5?! \[| The
development of the Knight with |Nc3| is more
urgent. |\] d6...|
\end{verbatim}

\noindent which produces:

\SkakOn
\newgame
\makebarchess
|1 e4 e5 Nf3 Nc5 Bc4 Bc5 d3 Nf5 Bg5?! \[| The
development of the Knight with |Nc3| is more
urgent. |\] d6|\dots


\subsection{Variations and subvariations}\label{subvars}

Variations and subvariations, marked by either "["\meta{variation}"]" or "\["\meta{variation}"\]", can be nested (however, "[" should always be closed by "]", and "\[" by "\]"). \TeXmate\ has four levels of variation (the first being the main game itself), each with its own conventions of font, signs, etc.

So, for example, here is a deeper annotation to White's move~11, achieved by nesting variations (the relevant input is ``\texttt{Nxd8 [Nxh8 Qe7!\ [Bg4?\ Qd2 Nd4 Nc3 Qe7 Qh6}"\WBetter"\texttt{] Nf7 Bxf2+ Rxf2\linebreak gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7}"\BBetter"\texttt{] Bg4}''):
\makebarchess
\makegametitle
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [\betteris Nc3] d6 O-O?! h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! Nxd8 [Nxh8 Qe7! [Bg4? Qd2 Nd4 Nc3 Qe7 Qh6\WBetter] Nf7 Bxf2+ Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 Bf3\#] Nf3+! gxf3 Bxf3\toD*{Bxf3} \resigns|


\subsection{Other tools for annotation}\label{tools}

When you open a commentary (whether by "[" or by "\["), \TeXmate\ `undoes' the last move (assuming that the commentary will offer alternatives to it). Therefore the first move in the commentary will feature the same move number, and be played by the same side, that the last move in the main game (or in the mother variation). Sometimes, however, you open a commentary to talk about what the answer can be to that last move. For those occassions, \TeXmate\,2 has the command \DescribeMacro{\ahead}"\ahead". 

A good illustration is the last move of our Dubois--Steinitz game (see diagram). 

\begin{figure}[h]
\makediagrams
\end{figure}

The point is that Black threatens mate with the g3 pawn on h2; White could try to avoid it by taking the pawn, but then the rook mates on h1. What we want for the last move is `{\bfseries\bishop\takes f3} \withidea g\takes h2\#, and if now 15.~h\takes g3 \rook h1\#'. I just typed it manually, but because I know the move numbers, etc. The "\ahead"  mechanism provides automation:

\makebarother
\begin{verbatim}
|... Bxf3 \threat<gxh2\#>\[|, and if now 
|\ahead hxg3 Rh1\#\]\resigns|
\end{verbatim}

\makebarchess
\newgame
|1 e4 e5 Nf3 Nc6 Bc4 Bc5 d3 Nf6 Bg5?! [\betteris Nc3] d6 O-O?! h6 Bh4 g5 Bg3 h5! Nxg5 h4! Nxf7 hxg3!! Nxd8 [Nxh8 Qe7! [Bg4? Qd2 Nd4 Nc3 Qe7 Qh6\WBetter] Nf7 Bxf2+ Rxf2 gxf2+ Kxf2 Ng4+ Kg3 Qf6 Qf3 Qg7\BBetter] Bg4 Qe1 Nd4 Nc3\onlymove [h3 Ne2+ Kh1 Rxh3+ gxh3 Bf3\#] Nf3+! gxf3 \storegame{gf3} Bxf3 \threat<gxh2\#>\[|, and if now |\ahead hxg3 Rh1\#\]\resigns|

\bigskip\noindent
We can also refine the comment to moves 12 by Black and 13 by White with the specification of the threat. This could not have been done with "\threat" (section~\ref{annotation}), because the threat involves a whole variation, not simply a move. With \DescribeMacro{\Threat}"\Threat<"\meta{threatened variation}">", \TeXmate\ will typeset the \meta{threatened variation} with appropriate move numbers, etc. Unlike "\threat", "\Threat" does not include the \withidea\ sign, but this can be added to the first move if necessary. Sometimes a space must be forced---the idea is that "\Threat" can be used in connection with running text, so nothing is rigidly added. (On the other hand, since this is not a real variation playable on the board, \textsf{skak} is turned off.)

So, by saying `{\ttfamily Nd4 "\Threat<\ \withidea" Ne2+ Kh1 Rxh3+ gxh3 Bf3"\#"] Nc3"\onlymove"}' we get `\SkakOff|\black 12 Nd4\Threat<\ \withidea Ne2+ Kh1 Rxh3+ gxh3 Bf3\#> Nc3\onlymove\Threat<Bd5>|', a better option for these moves than we have had so far.


\SkakOn

\bigskip\noindent
\DescribeMacro{\dummy}\DescribeMacro{\ddummy}On the other hand, the commands "\dummy" and "\ddummy" make \TeXmate\ advance half a move or a complete move (that is, a movement by both players). They can be used in commentary to talk about what is to come, and they are in some senses more flexible than "\ahead". But they remain in \TeXmate\,2 mainly for compatibility. Their main drawback is that they confuse \textsf{skak} (that is following the game, so that the moves have to make sense, and the move numbers have to be consistent). In \TeXmate\,2, therefore, they immediately turn \textsf{skak} off: for the remainder of the variation (or sub-variation), \textsf{skak} will not try to follow the game. The main consequence of this is that the variation cannot be automatically diagrammed.

\DescribeMacro{\white}\DescribeMacro{\black}Similarly, the old commands "\white" and "\black", that force \TeXmate\ to take the next move as one done by the indicated side, have to turn \textsf{skak} off.

\subsection{Multiple variations}\label{vars}

In complicated games, a commentator will often need to examine several alternatives in a given position. The tools given so far are not satisfactory for this. In old \TeXmate\ it could be achieved by handling groups properly, but this is not exactly trivial for the user (who is thinking of variations that are already complicated as it is!). In addition, this approach puts \textsf{skak} off the game, and will create strange results.

So, \TeXmate\,2 provides  an additional tool for this, that turns out to be very powerful and useful. It is the family of environments "{variations}".

Again, the final position of Dubois--Steinitz provides illustration. White could also try \emph{advancing} the pawn. So, having two alternatives for White's 14, let's discuss the different "{variations}" environments.

\DescribeEnv{variations}\DescribeMacro{\var}The regular\\
"[\begin{variations}"\\
"\var" \meta{variation}\\
"\var"\meta{variation}\\
$\vdots$\\
"\end{variations}]" 

\noindent is designed for running commentary (not a lot of text). It makes the first move of each variation bold, and puts a `;' between variations:

\restoregame{gf3}
\@whitefalse\move14
|Bxf3 \threat<gxh2\#>[|If now |\ahead\begin{variations}
\var hxg3 Rh1\#%
\var h3 Rxh3\threat<Rh1\#>\end{variations}]\resigns|

\noindent was produced by:

\makebarother
\begin{verbatim}
Bxf3 \threat<gxh2\#>[|If now |\ahead\begin{variations}
\var hxg3 Rh1\#%
\var h3 Rxh3\threat<Rh1\#>\end{variations}]\resigns
\end{verbatim}


\DescribeMacro{\var*}The starred "\var*" forgoes any formatting (no bold, no semicolon). It is useful when one of the variations is embedded in text. You can always force the bold first move by saying "\var*\bfseries". In general, font can be set immediately after "\var" or "\var*", and it will apply to the first move of the variation only.

\DescribeEnv{variations*}"\begin{variations*}" creates a list of variations where no variation has formatting (thus giving a shorthand for many "\var*"'s). Of course it has to be closed by "\end{variations*}".

\bigskip\noindent
On the other hand, "\begin{variations}" has a very different behavior when it appears in a `text commentary' (i.e., one open with "\[" rather than "["). Then it invokes another environment (usually a list, by default an "{itemize}"), where each "\var" is an \SpecialIndex{\item}"\item". (The starred "variations*", however, behaves as in non-text commentary.)

So, a more explicit commentary to the final position of our game is:

\begin{verbatim}
...Bxf3\[| threatening mate on h2. If now 
|\ahead\begin{variations}
\var hxg3 Rh1\# 
\var h3 Rxh3\threat<Rh1\#>\end{variations}| 
In view of that, White resigned.|\]\resigns|
\end{verbatim}


\makebarchess
\restoregame{gf3}
\@whitefalse\move14
|Bxf3 \[| threatening mate on h2. If now |\ahead\begin{variations}
\var hxg3 Rh1\# 
\var h3 Rxh3\threat<Rh1\#>\end{variations}| In view of that, White resigned.|\]\resigns|

\bigskip
\DescribeMacro{\VariationsEnvironment}List environments defined by other packages (\textsf{paralist}, \textsf{enumerate}, etc.) can be used. For example:

\begin{verbatim}
\VariationsEnvironment
    {\begin{enumerate}[a)]}
    {\end{enumerate}
\end{verbatim}


\bigskip\noindent
Different "{variations}" environments can be nested one into another, at least in some combinations (that is, sometimes there are problems, but it's been hard to understand why). It seems that the main requirement is that they don't appear at the same level of commentary. Here is a full analysis from a game that actually calls for commentary this deep. This is the input:


\makebarother\begin{verbatim}
|Bd4!! f5\onlymove Bxg7+\onlymove Kxg7 
[\begin{variations}
\var Kg8 Qg3! Bxd6 Bxc6 Qxc6 Qg6! Rf7\onlymove 
    Bh6+ Kh8 Qxf7 Rg8 Bg5! Rg7\onlymove Qe8+ Bf8 
    [Rg8 Bf6+ Nxf6 Qxc6] Re1\WBetter
\var Kh7 Qh3+ Kxg7 Qg3+| transposes to the 
game|\end{variations}] 
Qg3+ Kh7 [Kf6? Qg5\#] Rb3!!| (threatening mate 
with |\Threat<Qh3+ Kg7 Rg3+ Kf6 Qh6\#>\[|) and now:
|\ahead\begin{variations}
\var Bxd6 \[| where I had calculated 
    |\ahead\begin{variations*}\var Qh4+ Kg7 Rg3+ Kf7 Qh5+!
    Kf6 Rg6+ Kf7 Rh6+ Ke7 Rh7+|, but  
    |\var Qg5!\end{variations*}\]| 
    with mate is more elegant. 
|\var Nf6 Qh3+ Kg7 Rg3+ Ng4 Rxg4+! fxg4 Qxg4+ Kh8 
    Qh5+ Kg8 Qh7\#|.
|\var Rf6 Qh3+ Kg7 [Rh6 Bxf5! exf5 Qxf5 Rg6 Rh3+| 
    and mate|] Rg3+ Rg6 Nxf5+! exf5 Rxg6+ Kxg6 
    Qxf5+ Kf8 Qh6+ Kf7 Bd5+ Ke8 Qg6+ Kf8 Qf7\#|.  
|\var Nce5! fxe5 Nxe5 Nxf5! exf5 Qxe5 Qf6 Bxf5+ 
    Qxf5 Qxe7+\WBetter|.
|\end{variations}\]|  
\end{verbatim}



This is the position:
\position[w 34]{3r1r1k/3nbpp/q1nNp/p/PpP1BP/3QB/6PP/1RR3K}

\preparediagram{Garcia--Winwood}{After 33\dots\bishop e7}

\makediagrams

\noindent and this is the output:

\makebarchess
|Bd4!! f5\onlymove Bxg7+\onlymove Kxg7 
[\begin{variations}%
\var Kg8 Qg3! Bxd6 Bxc6 Qxc6 Qg6! Rf7\onlymove 
    Bh6+ Kh8 Qxf7 Rg8 Bg5! Rg7\onlymove Qe8+ Bf8 
    [Rg8 Bf6+ Nxf6 Qxc6] Re1\WBetter
\var Kh7 Qh3+ Kxg7 Qg3+| transposes to the 
game|\end{variations}] 
Qg3+ Kh7 [Kf6? Qg5\#] Rb3!!| (threatening mate 
with |\Threat<Qh3+ Kg7 Rg3+ Kf6 Qh6\#>\[|) and now:
|\ahead\begin{variations}
\var Bxd6 \[| where I had calculated 
    |\ahead\begin{variations*}\var\bfseries Qh4+ Kg7 Rg3+ Kf7 Qh5+!%
    Kf6 Rg6+ Kf7 Rh6+ Ke7 Rh7+|, but  
    |\var\bfseries Qg5!\end{variations*}\]| 
    with mate is more elegant. 
|\var Nf6 Qh3+ Kg7 Rg3+ Ng4 Rxg4+! fxg4 Qxg4+ Kh8 
    Qh5+ Kg8 Qh7\#|.
|\var Rf6 Qh3+ \[| and now:|\begin{variations}
    \var Rh6 Bxf5! exf5 Qxf5 Rg6 Rh3+| and mate, as in the game.
    |\var Rg3+ Rg6 Nxf5+! exf5 Rxg6+ Kxg6 
    Qxf5+ Kf8 Qh6+ Kf7 Bd5+ Ke8 Qg6+ Kf8 Qf7\#|.|\end{variations}\]|%
|\var Nce5! fxe5 Nxe5 Nxf5! exf5 Qxe5 Qf6 Bxf5+ 
    Qxf5 Qxe7+\WBetter|.
|\end{variations}\]|

\subsection{Setting up a position}\label{position}

\DescribeMacro{\position}With the command "\position", you can set up the board to any given position. As in \textsf{skak} and old \TeXmate, the position itself is indicated in \acro{FEN} format: line by line, from top to bottom, lowercase for black pieces, uppercase for white, and numbers for empty squares---lines separated by "/". For "\position", the lines do not have to have all 8 squares: a "/" at the end of a line instructs \TeXmate\ to `fill in' the remaining places with empty squares. 

It's much easier just to see one than to read the paragraph above:
\begin{verbatim}
\position{r1bq1rk/4bppp/p1p/1p1nR/%
    8/1BP/PP1P1PPP/RNBQ2K}
\end{verbatim}
\noindent creates a position that can be visualized with \textsf{skak}'s "\showboard":

\fenboard{r1bq1rk/4bppp/p1p/1p1nR/8/1BP/PP1P1PPP/RNBQ2K w KQkq - 0 11}
\showboard

This is a Marshall-Attack position, and it's White's turn to make his eleventh move. If moves are going to be typeset for this diagram, we need \TeXmate\ to know it's move 11 by white. That's easy enough with old commands ("\white 11"), but in \TeXmate\,2 we have to instruct \textsf{skak} as well. 

In order to do that, "\position" has an optional argument, something like "[b 19]"---whose turn it is ("w" or "b"), and what move number it is. The diagram above should be created with

\begin{verbatim}
\position[w 11]{r1bq1rk/4bppp/p1p/1p1nR/%
    8/1BP/PP1P1PPP/RNBQ2K}
\end{verbatim}

\noindent The position is now in memory, and will be upgraded with any new moves. It can be sent, at any point, to diagram memory with "\toD". 

\bigskip
\noindent"\position" is designed for quick diagram drawing (where it does not matter who can castle where, etc.). For complete \acro{FEN} descriptions of positions (for example from an external source), \textsf{skak}'s \SpecialIndex{\fenboard}"\fenboard{"\meta{\acro{FEN} position}"}" can be used. It has been modified so that \TeXmate\ will know who is to play and what the move number is. 


\bigskip\noindent
The old \TeXmate\ command \DescribeMacro{\diagram}"\diagram", kept for compatibility, has the effect of "\position" followed by "\showboard". It now accepts the optional argument (turn and move number) and passes it on to "\position".

\section{Customization}

\subsection{The input}\label{input}

\DescribeMacro{\pieceinitials}By default, input goes by the piece initials customary in English (Rook, kNight, Bishop, Queen, King). This can be changed, so that input can be though of (or copy-pasted in) other languages. Adding the Pawn at the beginning, and going left-to-right through the initial position, "\pieceinitials{"\meta{new initials}"}" will change the initials.

The effects of this are:
\begin{itemize}
\item Input in chess mode uses the new initials for pieces.
\item \textsf{skak} will also change. Even the commands that are not interfaced by \TeXmate\ (notably "\showonly{"\meta{pieces-to-show}"}" will make use of the new initials.
\item Position setup with "\position", "\diagram", and "\fenboard" will use the new language.
\item \textsf{chessfss}-directed output after \SpecialIndex{\usetextfig}"\usetextfig" will use the new language.
\end{itemize}

The architecture of the different programs even allows input in one language and output in another: issue "\pieceinitials" for the input language, and follow it immediately with \textsf{chessfss}'s \SpecialIndex{\setfigtextchars}"\setfigtextchars" to set the output. (Of course, "\usetextfig" must be in place for the latter to have any consequences.)

There is no more customization to the input to be done: \textbf{castling} can be input either with zeroes or with O's. \textbf{Captures} can be input either with `"x"' or with `":"'---or not at all, hoping for \textsf{skak} to be OK with that (it often is). Of course, in the latter case you would lose any automatic formatting of captures. \textbf{Checks} are a `"+"' or nothing---no problem here. It is strongly recommended to input \textbf{Promotions} with the `"="' sign (`"g1=Q"'), because \textsf{skak} will understand it.

So, the system is immediately ready to read PNG games (without commentary), as long as the input language (the piece initials) is not changed.

\subsection{The output: signs}\label{signs}

\DescribeMacro{\Castle}If you want castles like ``0--0--0'', type "\Castle0" (default). If you like them like ``O--O--O'', type "\CastleO".

\DescribeMacro{\takes}Predefined essentially as "$\times$", you can "\renewcommand\takes" to substitute your favorite sign for captures (a colon? nothing?).

\DescribeMacro{\checksign}\DescribeMacro{\#}Checks are "\checksign" (`+' by default). Mate is "\#" (`\#') by default. There is a "\mate" sign in the informator fonts of \textsf{skaknew}, that looks like `\mate', and to use it you can "\renewcommand\#{\mate}".

\subsection{The output: punctuation}\label{punct}

The material between moves and move numbers can be customized. The appropriate commands, their function, and their default, are in Table~\ref{moves}.

\begin{table}[h]
\centering
\begin{tabular}{lm{.5\textwidth}l}
\textsf{Command} & \textsf{Meaning} & \textsf{Default}\\\hline
"\afterno" & What comes between the move number and White's move & ".~"\\\hline
"\afterw" & What comes between White's move and Black's & \verb*" "\\\hline
"\afterb" & What comes between Black's move and the (immediately) following move number & \verb*" "\\\hline
"\beforeb" & What comes before Black's move when the variation is resumed & "\the\move\dots"\\\hline
"\beforeno" & What comes before the move number (always, sometimes after "\afterb"). & nothing\\\hline
\end{tabular}
\caption{Punctuation commands}\label{moves}
\SpecialIndex{\afterno}\SpecialIndex{\afterw}\SpecialIndex{\afterb}\SpecialIndex{\beforeb}\SpecialIndex{\beforeno}
\end{table}

\subsection{The output: fonts and contexts}\label{fonts}

There are four levels of commentary in \TeXmate, as summarized in Table~\ref{levels}.

\begin{table}[h]
\centering\begin{tabular}{clll}
\textsf{Level no.} & \textsf{Context} & \textsf{Font} & \textsf{Delimiters}\\\hline
i &Main game & boldface & nothing\\
ii & Comm.\ level 1 & normal & [ and ]\\
iii & Comm.\ level 2 & normal & ( and )\\
iv & Comm. level 3 & italic & ( and )\\\hline
\end{tabular}
\caption{Levels, default fonts and delimiters}\label{levels}
\end{table}

\DescribeMacro{\...font}\DescribeMacro{\...open}\DescribeMacro{\...close}Fonts and delimiters can be changed. Each level has commands for `font,' `open,' and `close.' Those of level three, for example, are "\iiiopen", "\iiiclose", and "\iiifont". These three are defined by default as follows:

"\let\iiifont\normalfont"

"\newcommand\iiiopen{(}"

"\newcommand\iiiclose{\leavevmode\unskip)}"

\noindent and the others are analogous. They can all be redefined. The \SpecialIndex{\unskip}"\leavevmode\unskip" in "\iiiclose" removes the space that is added by \TeXmate\ after the last move. 

Similarly, the space before and after the delimiters is embedded in \TeXmate. "\unskip", or its safer version "\leavevmode\unskip" can be used to remove these spaces. For example, to use the em-dash as delimiter for the third level, the redefinitions should be

\begin{verbatim}
\renewcommand\iiiopen{\leavevmode\unskip---}
\renewcommand\iiiclose{\leavevmode\unskip---}
\end{verbatim}

\bigskip\noindent
\DescribeMacro{\...opent}\DescribeMacro{\...closet}The delimiters work for commentaries open with "[". For commentaries with "\[" (`text commentaries'), the commands are "\iopent" and "\icloset", etc.\ (`"t"' for `text'). In principle they are all defined as "\relax" (nothing), but they could be redefined so that, for example, all commentary at level~ii starts on a new paragraph.


\bigskip\noindent
The regular variations in a "{variations}" environment within a "[" commentary (not a "\[" one) make their first move bold by default. \DescribeMacro{\varfont}This is command "\varfont", which is originally equivalent to "\bfseries", but can be changed. This is invoked by "\var", but not by "\var*".

\bigskip\noindent
\DescribeMacro{\steplevel}\DescribeMacro{\backlevel}Levels can be arbitrarily traversed with commands "\steplevel" and "\backlevel". This only affects fonts and typesetting uses, so there is no concern about getting \textsf{skak} confused. It might confuse the reader, though.


\subsection{Diagrams}\label{custdiagrams}

This section applies to intrinsic \TeXmate\ diagram-drawing tools. The tools of both \textsf{skak} (notably "\showboard", that typesets the current position) and \textsf{chessfss} (that provides commands for font, size, each piece on each kind of square, etc.), are kept independent, so that modularity is ensured.

In fact, \TeXmate\,2 does not have some possibilities of old \TeXmate. Its diagrams are always $8\times8$ squares. \textsf{chessboard} provides excellently for less standard situations. This program works hand in hand with \textsf{skak}, which means that when \TeXmate\ is used with this latter, there will be also communication with \textsf{chessboard}.\footnote{However, \textsf{skak} and \textsf{chessboard} do not pass information on to \TeXmate.}


\subsubsection{Diagram font, size, etc.}

\TeXmate\ does not deal with these matters, which are delegated to the package \textsf{chessfss}. The latter's \SpecialIndex{\setboardfontsize}"\setboardfontsize{12pt}" is issued by \TeXmate\ as a default, but there is no further handling. In addition, this latter default only has an effect when \textsf{skak} is not loaded, since otherwise \textsf{skak}'s commands (\SpecialIndex{\tinyboard}\SpecialIndex{\smallboard}\SpecialIndex{\normalboard}"\tinyboard", "\smallboard", "\normalboard") take precedence. \TeXmate\ sets "\smallboard" by default.


\subsubsection{Issuing the diagrams}\label{diagiss}
Diagrams are \emph{issued} at one point, and \emph{printed} at another. This allows the typesetting of diagrams side by side without regard to what the current position. 

\DescribeMacro{\diagramsign}Issuing the diagrams is done by the commands explained in section~\ref{diagrams}, namely \SpecialIndex{\toD}\SpecialIndex{\toD*}\SpecialIndex{\preparediagram}"\toD", "\toD*", and "\preparediagram". The regular version "\toD" inserts the contents of \diagramsign, which by default is `{~\mdseries(\textit{D})}', but can be freely redefined. "\toD*" does not insert "\diagramsign".

The diagrams are then put in memory---as \LaTeX\ boxes---together with some accompanying material: player names, move number, etc. (Note that \textsf{skak}'s \SpecialIndex{\showboard}"\showboard" or \textsf{chessboard}'s \SpecialIndex{\chessboard}"\chessboard" do not `issue' a diagram in \TeXmate's terms, but simply print the current or given position.) This section describes the basic customization of the diagram boxes. It actually tells some white lies, so section~\ref{further} below explains in full detail.

By default, diagrams:
\begin{itemize}
\item Are not numbered.
\item Put Black's name (whatever was given by \SpecialIndex{\bname}"\bname") above the diagram, boldface.
\item Put White's name \SpecialIndex{\wname}("\wname") below, boldface.
\item Typeset the last move (the argument to "\toD" or "\toD*") below White's name.
\item \textbf{Analysis} diagrams (diagrams issued within a commentary, i.e., between "["~and~"]" or "\["~and"\]") override the default behavior: instead of the players' names, the word `Analysis' appears at the top of the diagram, and the last move appears at the bottom.
\end{itemize}


\begin{table}
\begin{tabular}{lm{.6\textwidth}}\hline
 "\topdiagramnames" & Players' names  on top of the diagram. Like this: `\textbf{Dubois--Steinitz}'.\\\cline{2-2}
"\bottomdiagramnames" & Players' names  at the bottom of the diagram.\\\cline{2-2}
 "\diagramnames" & White's name at the bottom, Black's on top (default).\\\cline{2-2}
 "\nodiagramnames" & No  players' names.\\\hline
"\diagramnumber" & Diagram number on the top of the diagram (above names, if any). \newline The number is formatted by the current version of "\TheDiagram"---by default something like `\textit{\textbf{4}}'. \newline Regular (lower-case) "\thediagram" is intended for running-text reference. \\\cline{2-2}
 "\nodiagramnumber" & No diagram numbers (default).\\\hline
 "\leftdiagramturn" & Turn marker at the left of the diagram.\\
 "\rightdiagramturn" & Turn marker at the right of the diagram.\\
 "\nodiagramturn" & No turn marker (default).\\\hline
 "\diagrammove" & Last move at the bottom (default).\\
 "\nodiagrammove" & No last move.\\\hline
"\analysistop" & What goes by default on top of analysis diagrams. Defined originally as `Analysis'.
\end{tabular}
\SpecialIndex{\topdiagramnames}\SpecialIndex{\bottomdiagramnames}\SpecialIndex{\diagramnames}
\SpecialIndex{\nodiagramnames}\SpecialIndex{\diagramnumber}\SpecialIndex{\nodiagramnumber}\SpecialIndex{\leftdiagramturn}
\SpecialIndex{\rightdiagramturn}\SpecialIndex{\nodiagramturn}\SpecialIndex{\diagrammove}\SpecialIndex{\nodiagrammove}
\SpecialIndex{\analysistop}\SpecialIndex{\thediagram}\SpecialIndex{\TheDiagram}
\caption{Command for diagram information}\label{diagramcommands}
\end{table}

\noindent The commands of Table~\ref{diagramcommands} govern these defaults. They are user-modifiable with "\renewcommand", with one warning: these commands (and in general non-chess stuff) should go \emph{outside} chess mode. 

\DescribeMacro{\whiteturnmarker}\DescribeMacro{\blackturnmarker}When a turn marker is requested, \TeXmate\ will use the contents of either "\whiteturnmarker" or "\blackturnmarker". These, by default, are defined as:

\begin{verbatim}
\newcommand*\whiteturnmarker{%
    \raisebox{.75\expandafter\ht\csname 
    chessdiag\@roman\@tempcnta\endcsname}{%
    \textsl{W}}\ }
\end{verbatim}

\noindent where the first part is responsible for raising the symbol to three-quarters the height of the diagram. Modification of the coefficient .75 and of the actual contents of the box should (or the space after it) should pose no problem.


\DescribeMacro{\nextdiagramtop}\DescribeMacro{\nextdiagrambottom}On the other hand, it is possible to set the top and the bottom of one diagram (the one that is issued next, with "\toD" or "\toD*") with "\nextdiagramtop{"\meta{header}"}" and "\nextdiagrambottom{"\meta{footer}"}". 

For example:

\begin{verbatim}
\nextdiagramtop{\wname--\bname}
\nextdiagrambottom{Final position after}
\toD*{Bxf3}
\makediagrams
\end{verbatim}

\noindent produces

\nextdiagramtop{\wname--\bname}
\nextdiagrambottom{Final position after}
\toD*{Bxf3}
\makediagrams

\noindent \DescribeMacro{\diagramtop}\DescribeMacro{\diagrambottom}\DescribeMacro{\wname}\DescribeMacro{\bname}To set the top or bottom of \emph{all} future (non-analysis) diagrams at once, the commands "\diagramtop" and "\diagrambottom" can be redefined with "\renewcommand". For this, the commands "\wname" and "\bname", which hold the player names (as given at the beginning of the game with \SpecialIndex{\whitename}\SpecialIndex{\blackname}"\whitename" and "\blackname", as in section~\ref{markup}), might prove useful.


\bigskip\noindent
\DescribeMacro{\makediagramsfont}All the text typeset by "\makediagrams" is subject to "\makediagramsfont". By default it means "\small", but it can be changed at any point.

\subsubsection{Printing the diagrams}\label{diagpr}
The diagrams are actually typeset with the command \SpecialIndex{\makediagrams}"\makediagrams". This command will typeset, in principle, all diagrams in memory, framed and separated by "\hfill"'s. (There is therefore no need for "\centering", which in fact can disturb the resulting layout.) 

An optional argument to "\makediagrams["\meta{n}"]" will tell \TeXmate\ to typeset only the first $n$ diagrams in memory. The rest of the diagrams take then the memory positions of those that were typeset.

\DescribeMacro{\DiagramCache}By default, the number of diagrams that can be held in memory is~3. It can be enlarged with the command "\DiagramCache{"\meta{number}"}". So, a page of nine diagrams like page~\pageref{problems} below can be composed thus (the counter is reset because previous diagrams in this document have stepped it):

\begin{verbatim}
\DiagramCache{9}
\setcounter{diagram}{0}
\tinyboard
\diagramnumber
\leftdiagramturn
\let\makediagramfont\footnotesize
 % First diagram
\position[w 22]{r1q4r/pp2bQ/2p2p1k/6pp/4N/6R/PPP2PPP/2KR}
\preparediagram{}{22.~?}\label{pageref}

 % Second diagram
\position[b 20]{r5k/1bpp1ppp/1p1b3r/pP2n1q/2PB/P3PPP/3QBR1P/R2N2K}
\preparediagram{}{{20\dots?}}

etc.

% Ninth diagram
\position[w 27]{2r1r1k/p1q2ppp/6n/1p1Q/2N1P/P3B2P/2R2PP/6K}
\preparediagram{}{27.?}

\begin{figure}[p]
\makediagrams[3]

\smallskip\makediagrams[3]

\smallskip\makediagrams[3]
\end{figure}
\end{verbatim}

\DiagramCache{9}
\setcounter{diagram}{0}
\tinyboard
\diagramnumber
\leftdiagramturn
\let\makediagramfont\footnotesize

\position[w 22]{r1q4r/pp2bQ/2p2p1k/6pp/4N/6R/PPP2PPP/2KR}
\preparediagram{}{22.~?}

\position[b 20]{r5k/1bpp1ppp/1p1b3r/pP2n1q/2PB/P3PPP/3QBR1P/R2N2K}
\preparediagram{}{20\dots?}

\position[w 13]{r2qr1k/ppp1bppp/5n/1N1PQ1B/8/8/PPP2PPP/R4RK}
\preparediagram{}{13.~?}

\position[w 34]{3r1r1k/3nbpp/q1nNp/p/PpP1BP/3QB/6PP/1RR3K}
\preparediagram{}{34.~?}

\position[w 15]{rnbr2k/pp2bppp/4pn/1N2N/2B1q/4B/PP2QPPP/R2R2K}
\preparediagram{}{13.~?}

\position[b 22]{1r2r1k/5ppp/R2b/3p3q/3P/2P1B1Pb/1P3P1P/1N2R1KQ}
\preparediagram{}{22\dots?}

\position[b 44]{8/5k1r/4pP1p/3pP1pP/2p1p1P/5n1Q/r/1R5K}
\preparediagram{}{44\dots?}

\position[b 22]{1k4r/p1q2p/Q1p1pp/3p3p/4rP/1P/P1P1NK/3R1R}
\preparediagram{}{22\dots?}

\position[w 27]{2r1r1k/p1q2ppp/6n/1p1Q/2N1P/P3B2P/2R2PP/6K}
\preparediagram{}{27.?}

\begin{figure}[p]
\makediagrams[3]\label{problems}

\smallskip\makediagrams[3]

\smallskip\makediagrams[3]
\end{figure}


\bigskip
\noindent Almost all the layout parameters described in the previous section have an effect when the diagram is \emph{issued}. However, the switches for move number and last move (i.e., whether and where they should be put) are enforced at the moment of printing with "\makediagrams".

\subsubsection{Diagrams and cross refences}\label{diagref}

Diagrams are counted (whether the number is printed or not) with the "diagram" counter. When diagrams are printed with \SpecialIndex{\makediagrams}\SpecialIndex{diagram}\SpecialIndex{\label}"\makediagrams", this counter is "\refstep"'ped, i.e., a "\label" can be assigned to it for cross references. The mechanism is not completely implemented in \TeXmate, not least because there is little of a `standard' use. As it stands, the main problem is that the user cannot assign individual "\label"'s to diagrams that printed with the same "\makediagrams". On the other hand, if the latter command is used for one diagram at a time, cross referencing is fully functional.

\subsubsection{Detailed mechanism description}\label{further}


The commands described in the previous section are not intended to provide full control on diagram layout, but rather simple tools for the needs of most of the time. More extensive customization will require hands-on programming. The diagram mechanism in \TeXmate\,2 has been designed to make this task easier, should it arise. This section explains it.

As has been said, a diagram is \emph{issued} first and \emph{retrieved} later. The issuing commands \SpecialMainIndex{\toD}\SpecialMainIndex{\toD*}\SpecialMainIndex{\preparediagram}("\toD", "\toD*", and "\preparediagram") build four \LaTeX\ boxes and one command containing the diagram and the accompanying information. The names of these boxes contain the diagram number in lowercase Roman numerals. If, for example, a diagram in the third memory position is being issued, the following boxes are created:
\begin{itemize}
\item "\chessdiagiii" holds the diagram itself---and it is a copy of either "\showboard" or (when \textsf{skak} is not loaded) \TeXmate's own typesetting of the diagram with \textsf{chessfss} commands.
\item "\chessdiagiiitop" holds whatever goes on the top of the diagram. It can be: $a)$~with the "\...diagramnames" switches, the names of the players (or of Black); $b)$ whatever was defined by the user as "\diagramtop"; or $c)$ the first argument of the user's "\preparediagram".
\item "\chessdiagiiibottom" holds whatever goes on the bottom of the diagram. Analogous.
\item "\chessdiagiiimove" holds the typeset form of the argument to "\toD" or "\toD". It is empty in the case of "\preparediagram".
\end{itemize}
\SpecialIndex{\chessdiag...}\SpecialIndex{\chessdiag...top}\SpecialIndex{\chessdiag...bottom}
\SpecialIndex{\chessdiag...move}

\SpecialIndex{\chessdiag...turn}In addition, each diagram also has a command, "\chessdiagiiiturn" for the third diagram. This is set, according to whose turn it is when the diagram is issued, to expand to either "\whiteturnmarker" or "\blackturnmarker".\SpecialIndex{\whiteturnmarker}\SpecialIndex{\blackturnmarker}

The default \SpecialMainIndex{\makediagrams}"\makediagrams" (the command that is most likely to change in customization) is a fairly simple usage of these boxes and commands. Essentially, it follows the switches for diagram number, turn, and last move ("\if@numbertop", "\if@turnleft", "\if@turnright", "\if@movebottom") to typeset a "\shortstack[c]" containing, from top to bottom

\begin{center}
the diagram number

"\chessdiagiiitop"

"\chessdiagiii"

"\chessdiagiiibottom"

"\chesdiagiiimove"
\end{center}
\noindent For items to the left or the right, it builds 0-wide boxes (so that they don't affect centering and spacing) that contain "\whiteturnmarker" or "\blackturnmarker".

The same applies for all diagrams, just replacing the inner "iii" by the Roman numeral (lowercase) of the position of the diagram in memory. Note that this number is not the diagram~number, but its slot in memory. After using the boxes in that way, \SpecialMainIndex{\makediagrams}"\makediagrams" calls "\@killdiagrams", that deletes the diagrams from memory (and moves any remaining diagrams to the first memory positions).

\subsection{Cosmetics}\label{cosmetics}

There are other tools in \TeXmate\ that are provided `as is,' without complicated customization, because there is no standard. These should be modified or directly replaced to follow individual preferences. 

The game title is one of them. The pieces of information already implemented (with the user commands described in section~\ref{markup}) are: the players' names, held in "\wname" and "\bname"; their ratings, "\@welo", "\@belo"; the event, "\@tourn"; the opening, "\@opening"; and the \acro{ECO} code, held in "\@eco". The latter is the only one that adds something to the user's input: "\def\@elo{ -- \textbf{#1}}".

Then, \SpecialMainIndex{\makegametitle}"\makegametitle" simply uses these variables. Redefining it will not affect the program in any way.

\bigskip
\noindent\DescribeMacro{\result}Game result is also a `cosmetic.' The current definition of "\result{"\meta{result}"}" puts a boldface copy of its argument on the right margin of the current line, if it fits, or of the next one, if it doesn't. (When the command is encountered not in the main game, but in the commentaries, the argument is simply typeset.) 

\DescribeMacro{\whitewins}\DescribeMacro{\blackwins}\DescribeMacro{\drawn}\DescribeMacro{\resigns}"\whitewins" simply means "\result{1\,:\,0}"; "\blackwins" and "\drawn" are analogous. Finally, "\resigns" issues "\whitewins" if it's Black's turn, or "\blackwins" if it's White's.

\section{\protect\TeXmate\,2 and \textsf{skak}}\label{skak}

The command \SpecialIndex{\showboard}"\showboard" in the package \textsf{skak} has been mentioned repeatedly in this manual. It can be used with \TeXmate, and it provides total flexibility for the typesetting of the diagram, forgoing the automatic formatting that \TeXmate\ performs. 

Another important command, also mentioned before, is \SpecialIndex{\fenboard}"\fenboard".

But there are other commands from \textsf{skak} whose use might prove an extension to \TeXmate's capabilities. This is mainly connected to saving and restoring positions in memory or disk. \textsf{skak}'s \SpecialIndex{\storegame}"\storegame{"\meta{key}"}" saves a position in memory, to be restored by \SpecialIndex{\restoregame}"\restoregame{"\meta{key}"}". With this tool, for example, it is possible to quote an independent game in commentary, and still have the capabilities of \textsf{skak}. All that is needed is to store the main game, type \SpecialIndex{\newgame}"\newgame", quote the alternative game, issue any diagrams from it, and restore the main game when done. (\textsf{skak} also offers \SpecialIndex{\sidegame}"\sidegame" for this purpose, but its use with \TeXmate\ is not as straightforward.



\bigskip
\noindent \DescribeMacro{\SkakOff}\DescribeMacro{\SkakOn}If, for any reason, the capabilities of \textsf{skak} are an obstacle rather than a utility, \textsf{skak} can be turned off with "\SkakOff". \TeXmate\ will then typeset the moves as given, without passing them onto \textsf{skak}, and any potential problems and error messages caused by \textsf{skak} trying to follow the game will be avoided. "\SkakOn" turns all capabilities back on.

\TeXmate\,2 has a small tracing utility of \textsf{skak}'s workings: option \texttt{[diagnostics]} will type out messages with the moves that have been passed on to \textsf{skak}, helping understand where the latter stands respect to the typeset game and analysis.

\makebarother

\section{Chess symbols}

Chess symbols, as chess fonts, are delegated to \textsf{chessfss} in \TeXmate\,2. There are some differences with the output of \TeXmate, for the latter used to modify some of the symbols (in size, in position, etc.). It has been decided, for the sake of modularity, to forgo these modifications in \TeXmate\,2. Table~\ref{symbols} lists the symbols (with \TeXmate\ command names).

\makebarother
\begin{table}
\centering
\begin{tabular}{lc}\hline
\verb"\wbetter" & \wbetter\\
\verb"\bbetter" & \bbetter\\
\verb"\wBetter" & \wBetter\\
\verb"\bBetter" & \bBetter\\
\verb"\WBetter" & \WBetter\\
\verb"\BBetter" & \BBetter\\
\verb"\equal" & \equal \\
\verb"\unclear" & \unclear\\
\verb"\compensation" & \compensation\\\hline
\verb"\development" & \development\\
\verb"\spaceadv" & \spaceadv \\
\verb"\attack" & \attack \\
\verb"\initiative" & \initiative \\
\verb"\counterplay" & \counterplay \\\hline
\verb"\zugzwang" & \zugzwang \\
\verb"\onlymove" & \onlymove\\
\verb"\withidea" & \withidea \\
\verb"\betteris" & \betteris \\\hline
\verb"\boardfile" & \boardfile \\
\verb"\boarddiagonal" & \boarddiagonal\\
\verb"\boardcenter" & \boardcenter \\
\verb"\kingside" & \kingside  \\
\verb"\queenside" & \queenside  \\\hline
\verb"\weak" & \weak \\
\verb"\ending" & \ending \\
\verb"\bishops" & \bishops \\
\verb"\oppositebishops" & \oppositebishops\\
\verb"\samebishops" & \samebishops\\\hline
\verb"\unitedpawns" & \unitedpawns  \\
\verb"\separatedpawns" & \separatedpawns  \\
\verb"\doubledpawns" & \doubledpawns \\
\verb"\passedpawn" & \passedpawn \\
\verb"\pawnsno" & \pawnsno\\\hline
\verb"\timetrouble" & \timetrouble \\
\verb"\with" & \with \\
\verb"\without" & \without \\
\verb"\chessetc" & \chessetc  \\\hline
\end{tabular}
\caption{Chess symbols}\label{symbols}
\end{table}

\clearpage
\PrintIndex
\end{document}