Debian Codegraph @

texmf-dist/doc/metapost/mpchess/mpchess-doc-en.tex

raw
1
2 % LTeX: language=en
3
4 % mpchess: draw chess boards and positions with MetaPost
5 %
6 % Originally written by Maxime Chupin <[email protected]>,
7 % 2023.
8 %
9 % Distributed under the terms of the GNU free documentation licence:
10 % http://www.gnu.org/licenses/fdl.html
11 % without any invariant section or cover text.
12
13 \documentclass[english]{ltxdoc}
14
15 \input{mpchess-preamble}
16
17 \usepackage[english]{babel}
18
19 \makeindex[title=Command Index, columns=2]
20
21
22
23 %\lstset{moredelim=*[s][\color{red}\rmfamily\itshape]{<}{>}}
24 %\lstset{moredelim=*[s][\color{blue}\rmfamily\itshape]{<<}{>>}}
25
26 \begin{document}
27
28 \title{{MPchess} : drawing chess boards and positions with \hologo{METAPOST}}
29 \author{Maxime Chupin, \url{[email protected]}}
30 \date{\today}
31
32 %% === Page de garde ===================================================
33 \thispagestyle{empty}
34 \begin{tikzpicture}[remember picture, overlay]
35 \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
36 \includegraphics{fond.pdf}%
37 };
38 \end{tikzpicture}%
39
40 \noindent
41 {\Huge \mpchess}\par\medskip
42 \noindent
43 {\Large drawing chess boards and positions with \hologo{METAPOST}}\\[1cm]
44 \parbox{0.6\textwidth}{
45 \begin{mplibcode}
46 input mpchess
47 string pgnstr;
48 pgnstr:="1. e4 e5 2. Bc4 d6 3. Nf3 Bg4 4. Nc3 g6 5. Nxe5 Bxd1 ";
49 build_chessboards_from_pgn(pgnstr);
50 beginfig(0);
51 set_backboard_width(8cm);
52 init_backboard;
53 draw backboard;
54 show_last_move(10);
55 draw_comment("?","d1");
56 color_square(0.3[green,black])("c4","c3","e5");
57 color_square(0.3[red,black])("e8");
58 draw chessboard_step(10);
59 draw_arrows(0.3[green,black])("e5|-f7","c3-|d5");
60 draw_arrows(0.3[red,black])("c4--f7");
61 endfig;
62 \end{mplibcode}
63 }\hfill
64 \parbox{0.5\textwidth}{\Large\raggedleft
65 \textbf{Contributor}\\
66 Maxime \textsc{Chupin}\\
67 \url{[email protected]}
68 }
69 \vfill
70 \begin{center}
71 Version 0.9, 2024, Decembre, 16th \\
72 \url{https://gitlab.gutenberg-asso.fr/mchupin/mpchess}
73 \end{center}
74 %% == Page de garde ====================================================
75 \newpage
76
77 %\maketitle
78
79 \begin{abstract}
80 The \mpchess package allows you to draw chess boards and positions.
81 The appearance of its drawings is modern and largely inspired by what is offered by
82 the excellent web site \url{Lichess.org}.
83 Relying on \MP{} probably allows more graphic flexibility than the
84 excellent \LaTeX{} chess packages that already exist.
85 \end{abstract}
86
87
88 \begin{center}
89 \url{https://gitlab.gutenberg-asso.fr/mchupin/mpchess}
90 \url{https://github.com/chupinmaxime/mpchess}
91 \end{center}
92
93 \tableofcontents
94
95 \bigskip
96
97 \begin{tcolorbox}[ arc=0pt,outer arc=0pt,
98 colback=darkred!3,
99 colframe=darkred,
100 breakable,
101 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
102 3pt, toptitle=3pt,
103 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
104 0pt, bottomrule at break = 0pt,]
105 \itshape
106 This package is in beta version---do not hesitate to report bugs, as well as requests for improvement.
107 \end{tcolorbox}
108
109 \section{Installation}
110
111 \mpchess is on \ctan{} and can also be installed via the package manager of your
112 distribution.
113
114 \begin{center}
115 \url{https://www.ctan.org/pkg/mpchess}
116 \end{center}
117
118
119 \subsection{With \TeX live under Linux or macOS}
120
121 To install \mpchess with \TeX Live, you will have to create the directory
122 \lstinline+texmf+ directory in your \lstinline+home+.
123
124 \begin{commandshell}
125 mkdir ~/texmf
126 \end{commandshell}
127
128 Then, you will have to place the \lstinline+.mp+ files in the
129 \begin{center}
130 \lstinline+~/texmf/metapost/mpchess/+
131 \end{center}
132
133 \mpchess consists of 7 files \hologo{METAPOST} :
134 \begin{itemize}
135 \item \verb+mpchess.mp+;
136 \item \verb+mpchess-chessboard.mp+;
137 \item \verb+mpchess-pgn.mp+;
138 \item \verb+mpchess-fen.mp+;
139 \item \verb+mpchess-cburnett.mp+;
140 \item \verb+mpchess-pieces.mp+;
141 \item \verb+mpchess-skak.mp+.
142 \end{itemize}
143
144 Once this is done, \mpchess will be loaded with the classic \MP
145 input code
146 \begin{mpcode}
147 input mpchess
148 \end{mpcode}
149
150 \subsection{With Mik\TeX{} and Windows}
151
152 These two systems are unknown to the author of \mpchess, so we
153 refer you to the Mik\TeX documentation concerning the addition of local packages:
154 \begin{center}
155 \url{http://docs.miktex.org/manual/localadditions.html}
156 \end{center}
157
158
159
160 \subsection{Dependencies}
161
162
163 \mpchess depends, of course on \MP, as well as the packages \package{hatching}
164 and---if \mpchess is not used with \hologo{LuaLaTeX} and the \package{luamplib}
165 package---the \package{latexmp} package.
166
167
168 \section{Package Rationale and General Philosophy}
169
170 There are already \LaTeX{} packages for drawing chess boards and positions,
171 including the very good package \package{xskak}~\cite{ctan-xskak}coupled with
172 the package \package{chessboard}~\cite{ctan-chessboard}.
173 There, Ulrike Fisher ade improvements, undertaken maintenance work, and provided us with excellent tools to make chess diagrams and to handle the different
174 formats of
175 game descriptions\footnote{She even developed the
176 package to handle various chess fonts.}. The
177 documentation of each of these packages is very good.
178
179 Several things motivated the creation of \mpchess. First of all, with
180 \package{chessboard} the addition of a set of pieces is not very easy, because
181 it relies on fonts. Moreover, the author finds that drawing chess game diagrams is by its nature a very graphical task, and that using a dedicated drawing
182 language offers increased flexibility. In that case, what better than \MP~\cite{ctan-metapost}?
183
184 With \mpchess, the final image of the chess board is built with the pieces
185 by successive layers. Thus, we begin by producing and drawing the board
186 (\lstinline+backboard+), which we can modify---for example, by
187 coloring some squares. We then can add the pieces of the position (\lstinline+chessboard+),
188 and finally, we can annotate the whole thing with marks, colors,
189 arrows, and so forth.
190
191
192 Moreover, \mpchess produces images that are graphically close to what is
193 provided by excellent \emph{open source} website \url{https://lichess.org}. The colors, the pieces and the general aspect of
194 \mpchess are largely inspired
195 by what this website offers.
196
197 \section{Board}
198
199 The board is called with \mpchess{} \lstinline+backboard+.
200 You have to initialize the board before drawing it. This is done with the
201 following command:\par
202
203 \commande|init_backboard|\smallskip\index{init_backboard@\lstinline+init_backboard+}
204
205 This command constructs a \MP{} \lstinline+picture+ named
206 \mbox{\lstinline+backboard+.} It should then be drawn as shown in the following example.
207 \begin{ExempleMP}
208 input mpchess
209
210 beginfig(0);
211 init_backboard;
212 draw backboard;
213 endfig;
214 \end{ExempleMP}
215
216 This initialization will make it possible to use the
217 various options and features that are described in the
218 following sections.
219
220 \subsection{Size of the Board}
221
222 When creating the \lstinline+backboard+, you can further specify its width. This is done with the following command:\par\bigskip
223
224 \commande|set_backboard_width(«dim»)|\smallskip\index{set_backboard_width@\lstinline+set_backboard_width+}
225
226 \begin{description}
227 \item[\meta{dim}:] is the width of the board (with units). By default, this dimension is \SI{5}{cm}.
228 \end{description}
229
230 The use of this command is illustrated in the example~\ref{ex:widthcase}. This
231 command should be used before \lstinline+init_backboard+ so that it is taken
232 into account when creating the \lstinline+picture+.
233 \bigskip
234
235 The size of the board can be retrieved with the following command:
236
237 \commande|get_backboard_width|\smallskip\index{get_backboard_width@\lstinline+get_backboard_width+}
238
239 This command returns a \lstinline+numeric+.
240
241 \subsection{Number of Squares}
242
243 By default, the game board contains 64 squares ($8\times 8$). You can change
244 this with the following command:
245 \commande|set_backboard_size(«nbr»)|
246 \smallskip\index{set_backboard_size@\lstinline+set_backboard_size+}
247
248 \begin{description}
249 \item[\meta{nbr}:] is the desired number of squares. The board will then be
250 square of size \meta{nbr}$\times$\meta{nbr}. By default this number is 8.
251 \end{description}
252
253 Again, this command must be used before \lstinline+init_backboard+ for it to be
254 taken into account, as shown in the following example.
255
256 \begin{ExempleMP}[label=ex:widthcase]
257 input mpchess
258
259 beginfig(0);
260 set_backboard_width(3cm);
261 set_backboard_size(6);
262 init_backboard;
263 draw backboard;
264 endfig;
265 \end{ExempleMP}
266
267 To specify size of the game board, you can use the following command:
268
269
270 \commande|get_backboard_size|\smallskip\index{get_backboard_size@\lstinline+get_backboard_size+}
271
272 This command returns a \lstinline+numeric+.
273
274 \subsection{Dimension of a Square}
275
276 Depending on the number of squares on the board and the prescribed width of the board, \mpchess calculates the dimension (width or height) of a square. This
277 serves as a general unit. To obtain it, use the following command.
278
279 \commande|get_square_dim|\smallskip\index{get_square_dim@\lstinline+get_square_dim+}
280
281 This command returns a \lstinline+numeric+.
282
283 \subsection{Setting the Color Theme}
284
285 \subsubsection{Predefined Color Themes}
286
287 Several color themes are available. To choose a color theme, use the following
288 command:
289
290 \commande|set_color_theme(«string»)|\smallskip\index{set_color_theme@\lstinline+set_color_theme+}
291
292 \begin{description}
293 \item[\meta{string}] can be:
294 \begin{itemize}
295 \item \lstinline+"BlueLichess"+ (default);
296 \item \lstinline+"BrownLichess"+;
297 \item \lstinline+"GreenLichess"+;
298 \item \lstinline+"PinkPyramidalLichess"+;
299 \item \lstinline+"Wood"+;
300 \item \lstinline+"Classical"+;
301 \item \lstinline+"Dotted"+;
302 \item or \lstinline+"User"+;
303 \end{itemize}
304 \end{description}
305
306 The following example shows the results obtained from \lstinline+"BrownLichess"+:
307 \begin{ExempleMP}
308 input mpchess
309 beginfig(0);
310 set_color_theme("BrownLichess");
311 init_backboard;
312 draw backboard;
313 endfig;
314 \end{ExempleMP}
315
316 The table~\ref{tab:color} shows the different results of the different themes.
317
318 \begin{table}
319 \centering
320 \begin{tabular}{cc}
321
322 \lstinline+"GreenLichess"+ theme&\lstinline+"Classical"+ theme\\
323 \begin{mplibcode}
324 input mpchess
325 beginfig(0);
326 init_chessboard;
327 set_backboard_width(4cm);
328 set_color_theme("GreenLichess");
329 init_backboard;
330 draw backboard;
331 endfig;
332 \end{mplibcode}
333 &\begin{mplibcode}
334 input mpchess
335 beginfig(0);
336 init_chessboard;
337 set_backboard_width(4cm);
338 set_color_theme("Classical");
339 init_backboard;
340 draw backboard;
341 endfig;
342 \end{mplibcode}\\
343 \lstinline+"PinkPyramidalLichess"+ theme& \lstinline+"Wood"+ theme\\
344 \begin{mplibcode}
345 input mpchess
346 beginfig(0);
347 init_chessboard;
348 set_backboard_width(4cm);
349 set_color_theme("PinkPyramidalLichess");
350 init_backboard;
351 draw backboard;
352 endfig;
353 \end{mplibcode}&
354 \begin{mplibcode}
355 input mpchess
356 beginfig(0);
357 init_chessboard;
358 set_backboard_width(4cm);
359 set_color_theme("Wood");
360 init_backboard;
361 draw backboard;
362 endfig;
363 \end{mplibcode}\\
364 \lstinline+"Dotted"+ theme& \\
365 \begin{mplibcode}
366 input mpchess
367 beginfig(0);
368 init_chessboard;
369 set_backboard_width(4cm);
370 set_color_theme("Dotted");
371 init_backboard;
372 draw backboard;
373 endfig;
374 \end{mplibcode}&\\
375 \end{tabular}
376 \caption{The different color themes provided by \mpchess.}\label{tab:color}
377 \end{table}
378
379 The use of \lstinline+"User"+ is a special case, as it allows you to
380 define black and white squares. For this to work
381 a another macro
382 \lstinline+buildUserSquare+\index{buildUserSquare@\lstinline+buildUserSquare+}
383 should be difined. It must build the
384 images (\lstinline+picture+) \lstinline+_blackSquarePic+\index{_blackSquarePic@\lstinline+_blackSquarePic+} and
385 \lstinline+_whiteSquarePic+\index{_whiteSquarePic@\lstinline+_whiteSquarePic+}.
386 Here is a prototype of such a command.
387 \begin{mpcode}
388 def buildUserSquare(expr _SquareUnit)=
389 _blackSquarePic:=image(
390 fill (unitsquare scaled _SquareUnit) withcolor red;
391 );
392 _whiteSquarePic:=image(
393 fill unitsquare scaled _SquareUnit withcolor green;
394 );
395 enddef;
396 \end{mpcode}
397 The macro takes a unit as argument, and must construct two squares with length
398 equal to this unit.
399
400 \subsubsection{Configuring a Personal Color Theme}
401
402 \paragraph{Colors.}
403 A color theme is the definition of two colors.
404 These can be defined with the following commands\footnote{Attention,
405 in version 0.6, \lstinline+set_white_color+ became
406 \lstinline+set_white_squares_color+ and \lstinline+set_black_color+ became
407 \lstinline+set_black_squares_color+.}:
408
409 \commande|set_white_squares_color(«color»)|\index{set_white_squares_color@\lstinline+set_white_squares_color+}\par
410 \commande|set_black_squares_color(«color»)|\index{set_black_squares_color@\lstinline+set_black_squares_color+}\smallskip
411
412 \meta{color} is a \MP{} \lstinline+color+.
413
414 \begin{ExempleMP}
415 input mpchess
416 beginfig(0);
417 set_white_squares_color((0.9,0.8,0.8));
418 set_black_squares_color((0.7,0.6,0.6));
419 init_backboard;
420 draw backboard;
421 endfig;
422 \end{ExempleMP}
423
424 \paragraph{Color Types.}
425
426 To choose a type, you can use the following command:
427
428 \commande|set_board_type(«string»)|\index{set_board_type@\lstinline+set_board_type+}\smallskip
429
430
431 Three types of coloring are available:
432
433 \begin{description}
434 \item[\meta{string}] can be:
435 \begin{itemize}
436 \item \lstinline+"flat"+, simple flat coloring (default);
437 \item \lstinline+"pyramidal"+, Lichess \emph{pyramidal} coloring;
438 \item \lstinline+"wood"+, wood imitation.
439 \end{itemize}
440 \end{description}
441
442 Here is an example coupling color and type definitions.
443
444 \begin{ExempleMP}
445 input mpchess
446 beginfig(0);
447 set_white_squares_color((0.9,0.8,0.8));
448 set_black_squares_color((0.7,0.6,0.6));
449 set_board_type("wood");
450 init_backboard;
451 draw backboard;
452 endfig;
453 \end{ExempleMP}
454
455
456
457 \subsection{Display Coordinates}
458
459 You may have noticed in the various examples that by default, the coordinates are, as on the Lichess site, written in small letters inside the boxes.
460
461 \mpchess allows you to choose the coordinates position inside or outside the board with the
462 following command\footnote{Attention,
463 in version 0.6, \lstinline+set_coords_inside+ and \lstinline+set_coords_outside+ became
464 \lstinline+set_coordinates_position+.}:
465
466 \commande|set_coordinates_position(«string»)|\index{set_coordinates_position@\lstinline+set_coordinates_position+}\smallskip
467
468
469 \begin{description}
470 \item[\meta{string}] can be:
471 \begin{itemize}
472 \item \lstinline+"inside"+ (default);
473 \item \lstinline+"outside"+.
474 \end{itemize}
475 \end{description}
476
477 The result is as follows.
478
479
480
481 \begin{ExempleMP}
482 input mpchess
483 beginfig(0);
484 set_coordinates_position("outside");
485 init_backboard;
486 draw backboard;
487 endfig;
488 \end{ExempleMP}
489
490
491 You can see in the previous examples that with \package{luamplib} and
492 \LaTeX, the font used for the coordinates is the font of the current document. To draw these letters and
493 these numbers, \mpchess uses the \MP{} operator \lstinline+infont+ and the font
494 is set to \lstinline+defaultfont+ by default\footnote{With \package{luamplib}
495 the \lstinline+infont+ operator is redefined and its argument is simply
496 ignored}, so it is not possible to modify the composition font of the
497 coordinates. This font can be changed with the following command\footnote{Attention,
498 in version 0.6, \lstinline+set_coords_font+ became
499 \lstinline+set_coordinates_font+.}.
500
501 \commande|set_coordinates_font(«font»)|\index{set_coordinates_font@\lstinline+set_coordinates_font+}\smallskip
502
503 It will then be necessary to use the naming conventions specific to the \MP{}
504 operator
505 \lstinline+infont+, and we refer to the
506 \MP documentation~\cite{ctan-metapost} for more details.
507
508 You can also delete the coordinates with the following command\footnote{Attention,
509 in version 0.6, \lstinline+set_no_coords+ became
510 \lstinline+hide_coordinates+ and \lstinline+set_coords+ became
511 \lstinline+show_coordinates+.}:
512
513 \commande|hide_coordinates|\index{hide_coordinates@\lstinline+hide_coordinates+}\smallskip
514
515 And the reverse command also exists:
516
517 \commande|show_coordinates|\index{show_coordinates@\lstinline+show_coordinates+}\smallskip
518
519
520 \subsection{White or Black Side}
521
522 To choose if you want to see the tray on the white or black side, \mpchess
523 provides two commands:
524
525 \commande|set_white_view|\index{set_white_view@\lstinline+set_white_view+}\smallskip
526
527 \commande|set_black_view|\index{set_black_view@\lstinline+set_black_view+}\smallskip
528
529 (By default, we see the board on the white side.)
530
531 \subsection{Players' Names}
532
533 You can fill in the names of the players so that they are noted around the
534 chessboard. This is done with the following commands:
535
536 \commande|set_white_player(«string»)|\index{set_white_player@\lstinline+set_white_player+}\smallskip
537
538 \commande|set_black_player(«string»)|\index{set_black_player@\lstinline+set_black_player+}\smallskip
539
540 \begin{description}
541 \item[\meta{string} :] is the string interpreted by \LaTeX{} to display.
542 \end{description}
543
544 \begin{ExempleMP}
545 input mpchess
546 beginfig(0);
547 set_white_player("\textbf{GM} Kasparov");
548 set_black_player("\textbf{GM} Kramnik");
549
550 init_backboard;
551 draw backboard;
552 endfig;
553 \end{ExempleMP}
554
555 It is possible to place the names on the right side of the board without the
556 black bands present by default.
557 This happens either if the coordinates are printed outside the tray, or if the
558 following command is used:
559
560 \commande|set_players_side|\index{set_players_side@\lstinline+set_players_side+}\smallskip
561
562 \begin{ExempleMP}[righthand width=0.6\linewidth]
563 input mpchess
564 beginfig(0);
565 set_white_player("\textbf{GM} Kasparov");
566 set_black_player("\textbf{GM} Kramnik");
567 set_players_side;
568 init_backboard;
569 draw backboard;
570 endfig;
571 \end{ExempleMP}
572
573
574
575 \section{Pieces and Positions}
576
577 \mpchess, as described above, builds the picture of a chess position
578 layer by layer. This section describes the configuration of pieces and
579 positions.
580
581 Internally, \mpchess builds a table on the board grid. Then, some
582 macros allow to generate a \lstinline+picture+ to be drawn \emph{over} the board (\lstinline+backboard+).
583
584 \subsection{Setting the Theme of the Pieces}
585
586 \mpchess provides for the moment three themes of pieces. The default theme is
587 called \lstinline+mpchess+. It has been designed for this package \hologo{METAPOST}.
588 It has been proposed to the Lichess project, and has been accepted. Thus, you
589 will also have access to the \lstinline+mpchess+ piece set with
590 Lichess\footnote{The open-source projects feed each other! Even if obviously,
591 this package has borrowed much more from Lichess than the other way around.}
592
593 Another theme is borrowed from
594 Lichess (\lstinline+cburnett+) and the last one is borrowed from the
595 package~\package{skak}~cite{ctan-skak}\footnote{Which provides the \MF{} code
596 for a chess font, which has been easily adapted to \MP{} for \mpchess.}.
597
598 To choose the theme, use the following command:
599
600 \commande|set_pieces_theme(«string»)|\index{set_pieces_theme@\lstinline+set_pieces_theme+}\smallskip
601
602 \begin{description}
603 \item[\meta{string}:] can be:
604 \begin{itemize}
605 \item \lstinline+"mpchess"+ (default), to use the set specially designed for this
606 package;
607 \item \lstinline+"cburnett"+, to use the Lichess \emph{cburnett}
608 pieces set;
609 \item \lstinline+"skak"+, to use the \package{skak}
610 pieces set.
611 \end{itemize}
612 \end{description}
613
614
615 The table~\ref{tab:pieces} shows the result of the three sets of pieces.
616 \begin{table}
617 \centering
618 \begin{tabular}{cc}
619
620 \lstinline+cburnett+ theme&\lstinline+mpchess+ theme\\
621 \begin{mplibcode}
622 input mpchess
623 beginfig(0);
624 init_chessboard;
625 set_backboard_width(4cm);
626 set_pieces_theme("cburnett");
627 hide_whos_to_move;
628 init_backboard;
629 draw backboard;
630 draw chessboard_step(0);
631 endfig;
632 \end{mplibcode}
633 &\begin{mplibcode}
634 input mpchess
635 beginfig(0);
636 init_chessboard;
637 set_backboard_width(4cm);
638 set_pieces_theme("mpchess");
639 hide_whos_to_move;
640 init_backboard;
641 draw backboard;
642 draw chessboard_step(0);
643 endfig;
644 \end{mplibcode}\\
645 \lstinline+skak+ theme&\\
646 \begin{mplibcode}
647 input mpchess
648 beginfig(0);
649 init_chessboard;
650 set_backboard_width(4cm);
651 set_pieces_theme("skak");
652 hide_whos_to_move;
653 init_backboard;
654 draw backboard;
655 draw chessboard_step(0);
656 endfig;
657 \end{mplibcode}&\\
658 \end{tabular}
659 \caption{The different themes of pieces provided by \mpchess.}\label{tab:pieces}
660 \end{table}
661
662
663 \subsection{Specifying to Move}
664
665 \mpchess indicates which player has the current move. This is done by
666 a small colored triangle (white or black) at the end of the board (which
667 you can see in the following examples).
668
669 To specify which side is to move, use the following commands:
670
671 \commande|set_white_to_move|\index{set_white_to_move@\lstinline+set_white_to_move+}\smallskip
672
673
674 \commande|set_black_to_move|\index{set_black_to_move@\lstinline+set_black_to_move+}\smallskip
675
676 By default, white is to move, and this information is displayed.
677
678 To activate or deactivate this display, use one of the following two
679 commands\footnote{Attention,
680 in version 0.6, \lstinline+set_whos_to_move+ and
681 \lstinline+unset_whos_to_move+ became \lstinline+show_whos_to_move+ and
682 \lstinline+hide_whos_to_move+.}:
683
684 \commande|show_whos_to_move|\index{show_whos_to_move@\lstinline+show_whos_to_move+}\smallskip
685
686
687 \commande|hide_whos_to_move|\index{hide_whos_to_move@\lstinline+hide_whos_to_move+}\smallskip
688
689 It is now possible to change the appearance of the marker (since
690 version 0.9\footnote{Thanks to Udi Fogiel for fixing a placement bug and
691 for suggesting improvements.}. For this purpose, \mpchess provides three styles:
692 \lstinline+"triangle"+ (default), \lstinline+"square"+ and \lstinline+"disk"+.
693 To select the marker type, use the following command:
694
695 \commande|set_marker_type(«string»)|\index{set_marker_type@\lstinline+set_marker_type+}\smallskip
696
697 \begin{description}
698 \item[\meta{string}] may be
699 \begin{itemize}
700 \item \lstinline+"triangle"+ (default value);
701 \item \lstinline+"square"+;
702 \item \lstinline+"disk"+;
703 \item \lstinline+"custom"+.
704 \end{itemize}
705 \end{description}
706
707 You can adjust the size (by a factor of the unit dimension) with the following
708 command:
709
710 \commande|set_marker_scale(«numeric»)|\index{set_marker_scale@\lstinline+set_marker_scale+}\smallskip
711
712 \begin{description}
713 \item[\meta{numeric}:] is a unit dimension factor for enlarging or
714 shrink the mark (default value is \num{0.35}).
715 \end{description}
716
717 The \lstinline+"custom"+ marker type value lets you define the marker's
718 appearance. When this option is called, a
719 macro \MP{} \lstinline+custom_maker(expr s,r)+ must be defined. The
720 \lstinline+s+ parameter is the scale factor setting: the markers supplied by
721 \mpchess are drawings contained in a square of side 1 (\MP{} unit) and scaled
722 by \lstinline+s*_chessSquareU+. The \lstinline+r+ parameter is a boolean that
723 handles the case where the marker is rotated 180 degrees
724 when placed at the top of the chessboard.
725
726 For example, a \lstinline+custom_marker+ macro reproducing the triangle symbol might be as follows:
727 \begin{mpcode}
728 def custom_marker(expr s, r)=
729 ((0,0)--(1,0)--(0.5,0.5)--cycle) if r: rotatedaround((0.5, 0.5/3), 180) fi scaled (s*_chessSquareU)
730 enddef;
731 \end{mpcode}
732
733 Only the outline is defined, which will be filled by either white or black.
734
735
736 \begin{ExempleMP}
737 input mpchess
738 beginfig(0);
739 set_marker_type("disk");
740 set_marker_scale(0.5);
741 init_backboard;
742 draw backboard;
743 init_chessboard;
744 draw chessboard;
745 endfig;
746 \end{ExempleMP}
747 \subsection{Draw a Position}
748
749 The commands described below allow you to build a position in several ways
750 (adding pieces one by one, reading a \textsc{fen} file, etc.). Once a position
751 has been constructed, it can be plotted
752 using the following command, which generates a \MP{} \lstinline+picture+.
753
754
755 \commande|chessboard|\index{chessboard@\lstinline+chessboard+}\smallskip \label{com:chessboard}
756
757 (The use of this command will be widely illustrated in the following examples.)
758
759 \subsection{Build a position}
760
761 \subsubsection{Initialization}
762
763 To obtain the initial position of a game, simply use the following command:
764
765 \commande|init_chessboard|\index{init_chessboard@\lstinline+init_chessboard+}\smallskip
766
767 \begin{ExempleMP}
768 input mpchess
769 beginfig(0);
770 init_backboard;
771 draw backboard;
772 init_chessboard;
773 draw chessboard;
774 endfig;
775 \end{ExempleMP}
776
777 You can also initialize an empty \lstinline+chessboard+ with the following command:
778
779 \commande|set_empty_chessboard|\index{set_empty_chessboard@\lstinline+set_empty_chessboard+}\smallskip
780
781 \subsubsection{Adding Pieces}
782
783 You can add pieces to build a position with the following two commands:
784
785 \commande|add_white_pieces(«piece1»,«piece2»,etc.)|\index{add_white_pieces@\lstinline+add_white_pieces+}\smallskip
786
787
788 \commande|add_black_pieces(«piece1»,«piece2»,etc.)|\index{add_black_pieces@\lstinline+add_black_pieces+}\smallskip
789
790 These commands take lists of \textbf{\meta{piece}}, which are strings
791 that describe the piece and the position using
792 algebraic notation. There is no limitation on the number of pieces in the list.
793
794 The following example illustrates the use of these commands:
795
796 \begin{ExempleMP}
797 input mpchess
798 beginfig(0);
799 init_backboard;
800 draw backboard;
801 set_empty_chessboard;
802 add_white_pieces("e1","Kd2");
803 add_black_pieces("e7","f6","Kb8");
804 draw chessboard;
805 endfig;
806 \end{ExempleMP}
807
808
809 \subsubsection{Deleting Pieces}
810
811 \mpchess provides several commands to remove items from a position.
812
813 The first command allows you to delete an item from a square. This command takes
814 a list of squares, using algebraic notation:
815
816 \commande|clear_squares(«square1»,«square2»,etc.)|\index{clear_squares@\lstinline+clear_squares+}\smallskip
817
818 The variables \textbf{\meta{square1}}, \textbf{\meta{square2}},
819 and so forth are strings; for example, \lstinline+"a3"+.
820 \medskip
821
822 The following command deletes a set of squares in a region
823 determined by two coordinates on the board. This command may take
824 a list of regions:
825
826 \commande|clear_areas(«area1»,«area2»,etc.)|\index{clear_areas@\lstinline+clear_areas+}\smallskip
827
828 The variables \textbf{\meta{area1}}, \textbf{\meta{area2}}, and so
829 forth are strings consisting of two coordinates separated by a hyphen; for example, \lstinline+"a3-g7"+.
830 \medskip
831
832 The following command deletes all the cells in a file (column) determined by a
833 letter on the board. This command may take a list of files:
834
835
836 \commande|clear_files(«file1»,«file2»,etc.)|\index{clear_files@\lstinline+clear_files+}\smallskip
837
838 The variables \textbf{\meta{file1}}, \textbf{\meta{file2}}, and so
839 forth are strings of characters consisting of a letter; for example, \lstinline+"a"+.
840 \medskip
841
842 The following command deletes all the cells in a rank (line) determined by a
843 number on the board. This command may take a list of ranks.
844
845 \commande|clear_ranks(«rank1»,«rank2»,etc.)|\index{clear_ranks@\lstinline+clear_ranks+}\smallskip
846
847 The variables \textbf{\meta{rank1}}, \textbf{\meta{rank2}}, and so
848 forth are strings made up of a number; for example, \lstinline+"4"+.
849
850 The use of all these commands is illustrated in the following example:
851
852 \begin{ExempleMP}
853 input mpchess
854 beginfig(0);
855 init_backboard;
856 draw backboard;
857 init_chessboard;
858 clear_squares("a1","b2");
859 clear_areas("c2-d7");
860 clear_files("f","h");
861 clear_ranks("8");
862 draw chessboard;
863 endfig;
864 \end{ExempleMP}
865
866
867
868 \subsection{Reading Data in \textsc{fen} Format}
869
870 \mpchess allows you to read a position in the \textsc{fen} format thanks to the following command:
871
872 \commande|build_chessboard_from_fen(«string»)|\index{build_chessboard_from_fen@\lstinline+build_chessboard_from_fen+}\smallskip
873
874 \begin{description}
875 \item[\meta{string}:] is a string describing a position in
876 \textsc{fen} format. Note that all information after the
877 \texttt{w} or \texttt{b} character is ignored.
878 \end{description}
879
880 \begin{ExempleMP}
881 input mpchess;
882 beginfig(0);
883 init_backboard;
884 draw backboard;
885 string fenstr;
886 fenstr := "7r/2p1kp1p/p1B2p2/1pb5/8/2PP4/PP1N1PPP/R5K1 b - - 2 19";
887 build_chessboard_from_fen(fenstr);
888 draw chessboard;
889 endfig;
890 \end{ExempleMP}
891
892
893 It is also possible to read an external file containing on its first line a
894 string in \textsc{fen} format with the following command:
895
896 \commande|build_chessboard_from_fen_file(«string»)|\index{build_chessboard_from_fen_file@\lstinline+build_chessboard_from_fen_file+}\smallskip
897
898 \begin{description}
899 \item[\meta{string}:] is a string of characters (between double quotes)
900 indicating the name of the file to be read.
901 \end{description}
902
903
904 \begin{ExempleMP}
905 input mpchess;
906 beginfig(0);
907 init_backboard;
908 draw backboard;
909 build_chessboard_from_fen_file("test.fen");
910 draw chessboard;
911 endfig;
912 \end{ExempleMP}
913
914 \subsection{Reading Data in \textsc{pgn} Format}
915
916 \mpchess also reads strings in the \textsc{pgn} format.
917 Please note, this is a partial implementation of the format----in particular, \mpchess
918 does not manage the \emph{tags} of the \textsc{pgn} format. Rather, \mpchess handles only
919 the string describing the moves played. In the same way, the accepted format
920 by \mpchess does not allow variants or comments.
921
922 When such a functionality is used, \mpchess stores all the
923 intermediate positions and thus represents them.
924
925 To construct the positions, use the following command:
926
927 \commande|build_chessboards_from_pgn(«string»)|\index{build_chessboards_from_pgn@\lstinline+build_chessboards_from_pgn+}\smallskip
928
929
930 Once the positions are built, they can be represented with the following command:
931
932 \commande|chessboard_step(«int»)|\index{chessboard_step@\lstinline+chessboard_step+}\smallskip
933 \begin{description}
934 \item[\meta{int}:] is the number of the step. The initial configuration is numbered 0, and then each move, white or black, is numbered.
935 \end{description}
936
937 This command, like \lstinline+chessboard+ (see page~\pageref{com:chessboard}),
938 returns a \lstinline+picture+.
939
940 The following example illustrates the use of these commands:
941
942 \begin{ExempleMP}
943 input mpchess;
944 string pgnstr;
945 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
946 build_chessboards_from_pgn(pgnstr);
947 beginfig(0);
948 init_backboard;
949 draw backboard;
950 draw chessboard_step(3); % Nf3
951 endfig;
952 \end{ExempleMP}
953
954
955 It is also possible to read an external file containing on its first line a
956 string in \textsc{pgn} format with the following command:
957
958 \commande|build_chessboard_from_pgn_file(«string»)|\index{build_chessboard_from_pgn_file@\lstinline+build_chessboard_from_pgn_file+}\smallskip
959
960 \begin{description}
961 \item[\meta{string}:] is a string of characters (between double quotes),
962 indicating the name of the file to read.
963 \end{description}
964
965 \begin{ExempleMP}
966 input mpchess;
967 build_chessboards_from_pgn_file("test.pgn");
968 beginfig(0);
969 init_backboard;
970 draw backboard;
971 draw chessboard_step(4); % Nc6
972 endfig;
973 \end{ExempleMP}
974
975 \subsubsection{Showing the Last Move}
976
977 The last move can be displayed automatically with the following command:
978
979 \commande|show_last_move(«int»)|\index{show_last_move@\lstinline+show_last_move+}\smallskip
980
981 \begin{description}
982 \item[\meta{int}:] is the number of the step. The initial setup is numbered 0, and then each move, white or black, is numbered.
983 \end{description}
984
985 This command uses transparent colors to show the two squares where the last move
986 started and ended. Thus, it must be used between the drawing of the board
987 (\lstinline+draw backboard+) and the drawing of the pieces
988 (\lstinline+draw chessboard_step(i)+).
989
990 \begin{ExempleMP}
991 input mpchess;
992 string pgnstr;
993 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
994 build_chessboards_from_pgn(pgnstr);
995 beginfig(0);
996 init_backboard;
997 draw backboard;
998 show_last_move(3);
999 draw chessboard_step(3); % Nf3
1000 endfig;
1001 \end{ExempleMP}
1002
1003 You can configure the color used to color the squares of the last
1004 move with the following command:
1005
1006 \commande|set_last_move_color(«color»)|\index{set_last_move_color@\lstinline+set_last_move_color+}\smallskip
1007 \begin{description}
1008 \item[\meta{color}:] is a \MP{} \lstinline+color+.
1009 \end{description}
1010
1011
1012
1013 \subsubsection{Getting the Number of Moves}
1014
1015 You can get the number of half moves with the following command:
1016
1017 \commande|get_halfmove_number|\index{get_halfmove_number@\lstinline+get_halfmove_number+}\smallskip
1018
1019 This command returns a \lstinline+numeric+.
1020
1021 You can also get the total number of moves---in the sense that they are numbered
1022 in the \textsc{pgn} format---with the following command:
1023
1024 \commande|get_totalmove_number|\index{get_totalmove_number@\lstinline+get_totalmove_number+}\smallskip
1025
1026 This command returns a \lstinline+numeric+.
1027
1028 \section{Annotation}
1029
1030 Numerous commands allow you to annotate the chessboard (arrow, color, circle, cross,
1031 etc.).
1032
1033 \subsection{Arrows}
1034
1035 The command for drawing arrows on the chessboard is the following:
1036
1037 \commande|draw_arrows(«color»)(«string1»,«string2», etc.)|\index{draw_arrows@\lstinline+draw_arrows+}\smallskip
1038 \begin{description}
1039 \item[\meta{color}:] is a \MP{} \lstinline+color+.
1040 \item[\meta{string1}:] is a string (between double-quotes) consisting of two
1041 coordinates (letter and number) separated by two characters that can be
1042 \begin{description}
1043 \vitem+--+ to connect the two squares in a straight line;
1044 \vitem+-|+ to connect the two squares in a broken line, first horizontally then
1045 vertically;
1046 \vitem+|-+ to connect the two squares in a broken line, first vertically then
1047 horizontally.
1048 \end{description}
1049 \end{description}
1050
1051 The following example illustrates the use of this command:
1052
1053 \begin{ExempleMP}
1054 input mpchess;
1055 string pgnstr;
1056 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1057 build_chessboards_from_pgn(pgnstr);
1058 beginfig(0);
1059 init_backboard;
1060 draw backboard;
1061 show_last_move(3);
1062 draw chessboard_step(3); % Nf3
1063 draw_arrows(red)("f8--b4","g1|-f3");
1064 endfig;
1065 \end{ExempleMP}
1066
1067 The thickness of the arrows can be changed with the following command:
1068 \commande|set_arrow_width(«coeff»)|\index{set_arrow_width@\lstinline+set_arrow_width+}\smallskip
1069
1070 \begin{description}
1071 \item[\meta{coeff}:] is a coefficient (\lstinline+numeric+) which allows you
1072 to adjust the width of the arrows in proportion to the width of a square on the chessboard. By default, this coefficient is \lstinline+0.08+.
1073 \end{description}
1074
1075 The following example illustrates the use of this command:
1076
1077 \begin{ExempleMP}
1078 input mpchess;
1079 string pgnstr;
1080 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1081 build_chessboards_from_pgn(pgnstr);
1082 beginfig(0);
1083 set_black_view;
1084 init_backboard;
1085 draw backboard;
1086 show_last_move(3);
1087 draw chessboard_step(3); % Nf3
1088 set_arrow_width(0.12);
1089 draw_arrows(red)("f8--b4","g1|-f3");
1090 endfig;
1091 \end{ExempleMP}
1092
1093 \subsection{Coloring Squares}
1094
1095 \mpchess also allows you to color squares with the following command:
1096
1097 \commande|color_square(«color»)(«coord1»,«coord2», etc.)|\index{color_square@\lstinline+color_square+}\smallskip
1098
1099 \begin{description}
1100 \item[\meta{color}:] is a \MP{} \lstinline+color+.
1101 \item[\meta{coord1}:] is a string (between double quotes) consisting of two
1102 coordinates (a letter and a number).
1103 \end{description}
1104
1105 The following example illustrates the use of this command:
1106
1107 \begin{ExempleMP}
1108 input mpchess
1109 beginfig(0);
1110 init_backboard;
1111 draw backboard;
1112 color_square(red)("e2","e7","c5");
1113 init_chessboard;
1114 draw chessboard;
1115 endfig;
1116 \end{ExempleMP}
1117
1118 This command transparently colors the specified squares.
1119
1120 \subsection{Circles}
1121
1122 \mpchess allows you to surround squares with circles using the following command
1123 below:
1124
1125 \commande|draw_circles(«color»)(«coord1»,«coord2», etc.)|\index{draw_circles@\lstinline+draw_circles+}\smallskip
1126
1127 \begin{description}
1128 \item[\meta{color}:] is a \MP{} \lstinline+color+.
1129 \item[\meta{coord1}:] is a string (between double quotes) consisting of two
1130 coordinates (letter and number).
1131 \end{description}
1132
1133 The following example illustrates the use of this command.
1134
1135 \begin{ExempleMP}
1136 input mpchess
1137 beginfig(0);
1138 init_backboard;
1139 draw backboard;
1140 init_chessboard;
1141 draw chessboard;
1142 draw_circles(green)("e2","e7","c5");
1143 endfig;
1144 \end{ExempleMP}
1145
1146
1147
1148 \subsection{Crosses}
1149
1150
1151 \mpchess allows you to draw crosses on squares with the following command:
1152
1153 \commande|draw_crosses(«color»)(«coord1»,«coord2», etc.)|\index{draw_crosses@\lstinline+draw_crosses+}\smallskip
1154
1155 \begin{description}
1156 \item[\meta{color}:] is a \MP{} \lstinline+color+.
1157 \item[\meta{coord1}:] is a string (between double quotes) consisting of two
1158 coordinates (a letter and a number).
1159 \end{description}
1160
1161 The following example illustrates the use of this command.
1162
1163
1164 \begin{ExempleMP}
1165 input mpchess
1166 beginfig(0);
1167 init_backboard;
1168 draw backboard;
1169 init_chessboard;
1170 draw chessboard;
1171 draw_crosses(0.7[green,black])("e2","e7","c5");
1172 endfig;
1173 \end{ExempleMP}
1174
1175 \subsection{Move Comments}
1176
1177 \mpchess allows you to display the classic move comments of the type
1178 ``!?’’ with the following command:
1179
1180 \commande|draw_comment(«str»,«pos»)|\index{draw_comment@\lstinline+draw_comment+}\smallskip
1181
1182 \begin{description}
1183 \item[\meta{str}:] is a string (between double quotes) to display.
1184 \item[\meta{pos}:] is a string (between double quotes) consisting
1185 of a coordinate (a letter and a number).
1186 \end{description}
1187
1188 \begin{ExempleMP}
1189 input mpchess;
1190 string pgnstr;
1191 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1192 build_chessboards_from_pgn(pgnstr);
1193 beginfig(0);
1194 init_backboard;
1195 draw backboard;
1196 show_last_move(3);
1197 draw chessboard_step(3); % Nf3
1198 draw_comment("?!","f3");
1199 endfig;
1200 \end{ExempleMP}
1201
1202 The color of the comment annotation can be changed with the following command:
1203 \commande|set_comment_color(«color»)|\index{set_comment_color@\lstinline+set_comment_color+}\smallskip
1204
1205
1206 \subsection{Main Lines}
1207
1208 \mpchess provides a command to display the arrows of the moves of the
1209 main lines of analysis. There are commands for both colors.
1210
1211 \commande|draw_white_main_lines(«move1»,«move2»,etc.)|\index{draw_white_main_lines@\lstinline+draw_white_main_lines+}\smallskip
1212
1213 \commande|draw_black_main_lines(«move1»,«move2»,etc.)|\index{draw_black_main_lines@\lstinline+draw_black_main_lines+}\smallskip
1214
1215 \begin{description}
1216 \item[\meta{move1}, \meta{move2}, etc.:] are the moves to be illustrated using
1217 \textsc{pgn} notation.
1218 \end{description}
1219
1220 When using the format \textsc{pgn} for the construction of the positions to be
1221 to be displayed, the following commands can be used
1222 to specify which move of the game is being commented on:
1223
1224 \commande|draw_white_main_lines_step(«step»)(«move1»,«move2»,etc.)|\index{draw_white_main_lines_step@\lstinline+draw_white_main_lines_step+}\smallskip
1225
1226 \commande|draw_black_main_lines_step(«step»)(«move1»,«move2»,etc.)|\index{draw_black_main_lines_step@\lstinline+draw_black_main_lines_step+}\smallskip
1227
1228 \begin{description}
1229 \item[\meta{step}:] is the step of the game you want to annote;
1230 \item[\meta{move1}, \meta{move2}, etc.:] are the moves to be illustrated using
1231 \textsc{pgn} notation.
1232 \end{description}
1233
1234 The following example illustrates the use of this command:
1235 \begin{ExempleMP}
1236 input mpchess
1237 string pgnstr;
1238 pgnstr:="1. e4 d5";
1239 build_chessboards_from_pgn(pgnstr);
1240 beginfig(0);
1241 init_backboard;
1242 draw backboard;
1243 draw chessboard_step(2);
1244 draw_white_main_lines_step(2)("exd5","e5","Nc3");
1245 endfig;
1246 \end{ExempleMP}
1247
1248 To change the color (by default \lstinline+0.3[_blackColorSquare,black]+),
1249 use the following command:
1250
1251 \commande|set_main_lines_color(«color»)|\index{set_main_lines_color@\lstinline+set_main_lines_color+}\smallskip
1252
1253
1254 \subsection{Possible Moves}\label{sec:possiblemoves}
1255
1256 \mpchess allows, by imitating \href{Lichess.org}{https://lichess.org},
1257 to show possible moves for a piece. To do that, use the following command:
1258
1259 \commande|show_possible_moves(«square»)|\index{show_possible_moves@\lstinline+show_possible_moves+}\smallskip
1260
1261 \begin{description}
1262 \item[\meta{square}:] is a string (between double quotes) consisting
1263 of a coordinate (a letter and a number).
1264 \end{description}
1265
1266 This command must be used after having drawn the \lstinline+chessboard+.
1267
1268 \begin{ExempleMP}
1269 input mpchess
1270 string fenstr;
1271 fenstr:="7r/2p1kp1p/p1B2p2/1pb5/8/2PP4/PP1N1PPP/R5K1 b - - 2 19";
1272 build_chessboard_from_fen(fenstr);
1273 beginfig(0);
1274 set_black_view;
1275 init_backboard;
1276 draw backboard;
1277 draw chessboard;
1278 show_possible_moves("c5");
1279 endfig;
1280 \end{ExempleMP}
1281
1282 In the case where several positions have been constructed with \textsc{pgn}
1283 format, the following command should be used to access the chosen position.
1284
1285 \commande|show_possible_moves_step(«step»)(«square»)|\index{show_possible_moves_step@\lstinline+show_possible_moves_step+}\smallskip
1286
1287 \begin{description}
1288 \item[\meta{step}:] is the step of the game you want to annote;
1289 \item[\meta{square}:] is a string (between double quotes) consisting
1290 of a coordinate (a letter and a number).
1291 \end{description}
1292
1293 By default, the color is set to \lstinline+0.4[green,black]+, but this can be changed with the can be changed with the following command:
1294
1295 \commande|set_possible_moves_color(«color»)|\index{set_possible_moves_color@\lstinline+set_possible_moves_color+}\smallskip
1296
1297 \section{Miscellaneous}
1298
1299 \subsection{Reset the \lstinline+chessboard+}
1300
1301 To reset the internal structure storing the positions of the parts, use
1302 the following command:
1303
1304
1305 \commande|clear_chessboard|\index{clear_chessboard@\lstinline+clear_chessboard+}\smallskip
1306
1307
1308 \subsection{Global Reset}
1309
1310 To reinitialize the values of the different parameters of \mpchess, use
1311 the following command:
1312
1313 \commande|reset_mpchess|\index{reset_mpchess@\lstinline+reset_mpchess+}\smallskip
1314
1315
1316 \subsection{Clip the board}
1317
1318 We can clip the chessboard with the following command.
1319
1320 \commande|clip_chessboard(«string»)|\index{clip_chessboard@\lstinline+clip_chessboard+}\smallskip
1321
1322
1323 \begin{description}
1324 \item[\meta{string}:] is a string (between double quotes)
1325 composed of two coordinates (letter and number) separated by a dash; for example \lstinline+"a1-c6"+.
1326 \end{description}
1327
1328 Here is an example of an illustration:
1329 \begin{ExempleMP}
1330 input mpchess;
1331 string pgnstr;
1332 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1333 build_chessboards_from_pgn(pgnstr);
1334 beginfig(0);
1335 set_black_view;
1336 init_backboard;
1337 draw backboard;
1338 show_last_move(3);
1339 draw chessboard_step(3); % Nf3
1340 draw_comment("?!","f3");
1341 clip_chessboard("e1-g4");
1342 endfig;
1343 \end{ExempleMP}
1344
1345
1346 \section{Use with \LaTeX{}}
1347
1348 \subsection{Use with \hologo{pdfLaTeX} or \hologo{XeLaTeX}}
1349
1350 There are several ways to include the images produced by \mpchess in a \LaTeX
1351 document. The first is to generate pdf files with \MP{} and then to include them
1352 with \lstinline[language=TeX]+\includegraphics+. This solution works with all
1353 engines.
1354
1355 You can also use the packages \package{gmp} or \package{mpgraphics} with
1356 \hologo{pdfLaTeX} or \hologo{XeLaTeX}\footnote{We would like to thank Quark67
1357 for the questions and advice}.
1358
1359 \subsubsection{With \package{mpgraphics}}
1360
1361 With \package{mpgraphics}~\cite{ctan-mpgraphics}, we load \mpchess with the
1362 \lstinline+mpdefs+ environment and we can produce images with \MP{}
1363 code but without using \lstinline+beginfig+ and \lstinline+endfig+;
1364 rather, the code to generate a figure is in the
1365 \lstinline+mpdisplay+ environment. It will be necessary to use the option
1366 \lstinline+-shell-escape+ when compiling the \LaTeX document.
1367
1368 Here is a complete example:
1369
1370 \begin{latexcode}
1371 \documentclass{article}
1372 \usepackage{mpgraphics}
1373 \begin{document}
1374 \begin{mpdefs}
1375 input mpchess
1376 \end{mpdefs}
1377 \begin{mpdisplay}
1378 init_backboard;
1379 draw backboard;
1380 init_chessboard;
1381 draw chessboard;
1382 draw_arrows(red)("e7--e5","g1|-f3");
1383 \end{mpdisplay}
1384 \end{document}
1385 \end{latexcode}
1386
1387 \subsubsection{With \package{gmp}}
1388
1389 The use of the package \package{gmp}~\cite{ctan-gmp} is quite similar to that of
1390 \package{mpgraphics}. Some commands are different, but as with
1391 \package{mpgraphics}, we do not use \lstinline+beginfig+ and
1392 \lstinline+endfig+. The loading of \mpchess can be done when loading the
1393 package, and the \MP{} code is in a \lstinline+mpost+ environment. Here again
1394 it will be necessary to compile the \LaTeX{} document with the
1395 \lstinline+-shell-escape+ option.
1396
1397
1398 Here is a complete example:
1399
1400
1401 \begin{latexcode}
1402 \documentclass{article}
1403 \usepackage[shellescape, everymp={input mpchess;}]{gmp}
1404
1405 \begin{document}
1406
1407 \begin{mpost}
1408 init_backboard;
1409 draw backboard;
1410 init_chessboard;
1411 draw chessboard;
1412 draw_arrows(red)("e7--e5","g1|-f3");
1413 \end{mpost}
1414 \end{document}
1415 \end{latexcode}
1416 \subsection{Use with \hologo{LuaLaTeX} and \package{luamplib}}
1417
1418 It is possible to use \mpchess directly in a \LaTeX{} file with
1419 \hologo{LuaLaTeX} and the package \package{luamplib}. (This is what is done to
1420 write this documentation.)
1421
1422 It then suffices to put the \MP{} code in the environment
1423 \lstinline+mplibcode+.
1424
1425 For certain functionalities, \mpchess uses the \MP{} operator
1426 \lstinline+infont+. Thus, in order for the content of these features to be composed in the current font of the document, one must add the command
1427 \begin{latexcode}
1428 \mplibtextextlabel{enable}
1429 \end{latexcode}
1430
1431
1432
1433 For more details on these mechanisms, refer to the
1434 +\package{luamplib}~\cite{ctan-luamplib} documentation.
1435
1436 We can load globally \mpchess with the following command:
1437
1438 \begin{latexcode}
1439 \everymplib{input mpchess;}
1440 \end{latexcode}
1441
1442 Here is a complete example (to be compiled with
1443 \hologo{LuaLaTeX}).
1444
1445
1446 \begin{latexcode}
1447 \documentclass{article}
1448 \usepackage{luamplib}
1449
1450 \everymplib{input mpchess;}
1451
1452 \begin{document}
1453
1454 \begin{mplibcode}
1455 beginfig(0);
1456 init_backboard;
1457 draw backboard;
1458 init_chessboard;
1459 draw chessboard;
1460 draw_arrows(red)("e7--e5","g1|-f3");
1461 endfig;
1462 \end{mplibcode}
1463 \end{document}
1464 \end{latexcode}
1465
1466 \subsection{TrueType Font}
1467
1468 The \mpchess{} package provides a very simple font composed of only the 12
1469 glyphs corresponding to the black and white pieces in the Unicode table. To
1470 access it you just have to use \hologo{LuaLaTeX} or \hologo{XeLaTeX} and the
1471 package \package{fontspec}. To facilitate its use, we propose
1472 some definitions.
1473
1474 \begin{latexcode}
1475 \documentclass{article}
1476 \usepackage{fontspec}
1477 \newfontfamily{\chessfont}{mpchess font}
1478 \newcommand\bP{{\chessfont \char"265F}} % black Pawn
1479 \newcommand\bN{{\chessfont \char"265E}} % black Knight
1480 \newcommand\bB{{\chessfont \char"265D}} % black Bishop
1481 \newcommand\bR{{\chessfont \char"265C}} % black Rook
1482 \newcommand\bQ{{\chessfont \char"265B}} % black Queen
1483 \newcommand\bK{{\chessfont \char"265A}} % black King
1484 \newcommand\wP{{\chessfont \char"2659}} % white Pawn
1485 \newcommand\wN{{\chessfont \char"2658}} % white Knight
1486 \newcommand\wB{{\chessfont \char"2657}} % white Bishop
1487 \newcommand\wR{{\chessfont \char"2656}} % white Rook
1488 \newcommand\wQ{{\chessfont \char"2655}} % white Queen
1489 \newcommand\wK{{\chessfont \char"2654}} % white King
1490
1491 \begin{document}
1492
1493 1. e4 e5 2. \wB c4 d6 3. \wN f3 \bB g4 4. \wN
1494 c3 g6 5. \wN xe5 \bB xd1.
1495
1496 \end{document}
1497 \end{latexcode}
1498
1499 This code will produce:
1500
1501 "1. e4 e5 2. \wB c4 d6 3. \wN f3 \bB g4
1502 4. \wN c3 g6 5. \wN xe5 \bB xd1."
1503
1504 \section{To Do}
1505
1506 Many things can be added to \mpchess. Among these, we can think of:
1507 \begin{itemize}
1508 \item display the captured pieces, or the differential of the captured pieces;
1509 \item display the remaining time for each player;
1510 \item parsing the complete \textsc{pgn} format with the optional tags ;
1511 \item adding the coordinates outside the board when it is clipped;
1512 \item add piece themes.
1513 \end{itemize}
1514
1515 \section{Complete Example}
1516
1517 \begin{ExempleMP}[sidebyside=false]
1518 input mpchess
1519 string pgnstr;
1520 pgnstr:="1. e4 e5 2. Bc4 d6 3. Nf3 Bg4 4. Nc3 g6 5. Nxe5 Bxd1";
1521 build_chessboards_from_pgn(pgnstr);
1522 beginfig(0);
1523 set_white_player("Kermur de Legal");
1524 set_black_player("Saint-Brie");
1525 set_backboard_width(8cm);
1526 init_backboard;
1527 draw backboard;
1528 show_last_move(10);
1529 draw_comment("?","d1");
1530 color_square(0.3[green,black])("c4","c3","e5");
1531 color_square(0.3[red,black])("e8");
1532 draw chessboard_step(10);
1533 draw_arrows(0.3[green,black])("e5|-f7","c3-|d5");
1534 draw_arrows(0.3[red,black])("c4--f7");
1535 endfig;
1536 \end{ExempleMP}
1537
1538 \section{History}
1539
1540 \begin{description}
1541 \item[v0.9, December 16, 2024:] Correction of a bug in the placement of the
1542 trait marker (by Udi Fogiel), added different marker features (\lstinline
1543 +"triangle"+, \lstinline+"square"+,\lstinline+"disk"+ and \lstinline+"custom"+). Filling of the white marker.
1544 \item[v0.8, October 26, 2024:] Adding \lstinline+"Dotted"+ board theme, and
1545 \lstinline+"User"+ board theme that allows user to define black and white
1546 squares.
1547 \item[v0.7, July, 2023:] Black knight adjustment, adding color board themes (\lstinline+GreenLichess+, \lstinline+PinkPyramidalLichess+,
1548 \lstinline+Wood+ with color type (\lstinline+set_board_type+)).
1549 \item[v0.6, April 26, 2023:] Fixed bugs concerning castling management, and
1550 moves ambiguities in \textsc{pgn} format.
1551 Changed \lstinline+set_white_color+ to
1552 \lstinline+set_white_squares_color+ and \lstinline+set_black_color+ to
1553 \lstinline+set_black_squares_color+. Change \lstinline+set_no_coords+ to
1554 \lstinline+hide_coordinates+ and \lstinline+set_coords+ to
1555 \lstinline+show_coordinates+. Change \lstinline+set_whos_to_move+ to
1556 \lstinline+show_whos_to_move+ and \lstinline+unset_whos_to_move+ to
1557 \lstinline+hide_whos_to_move+. Change \lstinline+set_coords_inside+ and
1558 \lstinline+set_coords_outside+ to \lstinline+set_coordinates_position+.
1559 Change \lstinline+set_coords_font+ to \lstinline+set_coordinates_font+.
1560 \item[v0.5, April 20, 2023:] Bug fixed, \textbf{changing the
1561 default piece set} for the \lstinline+mpchess+ set (which has been added to Lichess), added TrueType font, and updated documentation.
1562 \item[v0.4, April 6, 2023:] Corrections in the documentation, especially the
1563 English version; added commands to visualize the possible movements for a
1564 piece (section~\ref{sec:possiblemoves}).
1565 \item[v0.3, March 29, 2023:] Small bug.
1566 \item [v0.2, March 28, 2023:] Added commands for \textsc{pgn} and \textsc{fen}
1567 file reading; added commands for displaying the main lines of
1568 analysis; removal of the \lstinline+staunty+ theme (because of
1569 license) and creation of the \lstinline+mpchess+ parts theme.
1570 \item[v0.1, March 23, 2023:] First publication on the \ctan.
1571 \end{description}
1572
1573 \section{Acknowledgements}
1574
1575 The author would like to thank Quark67 for his feedback and corrections,
1576 Douglas Johnson for correcting the English version of the documentation and Hans
1577 Nieuwenhuis for his advices.
1578 This
1579 feedback and encouragement is extremely appreciated!
1580
1581
1582 \printbibliography
1583 \printindex
1584 \end{document}
1585
1586
1587
1588 %%% Local Variables:
1589 %%% flyspell-mode: 1
1590 %%% ispell-local-dictionary: "fr"
1591 %%% End: