path: root/Master/texmf-dist/doc/latex/texmate/texmatesample.tex

\documentclass[10pt]{article}
\usepackage{doc}
\usepackage{texmate}
\title{\TeX mate\\(comprehensive chess annotation in \LaTeX)\\ Usage sample and reference}
\date{03/13/05}
 \author{Federico Garcia\\\texttt{federook@gmail.com}}
\begin{document}
\maketitle

\tableofcontents

\section{Introduction}
I tried using the \textsf{skak} package.\footnote{By Torben Hoffmann, 2001.} I liked very much its beautiful chess fonts. But somehow I got frustrated. I forget exactly what it was, but it frustrated me. It was about annotating the games, somehow the syntax requirements that \textsf{skak} imposed were too cumbersome when an analysis had many variations and subvariations. 

So I simply didn't do it in \TeX---I think I didn't do it at all. Until one day I got a game that I wanted to publish. So I went to Word---yes, yes, I'm sorry, but I had no option. Besides, the editors of the \emph{Pennswoodpusher} certainly used Word, so a Word file would be better. 

I commented my game, and `translated' it into a more readable format to send it to my friends. I wanted figurines instead of initials for the pieces (I used a True~Type for this), I wanted the main game to be separated from the commentary by paragraph breaks, sub-variations to be indicated differently, etc. The contents of the game, and even the analyzed variations, were of course the same. I started looking at several books to see their chess-formatting habits. 

And I figured that being able to transcribe a game from format to format without having to edit the input is, clearly, a task for \TeX\dots

\TeX mate is the result. The emphasis is on the formatting of annotated games of chess. \textsf{skak}'s focus seems to be more graphical: beautiful tools for diagrams (the package itself even keeps track of the position according to the moves in the game---which of course is the deep reason why it's not really flexible about variations and alternative lines---those confuse it). 

Commented code is in the file \texttt{texmate.dtx}. A user's manual required using the package, so it comes as this one separate file.

\section{A note on installation}
Installation is straightforward: the packages is made of a `source' (\texttt{texmate.dtx} and \texttt{texmate.ins}), which generate a `tex' (\texttt{texmate.sty}) and a `doc' (\texttt{texmate.dvi}) with the commented code. In addition, there is this extra `doc,' \texttt{texmatesample.tex}.

But the fonts of the \textsf{skak} package have to be installed. The easiest would of course install \textsf{skak} itself. I have included the fonts. There are \texttt{.mf} files (`source'), \texttt{.fd} files (`vf') and a \texttt{.map} file. 

\section{Basic conventions}
The moves are input with the (short) algebraic system of notation.

\begin{description}
\item[Pieces] Default is English piece initials (Rook, kNight, Bishop, Queen, King). But this can be changed with \verb"\pieceinitials"\DescribeMacro{\pieceinitials}. In fact, \TeX mate itself uses this command to initialize the default: \verb"\pieceinitials{PRNBQK}". The argument is the initials to be used, respectively, for pawn and then left to right in White's initial position. The initial for pawn is given only for diagrams---in game notation the pawn is not indicated.

\item[Move Numbers] \TeX mate keeps track of the move number. Inputting the numbers is totally optional to the user, and although it may be helpful for later edition of the document, sometimes the variations and sub-variations are so complicated that one loses track of them. If the user does indeed input the number, it will override \TeX mate's count. 

\item[Delimiters] Moves (and move numbers) are delimited by spaces, periods, or semicolons. None of these will be typeset directly, since \TeX mate takes care of all formatting and punctuation. Of course, this is customizable.

\makebarother
\item[Chess mode] All this is done within `chess mode:' just as \verb"$" changes to math mode, \verb+|+ changes to chess mode. Sometimes (notably tables) you need \verb"|" for other things, so you can turn its chess meaning off with \DescribeMacro{\makebarother}\DescribeMacro{\makebarchess}\verb"\makebarother". To turn it back on, \verb"\makebarchess".

\item[Checks] should be input (with \verb"+"), even if you don't like them to be typeset. There is a \verb"\checksign" command (default `\checksign') that you could redefine as nothing.

\item[Captures] too should be input,  with \verb"x", even if not intended to be visible. The command \verb"\takes" holds the sign that will be used for them (default a space-trimmed \verb"\times").

\item[Mate] is done through \verb"\mate". Alternatively, of course, \verb"\#".

\item[Promotions] are kind of an exception. Due to how \TeX mate works, the particle `\verb"c8N"' will produce literally `c8N,' instead of `c8\knight.' I did not think it was worth to change the whole nature of the system just for this, so I will ask the user to use piece-name commands for promotions: `\verb"c8\knight"' (or `\verb"c8=\knight",' as some people do).
\end{description}

\makebarchess
\section{Formatting and punctuation}
The output will be consistent as to punctuation marks. All of the following input streams:\makebarother

\verb"|1. e4 e5; 2. Nc3 Nf6; 3. Bb5 a6|",

\verb"|1 e4 e5 2 Nc3 Nf6 3 Bb5 a6|", and even

\verb"|1 e4 e5 Nc3 Nf6 ; Bb5 a6|", 

\noindent will produce, with default settings, \makebarchess`|1 e4 e5 2. Nc3 Nf6; 3 Bb5 a6|.' This format can be changed redefining the following commands:

\makebarother
\begin{center}
\begin{tabular}{|lp{.8\textwidth}|}\hline
\verb"\afterno" & What comes after the number (\verb".~" by default)\\
\verb"\afterw" & What comes between white's and black's moves (\verb*" ")\\
\verb"\afterb" & What comes between black's move and the next number (\verb*"; ")\\
\verb"\beforeb" & What comes before black's move when it's resuming the variation (\verb*"\the\move.\ \dots~")\\
\verb"\beforeno" & What comes before the number.\\\hline
\end{tabular}
\end{center}
\makebarchess

The character that symbolizes each pieces (by default the figurines) is contained in the commands \verb"\rook", \verb"\knight", \verb"\bishop", \verb"\queen", and \verb"\king", and can be changed at any moment. These piece-name commands, as well as those for chess symbols, can be used in running text. Or in chess mode, for that matter.

\section{Commentary}
Within chess mode, the character \DescribeMacro{[}\DescribeMacro{]}\verb"[" opens a commentary. \TeX mate will then expect a move that is an alternative to the one in the text. For example:

\makebarother
\verb"|34. Nd5? [Ne4!] Bxd5! [Qxd5? 35. Re1!\wBetter]|"
\makebarchess
\newgame

|34. Nd5? [Ne4!] Bxd5! [Qxd5? 35. Re1!\wBetter]|

\smallskip

Commentaries can be nested:

\makebarother
\verb"|35. Re1 [cxd5?! Qxd5 [Kh8? dxc6\wbetter [c3!?]]\; Kh1]|"
\makebarchess

|35. Re1 [cxd5?! Qxd5 [Kh8? dxc6\wbetter [c3!?]]\; Kh1]|

\smallskip
As you see, \TeX mate takes care of punctuation and fonts. But before going about modifying \DescribeMacro{\[}\DescribeMacro{\]}this things, there is an alternative way of commentary: \emph{control~sequences} \verb"\[" and \verb"\]". They are intended for freer commentary: they do not insert any punctuation, and the user has total control over the way the commentary is typeset.

\DescribeMacro{\ifont}\DescribeMacro{\iifont}\DescribeMacro{\iiifont}\DescribeMacro{\ivfont}All of this can be modified. The samples that follow later in this document are probably the best way to learn about this. But here is the abstract explanation: the main game (boldface by default) is `level' 1. There are 4 levels, and their fonts are controlled by \verb"\ifont", \verb"\iifont", \verb"\iiifont", and \verb"\ivfont". They can be defined as standard commands like \verb"\bfseries", but there's one caveat: this doesn't apply by itself to the chess font. Changing levels 3 and 4 is easy; for levels 1 and 2, look at the code of \TeX mate.

\DescribeMacro{\iopen}\DescribeMacro{\iclose}\DescribeMacro{\iiopen}\DescribeMacro{\iiclose}\marginpar{\hfill$\vdots$\quad\null}The symbols that mark the opening and closing of the commentaries are typeset by the commands \verb"\iopen", \verb"\iclose", \verb"\iiopen", \verb"\iiclose", etc. These are called by the characters \verb"[" and \verb"]". The control sequences \verb"\[" and \verb"\]" call for \verb"\iopent", \verb"\icloset", etc.\ (`\verb"t"' for `text'). If you are going to change these, remember that the first level of commentary is level~2 (1 is the game itself).

Text can be inserted in commentaries, simply by using the \makebarother\verb"|" character properly. Examples in the next sections illustrate.

\subsection{Additional commenting tools}
\DescribeMacro{\dummy}\DescribeMacro{\ddummy}With \verb"\dummy" and \verb"\ddummy" you can insert `dummy' moves. If \TeX mate was expecting White's move number 32, \verb"\dummy" will make it expect Black's move number 32 (half a move is skipped). With \verb"\ddummy", it will expect White's move number 33 (a entire move was skipped). Remember that you can change the move number at any moment simply by typing the new number in the input.

\DescribeMacro{\white}\DescribeMacro{\black}With \verb"\white" you force \TeX mate to handle the next move as one by White. \verb"\black" forces it to handle it as one by Black. With these commands, \TeX mate does not try to keep track of the move number, and so they should be used in connection with numbers. Both \verb"| 34 \black| " and \verb"|\black 34|" work in the same way: \TeX mate will expect Black's move number 34.

\DescribeMacro{\steplevel}\DescribeMacro{\backlevel}If you want to use the fonts of another level without actually invoking a commentary, you can use \verb"\steplevel" and \verb"\backlevel". The former increases the level by 1, the latter decreases it by 1. Both then load the corresponding font for the level. 

Remember that the main game is level 1, the last level of commentary is level 4.

\DescribeMacro{\threat<...>}With the \verb"\threat" macro you can introduce threats. This command has an argument, enclosed within \verb"<" and \verb">"; the argument is set \emph{as regular text} (i.e., not in chess mode). Before it, though, the sign \withidea\ is appended. For example:

\verb"|17. Nce5!\threat<h4!\wBetter\attack> Ne8! h4? f5!|"

\makebarchess
|17. Nce5!\threat<h4!\wBetter\initiative> Ne8! h4? f5!|
\makebarother

\section{Diagrams}
Producing the diagrams is really straightforward, more so than trying to explain it in words. Here are two examples that should make it really clear already:

\noindent\diagram{r1r1k/pp1qn2p/5pp/3p2N/%
6Q/8/PP3PPP/2R1R1K}\hfill{\pieceinitials{PTCADR}\diagram{t4tr/1d2ppap/a2p2p/2pc//1P4P/P3PPAP/1TADTCR}}
\begin{verbatim}
\diagram{r1r1k/pp1qn2p/5pp/3p2N/%           \diagram{r4rk/1q2ppbp/b2p2p%
    6Q/8/PP3PPP/2R1R1K}                        2pn//1P4P/P3PPBP/1RBQRNK}
\end{verbatim}



\DescribeMacro{\diagram}The diagram is typeset from the top board file to the bottom one, and from left to right. Numbers mean consecutive empty squares; lowercase letters mean black pieces; uppercase letters are white pieces. \verb"/" finishes a line. \TeX mate will fill any empty squares at the right of the last piece in the file.

For the pieces you use the letters defined by \verb"\pieceinitials" (default \texttt{PRNBQK}).

\DescribeMacro{\diagramsize}The default size for the diagram (each of its squares) is 18pt. It can be changed modifying the \LaTeX\ length \verb"\diagramsize".

\DescribeMacro{notfilling}The diagrams don't have to be $8\times8$. If you choose the \texttt{notfilling} option to \TeX mate, it will not fill up the remaining squares in incomplete files, so you can have $4\times4$ boards, for example. The \DescribeMacro{\SquareNo} \verb"\SquareNo" variable holds the number of squares per line, and it can be modified.

\section{Samples}

The following are examples from real life. Modifying a few commands, I was able to mimic the formats of two books, and I present a game from each. Looking at the code for these samples must be the best way to learn how to use \TeX mate.

\subsection{A famous study}
But first comes a beautiful position. I used almost the default formatting of \TeX mate, except redefining
\begin{verbatim}
\renewcommand\afterb{ }
\renewcommand\iiclose{\leavevmode\unskip] }
\end{verbatim}
\noindent so that there is no semicolon between black and white moves. I chose this because there are alternatives in the text-scarce commentaries, and they are separated by ;.

\newgame
\bigskip
\centerline{\diagram{8/8/1KP/3r/8/8/8/k}}

\medskip
This position has been associated to the name of a Spanish amateur, Saavedra. Its history is interesting: it seems that a similar endgame was reached in a game toward the end of the 19\textsuperscript{th} century, and called a lot of attention. Zukertort published an analysis of it---almost complete, but not quite. And then it was left to Saavedra to find, while reading Zukertort's article, a move that must be counted among the most amazing chess tricks to be found anywhere.


\renewcommand\afterb{ }
\renewcommand\iiclose{\leavevmode\unskip] }
\makeatletter
\makebarchess
\newgame
|1. c7 Rd6+\onlymove 2. Kb5 [Kc5 Rd1! 3. c8\queen Rc1+=\; 2 Kb7 Rd7 \threat<Rxc7>=] Rd5+ 3. Kb4[Kb6 Rd6+] Rd4+ 4. Kd3 Rd3+ 5. Kc2 Rd4! 6. c8\rook!![|What Zukertort overlooked. He `only' saw |c8\queen Rc4+ Qxc4| stalemate! Promoting a rook, White now threatens \rook a8\mate|] Ra4 7. Kb3\threat<\rook c1\mate,\ \king\takes b4\WBetter>|\hfill\textbf{1--0}
\bigskip

{\small OK}, here is the same game with a different format for resuming moves:

\makebarother
\noindent\verb"\renewcommand\beforeb{}"
\makebarchess

\noindent
makes resuming black moves to be typeset as if they were not resuming ones. So:

\renewcommand\beforeb{}
\newgame
|1. c7 Rd6+\onlymove Kb5 [Kc5 Rd1!  c8\queen Rc1+=\; 2 Kb7 Rd7 \threat<Rxc7>=] Rd5+  Kb4[Kb6 Rd6+] Rd4+  Kd3 Rd3+  Kc2 Rd4!  c8\rook!![|What Zukertort overlooked. He `only' saw |c8\queen Rc4+ Qxc4| stalemate! Promoting a rook, White now threatens \rook a8\mate|] Ra4  Kb3\threat<\rook c1\mate,\ \king\takes b4\WBetter>|\hfill\textbf{1--0}


\newpage
\newgame
\twocolumn
\renewcommand\afterno{~}
\renewcommand\iiopent{\par}
\renewcommand\iicloset{\par}
\renewcommand\takes{x}
\renewcommand\beforeb{\the\move.~\dots\ }
\subsection{Watson's format}
The following game opening is taken from John~Watson's wonderful \emph{Secrets of Modern Chess Strategy} (Gambit, 1998), page~254. I also copy his formatting: in addition to double-column (on which I blame the overfulls), `x' for captures, long commentary in individual paragraphs, no period (but a space) after numbers. These are the appropriate declarations:

\begin{verbatim}
\renewcommand\afterno{~}
\renewcommand\iiopent{\par}
\renewcommand\iicloset{\par}
\renewcommand\takes{x}
\end{verbatim}

\begin{center}
\textsf{Timoshenko -- Itkis}

\textit{Baile Herculane 1996}
\end{center}
\noindent|1. e4 e6 2. d4 d5 3. Nc3 Nf6 4. e5 Nfd7 5 f4 c5 6. Nf3 Nc6 7 Be3 cxd4 8 Nxd4 Qb6 9 Qd2 Qxb2 10 Rb1 Qa3 \[|Znosko-Borovsky's principle is highly relevant here: the queen itself provides some countterplay agains White's c3 point, which give Black a chance against the coming  onslaught. |\]11 Bb5! Nxd4!?\[|%
Risky. Later games saw |Ndb8 12 f5! Bb4!|, aparently leading to a messy equality.|\]12 Bxd4 Bb4 13. 0-0 a6 14. Rb3 Qa5 15 Rfb1 Ba3!?\[|%
Very provocative. |Qxb5 | is unclear after both |16 Nxb5 Bxd2| and |\white 16 Rxb4 Qc6|.|\]16. f5!!~{\normalfont(\emph{D})}\[|%
Timoshenko attributes this move to Krup\-pa.

\begin{center}
\diagram{r1b1k2r/1p1n1ppp/p3p/qB1pPP/3B/bRN/P1PQ2PP/1R4K}
\end{center}

|\]axb5 17 Rxa3! Qxa3 18 Nxb5 Qxa2 19 Nd6+ Kf8 20. Ra1 Qxa1+ 21. Bxa1 Rxa1+ 22 Kf2\[|%
Here the game went |\dummy Ra8? 23 Qg5! f6 24 Qh5 g6 25 Qh6+| with a winning attack. Better seems  |\black 22 Nxe5| (Nunn), leading to |23 Qc3 Ng4+ 24 Ke2|, when |Ra8? 25 Qc7!| is good for White, but |\black 24 Ke7| holds out hope for equality, for example |Nxc8+ [Qb4!?| is another possibility|] Rxc8 26 Qxc8 Ra4! 27. Qxb7+ Kf6|.

\newpage
\onecolumn
\subsection{Schiller's format}
Now I take a game from Eric~Schiller's \emph{Standard Chess Openings} (Cardoza Publishing, 2002), pages~291--2. His formatting includes: `x' for captures, initials (not figurines) for pieces, semicolon after black's moves, period after number (but no space after it),\footnote{And here you can see this book was typeset with Word: putting a space after the period risks an unacceptable line break there. Word doesn't have something like our \textasciitilde.} in-text commentary without punctuation, and a `1\dots Nf6' form for black resuming moves:

\begin{verbatim}
\renewcommand\afterno{.}
\renewcommand\afterb{; }
\renewcommand\beforeb{\the\move\dots}
\renewcommand\rook{R}\renewcommand\knight{N}\renewcommand\bishop{B}
\renewcommand\queen{Q}\renewcommand\king{K}
\renewcommand\iiopen{. }\renewcommand\iiopent{. }
\renewcommand\iiclose{\leavevmode\unskip\ }
\renewcommand\iicloset{\leavevmode\unskip\ }
\end{verbatim}

Note the use of Plain~\TeX's \verb"\unskip" in commentary-closing commands: it avoids double spaces. But it requires a previous \verb"\leavevmode".

\newgame
\renewcommand\afterno{.}
\renewcommand\afterb{; }
\renewcommand\beforeb{\the\move\dots}
\renewcommand\rook{R}\renewcommand\knight{N}\renewcommand\bishop{B}
\renewcommand\queen{Q}\renewcommand\king{K}
\renewcommand\iiopen{. }\renewcommand\iiopent{. }
\renewcommand\iiclose{\leavevmode\unskip\ }\renewcommand\iicloset{\leavevmode\unskip }
\setlength\diagramsize{15pt}
\begin{center}
\bfseries (102) TARRASCH - ECKART [C05]

Nuremberg, 1889

|1. e4 e6; 2.d4 d5 3. Nd2 Nf6 4. e5 Nfd7; 5. Bd3|

\medskip

\diagram{rnbqkb1r/pppn1ppp/4p/3pP/3P/3B/PPPN1PPP/R1BQK1NR}
\end{center}
This is the way that Tarrasch [\dots]. |5 \black c5 6 c3 Nc6 7. Ne2 [Ngf3| is also common. |]Qb6[|Black should exchange in the center instead and only then play \dots Qb6.|]8 Nf3 Be7[cxd4 9. cxd4|

|f6! 10. exf6 Nxf6 11. 0-0 Bd6| gives Black a reasonable game [\dots] Here is just one sample line: |Bf4!?| This sacrifices the b-pawn in return for play on the dark squares. |Bxf4 13 Nxf4 Qxb2 14. Ng5 Ke7| and White has to justify the material investment.

|10. Kf1 Be7|. In this sharp line of the French, opening lines with 10\dots f6 is a wiser move. |11. a3 Nf8 12 b4 Bd7 13. Be3 Nd8|. Black does have a plan: to play \bishop b5 and exchange the light-squared bishops. [\dots] |14 Nc3 a5|. [\dots] Now the scope of the \bishop d7 is severely limited, and Black's plan, beginning with |\black 13 Nd8|, is exposed as faulty.

|] 9. 0-0 0-0[|Black should just play |f6| here. |]10. Nf4 Nd8| [\dots]|11 Qc2! f5 [g6 12 h4 c4 13. Bxg6 hxg6; 14. h5 g5; 15. Ng6! fxg6 16. Qxg6+ Kh8; 17 Bxg5 Bxg5 18. Nxg5 Rf7 19 Nxf7+ Nxf7 20. Qxf7 Qxb2 21. h6| and Black gets mated.|]12. exf6 Nxf6; 13. Ng5[|White's pieces are swarming on the kingside, and Black just can't get enough defensive pieces to rescue the king.

|]g6|.

\begin{center}
\diagram{R1BN1RK/PP2B2P/1Q2PNP/2PP2n/3p1n/2pb/ppq2ppp/r1b2rk}
\end{center}

|14. Bxg6! hxg6 15. Qxg6+ Kh8 16. Qh6+ Kg8; 17. Ng6|\textbf{. White won.}



\section{Chess symbols}
The table on the next page lists \TeX mate's chess symbols and the commands that produce them. The symbols come from the font of \textsf{skak}, but some of them have been adjusted for size and position. These modifications are shown in the third column.

All the signs are \verb"\smash"'ed (the box that contains them is zero in height and depth) so that they don't affect interline spacing.

\makebarother
\centering
\begin{tabular}{|l|c|l|}\hline
\verb"\wbetter" & \wbetter & Shifted\\
\verb"\bbetter" & \bbetter & Shifted\\
\verb"\wBetter" & \wBetter & Shifted\\
\verb"\bBetter" & \bBetter & \\
\verb"\WBetter" & \WBetter & \verb"\large"\\
\verb"\BBetter" & \BBetter & \verb"\large"\\
\verb"\equal" & \equal & \\
\verb"\unclear" & \unclear & \verb"\Large", shifted\\
\verb"\compensation" & \compensation & \verb"\large"\\\hline
\verb"\development" & \development & \verb"\footnotesize"\\
\verb"\spaceadv" & \spaceadv & \verb"\footnotesize"\\
\verb"\attack" & \attack & \verb"\large"\\
\verb"\initiative" & \initiative & \verb"\large"\\
\verb"\counterplay" & \counterplay & \verb"\large"\\\hline
\verb"\zugzwang" & \zugzwang & \verb"\small"\\
\verb"\onlymove" & \onlymove & \verb"\footnotesize"\\
\verb"\withidea" & \withidea & \verb"\footnotesize"\\
\verb"\betteris" & \betteris & \verb"\footnotesize"\\\hline
\verb"\boardfile" & \boardfile & \\
\verb"\boarddiagonal" & \boarddiagonal & \verb"\small"\\
\verb"\boardcenter" & \boardcenter & \verb"\small"\\
\verb"\kingside" & \kingside & \\
\verb"\queenside" & \queenside & \\\hline
\verb"\weak" & \weak & \verb"\small"\\
\verb"\ending" & \ending & \verb"\footnotesize"\\
\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 & \verb"\small"\\\hline
\verb"\timetrouble" & \timetrouble  &\\
\verb"\with" & \with & \verb"\small"\\
\verb"\without" & \without & \verb"\small"\\
\verb"\chessetc" & \chessetc & \\
\verb"\chesssee" & \chesssee & \\\hline
\end{tabular}\qquad\parbox[t]{2in}


\end{document}