summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/texmate/texmate2manual.tex
blob: 92e84bf2a4a6f71a1de77c9b904f860557548f3b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
\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}