Debian Codegraph @

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

raw
1
2 % LTeX: language=fr
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[french]{ltxdoc}
14
15 \input{mpchess-preamble}
16
17
18 \usepackage[french]{babel}
19
20 \makeindex[title=Index des commandes, columns=2]
21
22
23
24
25 %\lstset{moredelim=*[s][\color{red}\rmfamily\itshape]{<}{>}}
26 %\lstset{moredelim=*[s][\color{blue}\rmfamily\itshape]{<<}{>>}}
27
28 \begin{document}
29
30 \title{{MPchess} : dessiner des plateaux d’échecs et des positions avec \hologo{METAPOST}}
31 \author{Maxime Chupin, \url{[email protected]}}
32 \date{\today}
33
34 %% === Page de garde ===================================================
35 \thispagestyle{empty}
36 \begin{tikzpicture}[remember picture, overlay]
37 \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
38 \includegraphics{fond.pdf}%
39 };
40 \end{tikzpicture}%
41
42
43 \noindent
44 {\Huge \mpchess}\par\medskip
45 \noindent
46 {\Large dessiner des plateaux d’échecs et des positions avec \hologo{METAPOST}}\\[1cm]
47 \parbox{0.6\textwidth}{
48 \begin{mplibcode}
49 input mpchess
50 string pgnstr;
51 pgnstr:="1. e4 e5 2. Bc4 d6 3. Nf3 Bg4 4. Nc3 g6 5. Nxe5 Bxd1 ";
52 build_chessboards_from_pgn(pgnstr);
53 beginfig(0);
54 set_backboard_width(8cm);
55 init_backboard;
56 draw backboard;
57 show_last_move(10);
58 draw_comment("?","d1");
59 color_square(0.3[green,black])("c4","c3","e5");
60 color_square(0.3[red,black])("e8");
61 draw chessboard_step(10);
62 draw_arrows(0.3[green,black])("e5|-f7","c3-|d5");
63 draw_arrows(0.3[red,black])("c4--f7");
64 endfig;
65 \end{mplibcode}
66 }\hfill
67 \parbox{0.5\textwidth}{\Large\raggedleft
68 \textbf{Contributeur}\\
69 Maxime \textsc{Chupin}\\
70 \url{[email protected]}
71 }
72 \vfill
73 \begin{center}
74 Version 0.9, 16 décembre 2024 \\
75 \url{https://gitlab.gutenberg-asso.fr/mchupin/mpchess}
76 \end{center}
77 %% == Page de garde ====================================================
78 \newpage
79
80 %\maketitle
81
82 \begin{abstract}
83 Ce package \MP{} permet de dessiner des plateaux d’échecs et des positions.
84 L’apparence des dessins se veut moderne et largement inspiré de ce que propose
85 l’excellent site web \url{Lichess.org}.
86 S’appuyer sur \MP{} permet sans doute plus de flexibilité graphique que les
87 excellent packages \LaTeX{}.
88 \end{abstract}
89
90
91 \begin{center}
92 \url{https://gitlab.gutenberg-asso.fr/mchupin/mpchess}
93 \url{https://github.com/chupinmaxime/mpchess}
94 \end{center}
95
96 \tableofcontents
97
98 \bigskip
99
100 \begin{tcolorbox}[ arc=0pt,outer arc=0pt,
101 colback=darkred!3,
102 colframe=darkred,
103 breakable,
104 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
105 3pt, toptitle=3pt,
106 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
107 0pt, bottomrule at break = 0pt,]
108 \itshape
109 Ce package est en version beta, n’hésitez pas à faire remonter les bugs, ainsi
110 que les demandes d’amélioration.
111 \end{tcolorbox}
112
113 \section{Installation}
114
115 \mpchess est sur le \ctan{} et peut être installé via le gestionnaire de package
116 de votre distribution.
117
118 \begin{center}
119 \url{https://www.ctan.org/pkg/mpchess}
120 \end{center}
121
122
123 \subsection{Avec la \TeX live sous Linux ou macOS}
124
125 Pour installer \mpchess avec \TeX live, il vous faudra créer le répertoire
126 \lstinline+texmf+ dans votre \lstinline+home+.
127
128 \begin{commandshell}
129 mkdir ~/texmf
130 \end{commandshell}
131
132 Ensuite, il faudra y placer les fichiers \lstinline+.mp+ dans le répertoire \begin{center}
133 \lstinline+~/texmf/metapost/mpchess/+
134 \end{center}
135
136 \mpchess est constitué de 7 fichiers \hologo{METAPOST} :
137 \begin{itemize}
138 \item \verb+mpchess.mp+;
139 \item \verb+mpchess-chessboard.mp+;
140 \item \verb+mpchess-pgn.mp+;
141 \item \verb+mpchess-fen.mp+;
142 \item \verb+mpchess-cburnett.mp+;
143 \item \verb+mpchess-pieces.mp+;
144 \item \verb+mpchess-skak.mp+.
145 \end{itemize}
146
147 Une fois fait cela, \mpchess sera chargé avec le classique
148 \begin{mpcode}
149 input mpchess
150 \end{mpcode}
151
152 \subsection{Avec Mik\TeX{} et Windows}
153
154 Ces deux systèmes sont inconnus de l’auteur de \mpchess, ainsi, nous renvoyons à
155 leurs documentations pour y ajouter des packages locaux :
156 \begin{center}
157 \url{http://docs.miktex.org/manual/localadditions.html}
158 \end{center}
159
160
161
162 \subsection{Dépendances}
163
164 \mpchess dépend des packages \MP: \package{hatching} et, si
165 \mpchess n’est pas utilisé avec \hologo{LuaLaTeX} et \package{luamplib},
166 \package{latexmp}.
167 \section{Pourquoi ce package et philosophie générale}
168
169 Il existe déjà des packages \LaTeX{} pour dessiner des plateaux d’échecs et des
170 positions dont le très bon \package{xskak}~\cite{ctan-xskak} couplé avec le
171 package \package{chessboard}~\cite{ctan-chessboard}. Ulrike Fisher a réalisé là un
172 travail d’amélioration, de maintient, et nous a fourni d’excellents outils pour
173 réaliser des diagrammes d’échecs et de traiter les différents formats de
174 descriptions de parties\footnote{Elle a même développé le
175 package~\package{chessfss} pour gérer diverses fontes d’échec.}. Les
176 documentations de ces packages sont de très bonnes qualités.
177
178 Plusieurs choses ont motivé la création de \mpchess. Tout d’abord, avec
179 \package{chessboard} l’ajout d’ensemble de pièces n’est pas très aisé, car cela
180 repose sur des fontes. De plus, je trouve que le dessin de diagrammes de parties
181 d’échec est quelque chose de très graphique, et que le passage par un langage
182 dédié au dessin offre plus de souplesse et quoi de mieux que \MP~\cite{ctan-metapost}.
183
184
185 Avec \mpchess, on construit l’image finale du plateau d’échec avec les pièces
186 par couches successives. Ainsi, on commencera par produire et dessiner le
187 plateau (\lstinline+backboard+), que l’on pourra modifier en colorant par
188 exemple certaines cases, ensuite on ajoutera les pièces de la position
189 (\lstinline+chessboard+), et enfin, on pourra annoter le tout avec des marques, des couleurs, des flèches, etc.
190
191 Par ailleurs, \mpchess produit des images proches graphiquement de ce que peut
192 fournir l’excellent site \emph{open source} \url{https://lichess.org}. Vous
193 verrez que les couleurs, les pièces et l’aspect général sont largement inspirés
194 de ce que propose ce site.
195
196 \section{Plateau}
197
198 Le plateau est appelé avec \mpchess{} \lstinline+backboard+.
199 Il faudra initialiser le plateau avant de le dessiner. Cela se fait avec la
200 commande suivante :\par
201
202 \commande|init_backboard|\smallskip\index{init_backboard@\lstinline+init_backboard+}
203
204
205 Cette commande construit une \lstinline+picture+ de \MP{} nommée
206 \mbox{\lstinline+backboard+.} Il faudra ensuite la tracer comme l’illustre l’exemple
207 suivant.
208
209 \begin{ExempleMP}
210 input mpchess
211
212 beginfig(0);
213 init_backboard;
214 draw backboard;
215 endfig;
216 \end{ExempleMP}
217
218 Cette initialisation permettra de prendre en compte les différentes options et
219 fonctionnalités que nous allons décrire dans la suite.
220 \subsection{Réglage des tailles}
221 Lors de la création du \lstinline+backboard+, on peut décider de la largeur de celui-ci. Cela se fait grâce à la commande suivante :\par\bigskip
222
223 \commande|set_backboard_width(«dim»)|\smallskip\index{set_backboard_width@\lstinline+set_backboard_width+}
224
225 \begin{description}
226 \item[\meta{dim}:] est la largeur de plateau de jeu souhaitée (avec l’unité). Par défaut, cette dimension est à \SI{5}{cm}.
227 \end{description}
228
229 L’utilisation de cette commande est illustré à l’exemple~\ref{ex:widthcase}. Cette commande est à utilisée avant \lstinline+init_backboard+ pour qu’elle soit prise en compte à la création de l’image.
230 \bigskip
231
232 On peut récupérer la dimension du plateau de jeu par la commande suivante.
233
234 \commande|get_backboard_width|\smallskip\index{get_backboard_width@\lstinline+get_backboard_width+}
235
236 Cette commande retourne un type \lstinline+numeric+.
237
238 \subsection{Nombre de case}
239 Par défaut, le plateau de jeu contient 64 cases ($8\times 8$). On peut modifier
240 cela avec la commande suivante:
241
242 \commande|set_backboard_size(«nbr»)|
243 \smallskip\index{set_backboard_size@\lstinline+set_backboard_size+}
244
245 \begin{description}
246 \item[\meta{nbr}:] est le nombre de cases souhaité. Le plateau sera alors carré de taille \meta{nbr}$\times$\meta{nbr}. Par défaut ce nombre est à 8.
247 \end{description}
248
249 Encore une fois, cette commande est à utilisée avant \lstinline+init_backboard+ pour qu’elle soit prise en compte comme le montre l’exemple suivant.
250
251 \begin{ExempleMP}[label=ex:widthcase]
252 input mpchess
253
254 beginfig(0);
255 set_backboard_width(3cm);
256 set_backboard_size(6);
257 init_backboard;
258 draw backboard;
259 endfig;
260 \end{ExempleMP}
261
262 Pour obtenir la taille du plateau de jeu, on pourra utiliser la commande
263 suivante.
264
265 \commande|get_backboard_size|\smallskip\index{get_backboard_size@\lstinline+get_backboard_size+}
266
267 Cette commande retourne un type \lstinline+numeric+.
268
269 \subsection{Dimension d’une case}
270
271 En fonction du nombre de cases sur le plateau et la largeur prescrite pour le
272 plateau, \mpchess calcule la dimension (largeur ou hauteur) d’une case. Cela
273 sert d’unité générale. Pour l’obtenir, on utilisera la commande suivante.
274
275 \commande|get_square_dim|\smallskip\index{get_square_dim@\lstinline+get_square_dim+}
276
277 Cette commande retourne un \lstinline+numeric+.
278
279 \subsection{Réglage du thème de couleur}
280
281 \subsubsection{Thèmes prédéfinis}
282
283 Plusieurs thèmes de couleurs sont accessibles. Pour choisir un thème de couleur, on utilisera la commande suivante :
284
285 \commande|set_color_theme(«string»)|\smallskip\index{set_color_theme@\lstinline+set_color_theme+}
286
287 \begin{description}
288 \item[\meta{string}] peut valoir :
289 \begin{itemize}
290 \item \lstinline+"BlueLichess"+ (thème par défaut);
291 \item \lstinline+"BrownLichess"+ ;
292 \item \lstinline+"GreenLichess"+;
293 \item \lstinline+"PinkPyramidalLichess"+;
294 \item \lstinline+"Wood"+;
295 \item \lstinline+"Classical"+;
296 \item \lstinline+"Dotted"+;
297 \item ou \lstinline+"User"+.
298 \end{itemize}
299 \end{description}
300
301 Les exemples suivants montrent les résultats obtenus pour les thèmes prédéfinis.
302 \begin{ExempleMP}
303 input mpchess
304 beginfig(0);
305 set_color_theme("BrownLichess");
306 init_backboard;
307 draw backboard;
308 endfig;
309 \end{ExempleMP}
310
311 Le tableau~\ref{tab:color} montre les résultats des différents thèmes fournis
312 par \mpchess.
313
314 \begin{table}
315 \centering
316 \begin{tabular}{cc}
317
318 Thème \lstinline+"GreenLichess"+&Thème \lstinline+"Classical"+\\
319 \begin{mplibcode}
320 input mpchess
321 beginfig(0);
322 init_chessboard;
323 set_backboard_width(4cm);
324 set_color_theme("GreenLichess");
325 init_backboard;
326 draw backboard;
327 endfig;
328 \end{mplibcode}
329 &\begin{mplibcode}
330 input mpchess
331 beginfig(0);
332 init_chessboard;
333 set_backboard_width(4cm);
334 set_color_theme("Classical");
335 init_backboard;
336 draw backboard;
337 endfig;
338 \end{mplibcode}\\
339 Thème \lstinline+"PinkPyramidalLichess"+&Thème \lstinline+"Wood"+\\
340 \begin{mplibcode}
341 input mpchess
342 beginfig(0);
343 init_chessboard;
344 set_backboard_width(4cm);
345 set_color_theme("PinkPyramidalLichess");
346 init_backboard;
347 draw backboard;
348 endfig;
349 \end{mplibcode}&
350 \begin{mplibcode}
351 input mpchess
352 beginfig(0);
353 init_chessboard;
354 set_backboard_width(4cm);
355 set_color_theme("Wood");
356 init_backboard;
357 draw backboard;
358 endfig;
359 \end{mplibcode}\\
360 Thème \lstinline+"Dotted"+&\\
361 \begin{mplibcode}
362 input mpchess
363 beginfig(0);
364 init_chessboard;
365 set_backboard_width(4cm);
366 set_color_theme("Dotted");
367 init_backboard;
368 draw backboard;
369 endfig;
370 \end{mplibcode}&\\
371 \end{tabular}
372 \caption{Les différents thèmes de couleur fournis par \mpchess.}\label{tab:color}
373 \end{table}
374
375 L’utilisation de \lstinline+"User"+ est un cas particulier, car il permet de
376 définir soit même les casses noires et blanches. Pour que cela fonctionne, il
377 faut définir en plus une macro \lstinline+buildUserSquare+\index{buildUserSquare@\lstinline+buildUserSquare+} qui construit les
378 images (\lstinline+picture+) internes \lstinline+_blackSquarePic+\index{_blackSquarePic@\lstinline+_blackSquarePic+} et
379 \lstinline+_whiteSquarePic+\index{_whiteSquarePic@\lstinline+_whiteSquarePic+} dont voici un prototype :
380 \begin{mpcode}
381 def buildUserSquare(expr _SquareUnit)=
382 _blackSquarePic:=image(
383 fill (unitsquare scaled _SquareUnit) withcolor red;
384 );
385 _whiteSquarePic:=image(
386 fill unitsquare scaled _SquareUnit withcolor green;
387 );
388 enddef;
389 \end{mpcode}
390 La macro prend en argument une unité, et doit construire deux carrés de côté
391 cette unité.
392
393
394 \subsubsection{Configuration d’un thème personnel}
395
396 \paragraph{Couleurs.}
397 Un thème de couleur conciste en la définition de deux couleurs.
398 Celles-ci peuvent se définir avec les commandes suivantes \footnote{Attention,
399 lors du passage à la version 0.6, \lstinline+set_white_color+ est devenu
400 \lstinline+set_white_squares_color+ et \lstinline+set_black_color+ est devenu
401 \lstinline+set_black_squares_color+.}.
402
403 \commande|set_white_squares_color(«color»)|\index{set_white_squares_color@\lstinline+set_white_squares_color+}\par
404 \commande|set_black_squares_color(«color»)|\index{set_black_squares_color@\lstinline+set_black_squares_color+}\smallskip
405
406 \meta{color} est une \lstinline+color+ \MP.
407
408 \begin{ExempleMP}
409 input mpchess
410 beginfig(0);
411 set_white_squares_color((0.9,0.8,0.8));
412 set_black_squares_color((0.7,0.6,0.6));
413 init_backboard;
414 draw backboard;
415 endfig;
416 \end{ExempleMP}
417
418 \paragraph{Type de coloriage.}
419
420
421 On peut choisir un type de coloriage avec la commande suivante:
422
423 \commande|set_board_type(«string»)|\index{set_board_type@\lstinline+set_board_type+}\smallskip
424
425 Les trois types de coloriage fournis par \mpchess{} se choisissent avec
426 \begin{description}
427 \item[\meta{string}] qui peut valoir:
428 \begin{itemize}
429 \item \lstinline+"flat"+, coloriage à plat (défaut);
430 \item \lstinline+"pyramidal"+, coloriage \emph{pyramidal} à la Lichess;
431 \item \lstinline+"wood"+, imitation bois.
432 \end{itemize}
433 \end{description}
434
435 Voici un exemple de paramétrage de couleur et de type de coloriage.
436
437 \begin{ExempleMP}
438 input mpchess
439 beginfig(0);
440 set_white_squares_color((0.9,0.8,0.8));
441 set_black_squares_color((0.7,0.6,0.6));
442 set_board_type("wood");
443 init_backboard;
444 draw backboard;
445 endfig;
446 \end{ExempleMP}
447
448 \subsection{Affichage des coordonnées}
449
450 Vous avez pu constater dans les divers exemples que par défaut, les coordonnées
451 sont, comme le fait le site Lichess, inscrites en petit à l’intérieur des
452 cases.
453
454 \mpchess permet de choisir le positionnement de ces coordonnées à l’extérieur ou
455 à l’intérieur du plateau avec la commande suivante\footnote{Attention,
456 en version 0.6, \lstinline+set_coords_inside+ et \lstinline+set_coords_outside+
457 ont été remplacés par
458 \lstinline+set_coordinates_position+.}.
459
460 \commande|set_coordinates_position(«string»)|\index{set_coordinates_position@\lstinline+set_coordinates_position+}\smallskip
461
462 \begin{description}
463 \item[\meta{string}] peut valoir :
464 \begin{itemize}
465 \item \lstinline+"inside"+ (par défaut);
466 \item \lstinline+"outside"+.
467 \end{itemize}
468 \end{description}
469
470
471 Le résultat est alors le suivant.
472
473 \begin{ExempleMP}
474 input mpchess
475 beginfig(0);
476 set_coordinates_position("outside");
477 init_backboard;
478 draw backboard;
479 endfig;
480 \end{ExempleMP}
481
482 Vous pouvez constater dans cette documentation qu’avec \package{luamplib} et
483 \LaTeX, la fonte est la fonte du document courant. Pour tracer ces lettres et
484 ces chiffres, \mpchess utilise l’opérateur \MP{} \lstinline+infont+ et la fonte
485 est réglée à \lstinline+defaultfont+ par défaut\footnote{Avec \package{luamplib}
486 l’opérateur \lstinline+infont+ est redéfini et son argument est simplement
487 ignoré, ainsi, il n’est pas possible de modifier la fonte de composition des
488 coordonnées.}. On peut modifier cette fonte avec la commande suivante\footnote{Attention,
489 en version 0.6, \lstinline+set_coords_font+ est devenue
490 \lstinline+set_coordinates_font+.}.
491
492 \commande|set_coordinates_font(«font»)|\index{set_coordinates_font@\lstinline+set_coordinates_font+}\smallskip
493
494 Il faudra alors utiliser les conventions de nommage propres à l’opérateur
495 \lstinline+infont+ de \MP{} et nous renvoyons à la
496 documentation~\cite{ctan-metapost} pour plus de détails.
497
498 On pourra aussi supprimer les coordonnées avec la commande suivante\footnote{Attention,
499 dans la version 0.6, \lstinline+set_no_coords+ est devenu
500 \lstinline+hide_coordinates+ et \lstinline+set_coords+ est devenu
501 \lstinline+show_coordinates+}.
502
503 \commande|hide_coordinates|\index{hide_coordinates@\lstinline+hide_coordinates+}\smallskip
504
505 Et la commande inverse aussi existe.
506
507 \commande|show_coordinates|\index{show_coordinates@\lstinline+show_coordinates+}\smallskip
508
509
510 \subsection{Vue blanche ou noire}
511
512 Pour choisir si l’on souhaite voir le plateau du côté blanc ou noir, \mpchess fournit deux commandes.
513
514 \commande|set_white_view|\index{set_white_view@\lstinline+set_white_view+}\smallskip
515
516 \commande|set_black_view|\index{set_black_view@\lstinline+set_black_view+}\smallskip
517
518 Par défaut, on voit l’échiquier côté blanc.
519
520 \subsection{Noms des joueurs}
521
522 On peut renseigner les noms des joueuses ou des joueurs pour qu’ils soient notés
523 autour de l’échiquier. Ceci se fait avec les commandes suivantes.
524 \commande|set_white_player(«string»)|\index{set_white_player@\lstinline+set_white_player+}\smallskip
525
526 \commande|set_black_player(«string»)|\index{set_black_player@\lstinline+set_black_player+}\smallskip
527
528 \begin{description}
529 \item[\meta{string} :] est la chaîne de caractères interprétée par \LaTeX{} à afficher.
530 \end{description}
531
532 \begin{ExempleMP}
533 input mpchess
534 beginfig(0);
535 set_white_player("\textbf{GM} Kasparov");
536 set_black_player("\textbf{GM} Kramnik");
537
538 init_backboard;
539 draw backboard;
540 endfig;
541 \end{ExempleMP}
542
543 Il est possible de placer les noms sur le côté droit du plateau sans les
544 bandeaux noirs présents par défaut. Cela se produit soit si les coordonnées sont
545 imprimées à l’extérieur du plateau, soit si la commande suivante est utilisée.
546
547 \commande|set_players_side|\index{set_players_side@\lstinline+set_players_side+}\smallskip
548
549 \begin{ExempleMP}[righthand width=0.6\linewidth]
550 input mpchess
551 beginfig(0);
552 set_white_player("\textbf{GM} Kasparov");
553 set_black_player("\textbf{GM} Kramnik");
554 set_players_side;
555 init_backboard;
556 draw backboard;
557 endfig;
558 \end{ExempleMP}
559
560
561
562 \section{Pièces et positions}
563
564 \mpchess, comme décrit plus haut, construit le graphique d’une position d’échec
565 couche par couche. Cette partie est dédiée à la configuration des pièces et des
566 positions.
567
568 En interne, \mpchess construit un tableau sur la grille du plateau. Ensuite, des
569 macros permettent de générer une \lstinline+picture+ à dessiner \emph{par
570 dessus} le plateau (\lstinline+backboard+).
571
572 \subsection{Réglage du thème des pièces}
573
574 \mpchess fournit pour l’instant trois thèmes de pièces. Le thème par défaut est
575 appelé \lstinline+mpchess+. Il a été designé pour ce package \hologo{METAPOST}.
576 Il a été proposé au projet Lichess, et a été accepté. Ainsi, vous aurez aussi
577 accès à l’ensemble de pièces \lstinline+mpchess+ avec Lichess\footnote{Les
578 projets libres se nourrissent mutuellement ! Même si évidemment, ce package a
579 bien plus emprunté à Lichess que le contraire.} ! Un autre thème est emprunté à
580 Lichess (\lstinline+cburnett+) et l’autre est emprunté au package~\package{skak}~\cite{ctan-skak}\footnote{Qui
581 fournit le code \MF{} pour la fonte de pièces d’échec, code qui a été
582 facilement adapté en \MP{} pour \mpchess.}.
583
584 Pour choisir le thème on utilisera la commande suivante.
585
586 \commande|set_pieces_theme(«string»)|\index{set_pieces_theme@\lstinline+set_pieces_theme+}\smallskip
587
588 \begin{description}
589 \item[\meta{string}:] peut valoir:
590 \begin{itemize}
591 \item \lstinline+"mpchess"+ (valeur par défaut), pour obtenir l’ensemble de pièces spécialement
592 conçu pour ce package ;
593 \item \lstinline+"cburnett"+, pour obtenir l’ensemble de pièces nommé \emph{cburnett} de Lichess;
594 \item \lstinline+"skak"+, pour obtenir l’ensemble de pièces du package~\package{skak}.
595 \end{itemize}
596 \end{description}
597
598 Le tableau~\ref{tab:pieces} montre le résultat des trois ensembles de pièces.
599 \begin{table}
600 \centering
601 \begin{tabular}{cc}
602
603 Thème \lstinline+cburnett+&Thème \lstinline+mpchess+\\
604 \begin{mplibcode}
605 input mpchess
606 beginfig(0);
607 init_chessboard;
608 set_backboard_width(4cm);
609 set_pieces_theme("cburnett");
610 hide_whos_to_move;
611 init_backboard;
612 draw backboard;
613 draw chessboard_step(0);
614 endfig;
615 \end{mplibcode}
616 &\begin{mplibcode}
617 input mpchess
618 beginfig(0);
619 init_chessboard;
620 set_backboard_width(4cm);
621 set_pieces_theme("mpchess");
622 hide_whos_to_move;
623 init_backboard;
624 draw backboard;
625 draw chessboard_step(0);
626 endfig;
627 \end{mplibcode}\\
628 Thème \lstinline+skak+&\\
629 \begin{mplibcode}
630 input mpchess
631 beginfig(0);
632 init_chessboard;
633 set_backboard_width(4cm);
634 set_pieces_theme("skak");
635 hide_whos_to_move;
636 init_backboard;
637 draw backboard;
638 draw chessboard_step(0);
639 endfig;
640 \end{mplibcode}&\\
641 \end{tabular}
642 \caption{Les différents thèmes de pièces fournits par \mpchess.}\label{tab:pieces}
643 \end{table}
644
645
646
647 \subsection{Trait}
648
649 \mpchess indique qui a le trait entre les blancs et les noirs. Ceci ce fait par
650 un petit triangle coloré (blanc ou noir) à l’extérieur du plateau (que vous
651 pourrez observer dans les nombreux exemples suivants).
652
653 Pour spécifier qui a le trait on utilisera les commandes suivantes.
654
655 \commande|set_white_to_move|\index{set_white_to_move@\lstinline+set_white_to_move+}\smallskip
656
657
658 \commande|set_black_to_move|\index{set_black_to_move@\lstinline+set_black_to_move+}\smallskip
659
660 Par défaut, c’est aux blancs de jouer, et cette information est affichée.
661
662 Pour activer ou désactiver l’affichage du trait, on utilisera une des deux commandes suivantes\footnote{Attention,
663 lors du passage à la version 0.6, \lstinline+set_whos_to_move+ et
664 \lstinline+unset_whos_to_move+ sont devenus \lstinline+show_whos_to_move+ et
665 \lstinline+hide_whos_to_move+.}.
666
667 \commande|show_whos_to_move|\index{show_whos_to_move@\lstinline+show_whos_to_move+}\smallskip
668
669
670 \commande|hide_whos_to_move|\index{hide_whos_to_move@\lstinline+hide_whos_to_move+}\smallskip
671
672 Il est désormais possible de changer l’apparence du marqueur de trait (depuis la
673 version 0.9\footnote{Merci à Udi Fogiel d’avoir corrigé un bug de placement et
674 d’avoir proposé des améliorations.}). Pour cela, \mpchess fournit trois styles:
675 \lstinline+"triangle"+ (par défaut), \lstinline+"square"+ et \lstinline+"disk"+.
676 Pour choisir le type de marquer, on utilisera la commande suivante:
677
678
679 \commande|set_marker_type(«string»)|\index{set_marker_type@\lstinline+set_marker_type+}\smallskip
680
681 \begin{description}
682 \item[\meta{string}:] peut valoir:
683 \begin{itemize}
684 \item \lstinline+"triangle"+ (valeur par défaut) ;
685 \item \lstinline+"square"+;
686 \item \lstinline+"disk"+;
687 \item \lstinline+"custom"+.
688 \end{itemize}
689 \end{description}
690
691 Vous pouvez ajuster la taille (par un facteur de la dimension d’unité) avec la
692 commande suivante:
693
694 \commande|set_marker_scale(«numeric»)|\index{set_marker_scale@\lstinline+set_marker_scale+}\smallskip
695
696 \begin{description}
697 \item[\meta{numeric}:] est un facteur de la dimension d’unité pour agrandir ou
698 rétrécir le marquer (la valeur par défaut est \num{0.35}).
699 \end{description}
700
701 La valeur \lstinline+"custom"+ du type de marqueur permet de définir soi même
702 l’apparence du marqueur. Lorsque cette option est appelée, il faut définir une
703 macro \MP{} \lstinline+custom_maker(expr s,r)+. Le paramètre \lstinline+s+ est
704 le réglage du facteur d’échelle : pour les marqueurs fournis par \mpchess, ce
705 sont des dessins contenus dans un carré de côté 1 (unité \MP) est mis à
706 l’échelle par \lstinline+s*_chessSquareU+. Le paramètre \lstinline+r+ est un
707 booléen qui permet de traiter le cas où le marqueur est tourné de 180 degrés
708 lorsqu’il est placé en haut de l’échiquier.
709
710 Par exemple, une macro \lstinline+custom_marker+ reproduisant le symbole en
711 triangle pourrait être la suivante:
712 \begin{mpcode}
713 def custom_marker(expr s, r)=
714 ((0,0)--(1,0)--(0.5,0.5)--cycle) if r: rotatedaround((0.5, 0.5/3), 180) fi scaled (s*_chessSquareU)
715 enddef;
716 \end{mpcode}
717
718 On ne définit que le contour qui sera, suivant le cas, colorié en blanc ou en
719 noir.
720
721 \begin{ExempleMP}
722 input mpchess
723 beginfig(0);
724 set_marker_type("disk");
725 set_marker_scale(0.5);
726 init_backboard;
727 draw backboard;
728 init_chessboard;
729 draw chessboard;
730 endfig;
731 \end{ExempleMP}
732
733 \subsection{Dessiner une position}
734
735 Les commandes décrites ci-dessous permet de construire une position de plusieurs
736 façons (ajout de pièces une à une, lecture de fichier \textsc{fen}, etc.). Une
737 fois une position construite, on peut la tracer grâce à la commande suivante qui
738 génère une \lstinline+picture+.
739
740 \commande|chessboard|\index{chessboard@\lstinline+chessboard+}\smallskip \label{com:chessboard}
741
742 L’utilisation de cette commande va être largement illustrée dans les exemples suivants.
743
744 \subsection{Construire une position}
745
746 \subsubsection{Initialisation}
747
748 Pour obtenir la position initiale d’une partie, il suffit d’utiliser la commande suivante.
749
750 \commande|init_chessboard|\index{init_chessboard@\lstinline+init_chessboard+}\smallskip
751
752 \begin{ExempleMP}
753 input mpchess
754 beginfig(0);
755 init_backboard;
756 draw backboard;
757 init_chessboard;
758 draw chessboard;
759 endfig;
760 \end{ExempleMP}
761
762 On pourra aussi initialiser un \lstinline+chessboard+ vide grâce à la commande suivante.
763
764 \commande|set_empty_chessboard|\index{set_empty_chessboard@\lstinline+set_empty_chessboard+}\smallskip
765
766 \subsubsection{Ajout de pièces}
767
768 On peut ajouter des pièces pour construire une position grâce aux deux commandes suivantes.
769
770 \commande|add_white_pieces(«piece1»,«piece2»,etc.)|\index{add_white_pieces@\lstinline+add_white_pieces+}\smallskip
771
772
773 \commande|add_black_pieces(«piece1»,«piece2»,etc.)|\index{add_black_pieces@\lstinline+add_black_pieces+}\smallskip
774
775 Ces commandes prennent des listes de \textbf{\meta{piece}} qui sont des chaînes
776 de caractères qui décrivent la pièce et la position en utilisant la notation
777 algébrique. Il n’y a pas de limitation au nombre de pièces dans la liste.
778
779 L’exemple suivant illustre l’utilisation de ces commandes.
780 \begin{ExempleMP}
781 input mpchess
782 beginfig(0);
783 init_backboard;
784 draw backboard;
785 set_empty_chessboard;
786 add_white_pieces("e1","Kd2");
787 add_black_pieces("e7","f6","Kb8");
788 draw chessboard;
789 endfig;
790 \end{ExempleMP}
791
792
793 \subsubsection{Suppression de pièces}
794
795 \mpchess fournit plusieurs commandes permettant de supprimer des éléments d’une position.
796
797 La première commande permet de supprimer un élément d’une case. Cette commande permet de prendre une liste de cases, en utilisant la notation algébrique.
798
799 \commande|clear_squares(«square1»,«square2»,etc.)|\index{clear_squares@\lstinline+clear_squares+}\smallskip
800
801 Les \textbf{\meta{square1}}, \textbf{\meta{square2}}, etc., sont des chaînes de caractères, par exemple \lstinline+"a3"+.
802 \medskip
803
804 La commande suivante permet de supprimer un ensemble de cases dans une région
805 déterminé par deux coordonnées sur le plateau. Cette commande permet de prendre
806 une liste de régions.
807
808 \commande|clear_areas(«area1»,«area2»,etc.)|\index{clear_areas@\lstinline+clear_areas+}\smallskip
809
810 Les \textbf{\meta{area1}}, \textbf{\meta{area2}}, etc., sont des chaînes de caractères constituées de deux coordonnées séparées par un tiret, par exemple \lstinline+"a3-g7"+.
811 \medskip
812
813 La commande suivante permet de supprimer l’ensemble des cases d’une colonne
814 déterminé par une lettre sur le plateau. Cette commande permet de prendre
815 une liste de colonnes.
816
817 \commande|clear_files(«file1»,«file2»,etc.)|\index{clear_files@\lstinline+clear_files+}\smallskip
818
819 Les \textbf{\meta{file1}}, \textbf{\meta{file2}}, etc., sont des chaînes de caractères constituées d’une lettre, par exemple \lstinline+"a"+.
820 \medskip
821
822 La commande suivante permet de supprimer l’ensemble des cases d’une ligne
823 déterminé par un nombre sur le plateau. Cette commande permet de prendre
824 une liste de lignes.
825
826 \commande|clear_ranks(«rank1»,«rank2»,etc.)|\index{clear_ranks@\lstinline+clear_ranks+}\smallskip
827
828 Les \textbf{\meta{rank1}}, \textbf{\meta{rank2}}, etc., sont des chaînes de caractères constituées d’un nombre, par exemple \lstinline+"4"+.
829
830 L’utilisation de l’ensemble des ces commandes est illustrée dans l’exemple suivant.
831
832 \begin{ExempleMP}
833 input mpchess
834 beginfig(0);
835 init_backboard;
836 draw backboard;
837 init_chessboard;
838 clear_squares("a1","b2");
839 clear_areas("c2-d7");
840 clear_files("f","h");
841 clear_ranks("8");
842 draw chessboard;
843 endfig;
844 \end{ExempleMP}
845
846
847
848 \subsection{Lecture de données au format \textsc{fen}}
849
850 \mpchess permet de lire une position au format \textsc{fen} grâce à la commande suivante.
851 \commande|build_chessboard_from_fen(«string»)|\index{build_chessboard_from_fen@\lstinline+build_chessboard_from_fen+}\smallskip
852
853 \begin{description}
854 \item[\meta{string}:] est une chaîne de caractères décrivant une position au
855 format \textsc{fen}. Notons que toutes les informations après l’information du
856 \emph{trait} (\texttt{w} ou \texttt{b}) sont ignorées.
857 \end{description}
858
859 \begin{ExempleMP}
860 input mpchess;
861 beginfig(0);
862 init_backboard;
863 draw backboard;
864 string fenstr;
865 fenstr := "7r/2p1kp1p/p1B2p2/1pb5/8/2PP4/PP1N1PPP/R5K1 b - - 2 19";
866 build_chessboard_from_fen(fenstr);
867 draw chessboard;
868 endfig;
869 \end{ExempleMP}
870
871 Il est aussi possible de lire un fichier externe contenant sur la première ligne
872 une chaîne de caractères au format \textsc{fen} avec la commande suivante.
873
874 \commande|build_chessboard_from_fen_file(«string»)|\index{build_chessboard_from_fen_file@\lstinline+build_chessboard_from_fen_file+}\smallskip
875
876 \begin{description}
877 \item[\meta{string}:] est une chaîne de caractères (entre double-quotes)
878 indiquant le nom du fichier à lire.
879 \end{description}
880
881 \begin{ExempleMP}
882 input mpchess;
883 beginfig(0);
884 init_backboard;
885 draw backboard;
886 build_chessboard_from_fen_file("test.fen");
887 draw chessboard;
888 endfig;
889 \end{ExempleMP}
890
891
892
893 \subsection{Lecture de données au format \textsc{pgn}}
894
895 \mpchess permet aussi de lire une chaîne de caractères au format \textsc{pgn}.
896 Attention, il s’agit d’une gestion partielle du format, en particulier
897 \mpchess ne gère pas les \emph{tags} du format. En réalité, \mpchess ne traite
898 que la chaîne de caractères décrivant les coups joués. De même, le format
899 \textsc{pgn} accepté par \mpchess n’accepte ni les variantes ni les
900 commentaires.
901
902 Lorsqu’une telle fonctionnalité est utilisé, \mpchess stocke toutes les
903 positions intermédiaires et permet ainsi de les représenter.
904
905 Pour construire les positions, on utilisera la commande suivante.
906
907 \commande|build_chessboards_from_pgn(«string»)|\index{build_chessboards_from_pgn@\lstinline+build_chessboards_from_pgn+}\smallskip
908
909
910
911 Une fois le positions construites, on pourra les représenter grâce à la commande suivante.
912
913 \commande|chessboard_step(«int»)|\index{chessboard_step@\lstinline+chessboard_step+}\smallskip
914 \begin{description}
915 \item[\meta{int}:] est le numéro du l’étape. La configuration initiale est numérotée 0, et ensuite, chaque coup, blanc ou noir, est numéroté.
916 \end{description}
917
918 Cette commande, comme \lstinline+chessboard+ (voir page~\pageref{com:chessboard}), retourne une \lstinline+picture+.
919
920 L’exemple suivant illustre l’utilisation de ces commandes.
921
922 \begin{ExempleMP}
923 input mpchess;
924 string pgnstr;
925 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
926 build_chessboards_from_pgn(pgnstr);
927 beginfig(0);
928 init_backboard;
929 draw backboard;
930 draw chessboard_step(3); % Nf3
931 endfig;
932 \end{ExempleMP}
933
934 Il est aussi possible de lire un fichier externe contenant sur la première ligne
935 une chaîne de caractères au format \textsc{pgn} avec la commande suivante.
936
937 \commande|build_chessboard_from_pgn_file(«string»)|\index{build_chessboard_from_pgn_file@\lstinline+build_chessboard_from_pgn_file+}\smallskip
938
939 \begin{description}
940 \item[\meta{string}:] est une chaîne de caractères (entre double-quotes)
941 indiquant le nom du fichier à lire.
942 \end{description}
943
944 \begin{ExempleMP}
945 input mpchess;
946 build_chessboards_from_pgn_file("test.pgn");
947 beginfig(0);
948 init_backboard;
949 draw backboard;
950 draw chessboard_step(4); % Nc6
951 endfig;
952 \end{ExempleMP}
953
954
955
956 \subsubsection{Montrer le dernier coup}
957
958 On peut afficher automatiquement le dernier coup grâce à la commande suivante.
959
960 \commande|show_last_move(«int»)|\index{show_last_move@\lstinline+show_last_move+}\smallskip
961
962 \begin{description}
963 \item[\meta{int}:] est le numéro du l’étape. La configuration initiale est numérotée 0, et ensuite, chaque coup, blanc ou noir, est numéroté.
964 \end{description}
965
966 Cette commande colorie en transparence les deux cases de départ et d’arrivée du dernier coup. Ainsi, elle doit être utilisée entre le dessin du plateau (\lstinline+draw backboard+) et le dessin des pièces (\lstinline+draw chessboard_step(i)+).
967
968 \begin{ExempleMP}
969 input mpchess;
970 string pgnstr;
971 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
972 build_chessboards_from_pgn(pgnstr);
973 beginfig(0);
974 init_backboard;
975 draw backboard;
976 show_last_move(3);
977 draw chessboard_step(3); % Nf3
978 endfig;
979 \end{ExempleMP}
980
981 On pourra configurer la couleur utilisée pour colorier en transparence les cases du dernier coup grâce à la commande suivante.
982
983 \commande|set_last_move_color(«color»)|\index{set_last_move_color@\lstinline+set_last_move_color+}\smallskip
984 \begin{description}
985 \item[\meta{color}:] est une \lstinline+color+ \MP.
986 \end{description}
987
988
989
990 \subsubsection{Obtenir le nombre de coups}
991
992 On pourra récupérer le nombre de \emph{demi}-coups grâce à la
993 commande suivante.
994
995 \commande|get_halfmove_number|\index{get_halfmove_number@\lstinline+get_halfmove_number+}\smallskip
996
997 Cette commande retourne un \lstinline+numeric+.
998
999 On pourra aussi récupérer le nombre de coups \og{}total\fg{} au sens où il sont numéroté dans le format \textsc{pgn}, grâce à la commande suivante :
1000
1001 \commande|get_totalmove_number|\index{get_totalmove_number@\lstinline+get_totalmove_number+}\smallskip
1002
1003 Cette commande retourne un \lstinline+numeric+.
1004
1005 \section{Annotation}
1006
1007 De nombreuses commandes permettent d’annoter l’échiquier (flèche, couleur, cercle, croix, etc.).
1008
1009 \subsection{Flèches}
1010
1011 La commande pour tracer des flèches sur l’échiquier est la suivante.
1012
1013 \commande|draw_arrows(«color»)(«string1»,«string2», etc.)|\index{draw_arrows@\lstinline+draw_arrows+}\smallskip
1014 \begin{description}
1015 \item[\meta{color}:] est une \lstinline+color+ \MP.
1016 \item[\meta{string1}:] est une chaîne de caractères (entre double-quotes) constituée de deux coordonnées (lettre et chiffre) séparés par deux caractères qui peuvent être
1017 \begin{description}
1018 \vitem+--+ pour relier les deux cases en ligne droite ;
1019 \vitem+-|+ pour relier les deux cases en ligne brisée, d’abord horizontalement puis verticalement ;
1020 \vitem+|-+ pour relier les deux cases en ligne brisée, d’abord verticalement puis horizontalement.
1021 \end{description}
1022 \end{description}
1023
1024 L’exemple suivant illustre l’utilisation de cette commande.
1025 \begin{ExempleMP}
1026 input mpchess;
1027 string pgnstr;
1028 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1029 build_chessboards_from_pgn(pgnstr);
1030 beginfig(0);
1031 init_backboard;
1032 draw backboard;
1033 show_last_move(3);
1034 draw chessboard_step(3); % Nf3
1035 draw_arrows(red)("f8--b4","g1|-f3");
1036 endfig;
1037 \end{ExempleMP}
1038
1039 On pourra modifier l’épaisseur des flèches grâce à la commande suivante.
1040 \commande|set_arrow_width(«coeff»)|\index{set_arrow_width@\lstinline+set_arrow_width+}\smallskip
1041
1042 \begin{description}
1043 \item[\meta{coeff}:] est un coefficient (\lstinline+numeric+) qui permet de
1044 régler la largeur des flèches proportionnellement à la largeur d’une case de
1045 l’échiquier. Par défaut, ce coefficient vaut \lstinline+0.08+.
1046 \end{description}
1047
1048 L’exemple suivant illustre l’utilisation de cette commande.
1049 \begin{ExempleMP}
1050 input mpchess;
1051 string pgnstr;
1052 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1053 build_chessboards_from_pgn(pgnstr);
1054 beginfig(0);
1055 set_black_view;
1056 init_backboard;
1057 draw backboard;
1058 show_last_move(3);
1059 draw chessboard_step(3); % Nf3
1060 set_arrow_width(0.12);
1061 draw_arrows(red)("f8--b4","g1|-f3");
1062 endfig;
1063 \end{ExempleMP}
1064
1065
1066 \subsection{Coloration de cases}
1067 \mpchess permet aussi de colorer des cases grâce à la commande suivante.
1068
1069 \commande|color_square(«color»)(«coord1»,«coord2», etc.)|\index{color_square@\lstinline+color_square+}\smallskip
1070
1071 \begin{description}
1072 \item[\meta{color}:] est une \lstinline+color+ \MP.
1073 \item[\meta{coord1}:] est une chaîne de caractères (entre double-quotes) constituée de deux coordonnées (lettre et chiffre).
1074 \end{description}
1075
1076 L’exemple suivant permet d’illustrer l’utilisation de cette commande.
1077
1078 \begin{ExempleMP}
1079 input mpchess
1080 beginfig(0);
1081 init_backboard;
1082 draw backboard;
1083 color_square(red)("e2","e7","c5");
1084 init_chessboard;
1085 draw chessboard;
1086 endfig;
1087 \end{ExempleMP}
1088
1089 Cette commande colorie les cases avec une certaine transparence pour s’adapter
1090 aux cases blanches et noires.
1091
1092 \subsection{Cercles}
1093 \mpchess permet d’entourer des cases avec des cercles grâce à la commande
1094 suivante.
1095 \commande|draw_circles(«color»)(«coord1»,«coord2», etc.)|\index{draw_circles@\lstinline+draw_circles+}\smallskip
1096
1097 \begin{description}
1098 \item[\meta{color}:] est une \lstinline+color+ \MP.
1099 \item[\meta{coord1}:] est une chaîne de caractères (entre double-quotes) constituée de deux coordonnées (lettre et chiffre).
1100 \end{description}
1101
1102 L’exemple suivant permet d’illustrer l’utilisation de cette commande.
1103
1104 \begin{ExempleMP}
1105 input mpchess
1106 beginfig(0);
1107 init_backboard;
1108 draw backboard;
1109 init_chessboard;
1110 draw chessboard;
1111 draw_circles(green)("e2","e7","c5");
1112 endfig;
1113 \end{ExempleMP}
1114
1115
1116
1117 \subsection{Croix}
1118
1119
1120 \mpchess permet de tracer des croix sur des cases grâce à la commande
1121 suivante.
1122 \commande|draw_crosses(«color»)(«coord1»,«coord2», etc.)|\index{draw_crosses@\lstinline+draw_crosses+}\smallskip
1123
1124 \begin{description}
1125 \item[\meta{color}:] est une \lstinline+color+ \MP.
1126 \item[\meta{coord1}:] est une chaîne de caractères (entre double-quotes) constituée de deux coordonnées (lettre et chiffre).
1127 \end{description}
1128
1129 L’exemple suivant permet d’illustrer l’utilisation de cette commande.
1130
1131 \begin{ExempleMP}
1132 input mpchess
1133 beginfig(0);
1134 init_backboard;
1135 draw backboard;
1136 init_chessboard;
1137 draw chessboard;
1138 draw_crosses(0.7[green,black])("e2","e7","c5");
1139 endfig;
1140 \end{ExempleMP}
1141
1142 \subsection{Commentaires de coup}
1143
1144 \mpchess permet d’afficher les classiques commentaires de coups du type
1145 \og{}!?\fg{} grâce à la commande suivante.
1146
1147 \commande|draw_comment(«str»,«pos»)|\index{draw_comment@\lstinline+draw_comment+}\smallskip
1148
1149 \begin{description}
1150 \item[\meta{str}:] est une chaîne de caractères (entre double-quotes) à
1151 afficher.
1152 \item[\meta{pos}:] est une chaîne de caractères (entre double-quotes) constituée
1153 d’une coordonnée (lettre et chiffre).
1154 \end{description}
1155
1156 \begin{ExempleMP}
1157 input mpchess;
1158 string pgnstr;
1159 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1160 build_chessboards_from_pgn(pgnstr);
1161 beginfig(0);
1162 init_backboard;
1163 draw backboard;
1164 show_last_move(3);
1165 draw chessboard_step(3); % Nf3
1166 draw_comment("?!","f3");
1167 endfig;
1168 \end{ExempleMP}
1169
1170
1171
1172
1173 La couleur des annotation de commentaires peut être changé grâce à la commande
1174 suivante.
1175 \commande|set_comment_color(«color»)|\index{set_comment_color@\lstinline+set_comment_color+}\smallskip
1176
1177 \subsection{Lignes principales}
1178
1179 \mpchess fournit une commande permettant d’afficher les flèches des coups des
1180 lignes principales d’analyses. Il y a les commandes pour les deux couleurs.
1181
1182 \commande|draw_white_main_lines(«move1»,«move2»,etc.)|\index{draw_white_main_lines@\lstinline+draw_white_main_lines+}\smallskip
1183
1184 \commande|draw_black_main_lines(«move1»,«move2»,etc.)|\index{draw_black_main_lines@\lstinline+draw_black_main_lines+}\smallskip
1185
1186 \begin{description}
1187 \item[\meta{move1}, \meta{move2}, etc.:] sont les coups à illustrer par une
1188 flèche, en suivant la notation de type \textsc{pgn}.
1189 \end{description}
1190 Lorsqu’on utilise la lecture de format \textsc{pgn} pour la construction des
1191 positions à afficher, on pourra alors utiliser les commandes suivantes
1192 permettant de spécifier quelle étape de la partie on commente.
1193
1194 \commande|draw_white_main_lines_step(«step»)(«move1»,«move2»,etc.)|\index{draw_white_main_lines_step@\lstinline+draw_white_main_lines_step+}\smallskip
1195
1196 \commande|draw_black_main_lines_step(«step»)(«move1»,«move2»,etc.)|\index{draw_black_main_lines_step@\lstinline+draw_black_main_lines_step+}\smallskip
1197
1198 \begin{description}
1199 \item[\meta{step}:] est l’étape de la partie qu’on souhaite annoter;
1200 \item[\meta{move1}, \meta{move2}, etc.:] sont les coups à illustrer par une
1201 flèche, en suivant la notation de type \textsc{pgn}.
1202 \end{description}
1203
1204 L’exemple suivant permet d’illustrer l’utilisation de cette commande.
1205
1206 \begin{ExempleMP}
1207 input mpchess
1208 string pgnstr;
1209 pgnstr:="1. e4 d5";
1210 build_chessboards_from_pgn(pgnstr);
1211 beginfig(0);
1212 init_backboard;
1213 draw backboard;
1214 draw chessboard_step(2);
1215 draw_white_main_lines_step(2)("exd5","e5","Nc3");
1216 endfig;
1217 \end{ExempleMP}
1218
1219 Pour changer la couleur (par défaut \lstinline+0.3[_blackColorSquare,black]+),
1220 on utilisera la commande suivante.
1221
1222 \commande|set_main_lines_color(«color»)|\index{set_main_lines_color@\lstinline+set_main_lines_color+}\smallskip
1223
1224 \subsection{Mouvements possibles}\label{sec:possiblemoves}
1225
1226 \mpchess permet, à la manière du site \href{Lichess.org}{https://lichess.org},
1227 de montrer les mouvements possibles pour une pièce. Pour cela, on utilisera la
1228 commande suivante.
1229
1230 \commande|show_possible_moves(«square»)|\index{show_possible_moves@\lstinline+show_possible_moves+}\smallskip
1231
1232 \begin{description}
1233 \item[\meta{square}:] est une chaîne de caractères indiquant au format classique
1234 les coordonnées de la case où la pièce se situe.
1235 \end{description}
1236
1237 Cette commande doit être utilisée après avoir tracé le \lstinline+chessboard+.
1238
1239 \begin{ExempleMP}
1240 input mpchess
1241 string fenstr;
1242 fenstr:="7r/2p1kp1p/p1B2p2/1pb5/8/2PP4/PP1N1PPP/R5K1 b - - 2 19";
1243 build_chessboard_from_fen(fenstr);
1244 beginfig(0);
1245 set_black_view;
1246 init_backboard;
1247 draw backboard;
1248 draw chessboard;
1249 show_possible_moves("c5");
1250 endfig;
1251 \end{ExempleMP}
1252
1253 Dans le cas où plusieurs positions ont été construites avec le format
1254 \textsc{pgn}, on utilisera la commande suivante pour acceder à la position
1255 choisie.
1256
1257 \commande|show_possible_moves_step(«step»)(«square»)|\index{show_possible_moves_step@\lstinline+show_possible_moves_step+}\smallskip
1258
1259 \begin{description}
1260 \item[\meta{step}:] est l’étape de la partie qu’on souhaite annoter;
1261 \item[\meta{square}:] est une chaîne de caractères indiquant au format classique
1262 les coordonnées de la case où la pièce se situe.
1263 \end{description}
1264
1265 Par défaut, la couleur est réglée à \lstinline+0.4[green,black]+, mais celle-ci
1266 peut-être modifiée avec la commande suivante.
1267
1268 \commande|set_possible_moves_color(«color»)|\index{set_possible_moves_color@\lstinline+set_possible_moves_color+}\smallskip
1269
1270
1271 \section{Divers}
1272
1273 \subsection{Réinitialisation du \lstinline+chessboard+}
1274
1275 Pour réinitialiser la structure interne stockant les positions des pièces, on
1276 pourra utiliser la commande suivante.
1277
1278 \commande|clear_chessboard|\index{clear_chessboard@\lstinline+clear_chessboard+}\smallskip
1279
1280
1281 \subsection{Réinitialisation globale}
1282
1283 Pour réinitialiser les valeurs des différents paramètres de \mpchess, on pourra
1284 utiliser la commande suivante.
1285
1286 \commande|reset_mpchess|\index{reset_mpchess@\lstinline+reset_mpchess+}\smallskip
1287
1288
1289 \subsection{Découpe de l’échiquier}
1290
1291 On pourra faire une découpe dans l’image de l’échiquier grâce à la commande suivante.
1292
1293 \commande|clip_chessboard(«string»)|\index{clip_chessboard@\lstinline+clip_chessboard+}\smallskip
1294
1295
1296 \begin{description}
1297 \item[\meta{string}:] est une chaîne de caractères (entre double-quotes)
1298 composée de deux coordonnées (lettre et chiffre) séparées par un tiret, par
1299 exemple \lstinline+"a1-c6"+.
1300 \end{description}
1301
1302 Voici un exemple d’illustration.
1303 \begin{ExempleMP}
1304 input mpchess;
1305 string pgnstr;
1306 pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
1307 build_chessboards_from_pgn(pgnstr);
1308 beginfig(0);
1309 set_black_view;
1310 init_backboard;
1311 draw backboard;
1312 show_last_move(3);
1313 draw chessboard_step(3); % Nf3
1314 draw_comment("?!","f3");
1315 clip_chessboard("e1-g4");
1316 endfig;
1317 \end{ExempleMP}
1318
1319
1320
1321
1322 \section{Utilisation avec \LaTeX{}}
1323
1324 \subsection{Utilisation avec \hologo{pdfLaTeX} ou \hologo{XeLaTeX}}
1325
1326 Il existe plusieurs façons d’inclure les images produites par \mpchess dans un
1327 document \LaTeX. La première est de générer des fichiers \pdf{} avec \MP{} puis
1328 de les inclure avec \lstinline[language=TeX]+\includegraphics+. Cette
1329 solution fonctionne avec tous les moteurs.
1330
1331 On pourra aussi utiliser les packages \package{gmp} ou \package{mpgraphics}
1332 avec \hologo{pdfLaTeX} ou \hologo{XeLaTeX}\footnote{Nous tenons à remercier
1333 Quark67 pour les questions et les conseils.}.
1334
1335 \subsubsection{Avec \package{mpgraphics}}
1336
1337 Avec \package{mpgraphics}~\cite{ctan-mpgraphics}, on chargera \mpchess avec
1338 l’environnement \lstinline+mpdefs+ et on pourra produire des images grâce à du
1339 code \MP{} mais sans avoir recours à \lstinline+beginfig+ et \lstinline+endfig+,
1340 le code pour générer une figure \MP{} se trouvant dans l’environnement
1341 \lstinline+mpdisplay+. Il faudra de plus utiliser l’option
1342 \lstinline+-shell-escape+ à la compilation du document \LaTeX.
1343
1344 Voici un exemple complet d’illustration.
1345
1346 \begin{latexcode}
1347 \documentclass{article}
1348 \usepackage{mpgraphics}
1349 \begin{document}
1350 \begin{mpdefs}
1351 input mpchess
1352 \end{mpdefs}
1353 \begin{mpdisplay}
1354 init_backboard;
1355 draw backboard;
1356 init_chessboard;
1357 draw chessboard;
1358 draw_arrows(red)("e7--e5","g1|-f3");
1359 \end{mpdisplay}
1360 \end{document}
1361 \end{latexcode}
1362
1363 \subsubsection{Avec \package{gmp}}
1364
1365 L’utilisation de \package{gmp}~\cite{ctan-gmp} est assez similaire à celle de
1366 \package{mpgraphics}. Quelques commandes sont toutefois différentes, mais comme
1367 avec \package{mpgraphics}, on n’aura pas recours à \lstinline+beginfig+ et
1368 \lstinline+endfig+. Le chargement de \mpchess peut se faire au chargement du
1369 package, et le code \MP{} se trouve dans l’environnement \lstinline+mpost+. Là
1370 encore il faudra compiler le document \LaTeX{} avec l’option \lstinline+-shell-escape+.
1371
1372 Voici un exemple complet d’illustration.
1373
1374 \begin{latexcode}
1375 \documentclass{article}
1376 \usepackage[shellescape, everymp={input mpchess;}]{gmp}
1377
1378 \begin{document}
1379
1380 \begin{mpost}
1381 init_backboard;
1382 draw backboard;
1383 init_chessboard;
1384 draw chessboard;
1385 draw_arrows(red)("e7--e5","g1|-f3");
1386 \end{mpost}
1387 \end{document}
1388 \end{latexcode}
1389
1390 \subsection{Utilisation avec \hologo{LuaLaTeX} et \package{luamplib}}
1391
1392 Il est tout à fait possible d’utiliser \mpchess directement dans un fichier
1393 \LaTeX{} avec \hologo{LuaLaTeX}\footnote{Rappelons que \MP{} fait partie
1394 intégrante de \hologo{LuaTeX}.} et le package \package{luamplib}. C’est
1395 d’ailleurs ce qui est fait pour écrire cette documentation.
1396
1397 Il suffira alors de mettre le code \MP{} dans l’environnement
1398 \lstinline+mplibcode+ comme illustré plus bas.
1399
1400
1401 \mpchess utilise, pour certaines fonctionnalités, l’opérateur
1402 \lstinline+infont+ de \MP. Ainsi, pour que le contenu de ces fonctionnalités
1403 soit composé dans la fonte courante du document, on devra ajouter dans son
1404 document
1405 \LaTeX{}, la commande :
1406 \begin{latexcode}
1407 \mplibtextextlabel{enable}
1408 \end{latexcode}
1409
1410 Pour plus de détails sur ces mécanismes, nous renvoyons à la documentation du
1411 package \package{luamplib}~\cite{ctan-luamplib}.
1412
1413 On pourra charger globaletement \mpchess avec la commande suivante.
1414
1415 \begin{latexcode}
1416 \everymplib{input mpchess;}
1417 \end{latexcode}
1418
1419 Voici un exemple complet d’illustration (à compiler avec \hologo{LuaLaTeX}).
1420
1421 \begin{latexcode}
1422 \documentclass{article}
1423 \usepackage{luamplib}
1424
1425 \everymplib{input mpchess;}
1426
1427 \begin{document}
1428
1429 \begin{mplibcode}
1430 beginfig(0);
1431 init_backboard;
1432 draw backboard;
1433 init_chessboard;
1434 draw chessboard;
1435 draw_arrows(red)("e7--e5","g1|-f3");
1436 endfig;
1437 \end{mplibcode}
1438 \end{document}
1439 \end{latexcode}
1440
1441 \subsection{Font TrueType}
1442
1443 Le package \mpchess{} fournit une fonte très simple composé d’uniquement les 12
1444 glyphes correspondant aux pièces noires et blanches dans la table Unicode. Pour
1445 y avoir accès il suffit d’utiliser \hologo{LuaLaTeX} ou \hologo{XeLaTeX} et le
1446 package \package{fontspec}. Pour faciliter son utilisation, nous proposons
1447 quelques définitions.
1448
1449 \begin{latexcode}
1450 \documentclass{article}
1451 \usepackage{fontspec}
1452 \newfontfamily{\chessfont}{mpchess font}
1453 \newcommand\bP{{\chessfont \char"265F}} % black Pawn
1454 \newcommand\bN{{\chessfont \char"265E}} % black Knight
1455 \newcommand\bB{{\chessfont \char"265D}} % black Bishop
1456 \newcommand\bR{{\chessfont \char"265C}} % black Rook
1457 \newcommand\bQ{{\chessfont \char"265B}} % black Queen
1458 \newcommand\bK{{\chessfont \char"265A}} % black King
1459 \newcommand\wP{{\chessfont \char"2659}} % white Pawn
1460 \newcommand\wN{{\chessfont \char"2658}} % white Knight
1461 \newcommand\wB{{\chessfont \char"2657}} % white Bishop
1462 \newcommand\wR{{\chessfont \char"2656}} % white Rook
1463 \newcommand\wQ{{\chessfont \char"2655}} % white Queen
1464 \newcommand\wK{{\chessfont \char"2654}} % white King
1465
1466 \begin{document}
1467
1468 Voici l'enchainement de coups : 1. e4 e5 2. \wB c4 d6 3. \wN f3 \bB g4 4. \wN
1469 c3 g6 5. \wN xe5 \bB xd1.
1470
1471 \end{document}
1472 \end{latexcode}
1473
1474 Qui produira :
1475
1476 \og{}Voici l’enchainement de coups : 1. e4 e5 2. \wB c4 d6 3. \wN f3 \bB g4
1477 4. \wN c3 g6 5. \wN xe5 \bB xd1.\fg{}
1478
1479
1480
1481 \section{To do}
1482
1483 De nombreuses choses sont à ajouter à \mpchess. Parmi celles-ci, on peut penser
1484 à :
1485
1486 \begin{itemize}
1487 \item afficher les pièces capturées, ou le différentiel des pièces capturées ;
1488 \item afficher le temps restant pour chaque joueur ;
1489 \item parser le format \textsc{pgn} complet et donc avec les tags optionnels ;
1490 \item ajouter les coordonnées en extérieur lorsque le plateau est découpé ;
1491 \item ajouter des thèmes de pièces.
1492 \end{itemize}
1493
1494 \section{Un exemple complet}
1495
1496 \begin{ExempleMP}[sidebyside=false]
1497 input mpchess
1498 string pgnstr;
1499 pgnstr:="1. e4 e5 2. Bc4 d6 3. Nf3 Bg4 4. Nc3 g6 5. Nxe5 Bxd1";
1500 build_chessboards_from_pgn(pgnstr);
1501 beginfig(0);
1502 set_backboard_width(8cm);
1503 set_white_player("Kermur de Legal");
1504 set_black_player("Saint-Brie");
1505 init_backboard;
1506 draw backboard;
1507 show_last_move(10);
1508 draw_comment("?","d1");
1509 color_square(0.3[green,black])("c4","c3","e5");
1510 color_square(0.3[red,black])("e8");
1511 draw chessboard_step(10);
1512 draw_arrows(0.3[green,black])("e5|-f7","c3-|d5");
1513 draw_arrows(0.3[red,black])("c4--f7");
1514 endfig;
1515 \end{ExempleMP}
1516
1517 \section{Historique}
1518
1519 \begin{description}
1520 \item[v0.9, 16 décembre 2024:] Correction d’un bug de placement de la marque
1521 de trait (par Udi Fogiel), ajout de différents marqueur de traits (\lstinline"triangle",
1522 \lstinline"square",\lstinline"disk" and \lstinline"custom"). Colloriage du
1523 marqueur blanc.
1524 \item[v0.8, 26 octobre 2024:] Ajout du thème d’échiquier \lstinline+"Dotted"+
1525 et ajout du thème d’échiquier \lstinline+"User"+ qui permet à l’utilisateur ou
1526 l’utilisatrice de définir les casses blanches et noires.
1527 \item[v0.7, juillet 2023:] Ajustement du cavalier noir, ajout de thèmes
1528 d'échiquier (\lstinline+GreenLichess+, \lstinline+PinkPyramidalLichess+,
1529 \lstinline+Wood+ avec des types de coloriage (\lstinline+set_board_type+).
1530 \item[v0.6, avril 2023:] Corrections de bugs concernant la gestion des roques, et
1531 des ambiguïtés de pièces pour les déplacements sous format \textsc{pgn}.
1532 Changement de \lstinline+set_white_color+ en
1533 \lstinline+set_white_squares_color+ et \lstinline+set_black_color+ en
1534 \lstinline+set_black_squares_color+. Changement de \lstinline+set_no_coords+ en
1535 \lstinline+hide_coordinates+ et \lstinline+set_coords+ en
1536 \lstinline+show_coordinates+. Changement de \lstinline+set_whos_to_move+ en
1537 \lstinline+show_whos_to_move+ et \lstinline+unset_whos_to_move+ en
1538 \lstinline+hide_whos_to_move+. Changement de \lstinline+set_coords_inside+ et
1539 \lstinline+set_coords_outside+ en \lstinline+set_coordinates_position+.
1540 Changement de \lstinline+set_coords_font+ en \lstinline+set_coordinates_font+.
1541 \item[v0.5, 20 avril 2023:] Correction d’un bug, \textbf{changement de
1542 l’ensemble de pièce par défaut} pour l’ensemble \lstinline+mpchess+ (qui a été
1543 ajouté à Lichess), ajout de la fonte TrueType, et mise à jour de la documentation.
1544 \item[v0.4, 6 avril 2023:] Corrections dans la documentation, notamment la
1545 version anglaise; ajout des commandes pour visualiser les mouvements possible
1546 pour une pièce (section~\ref{sec:possiblemoves}).
1547 \item[v0.3, 29 mars 2023 :] Petit bug.
1548 \item[v0.2, 28 mars 2023 :] Ajout des commandes de lecture de fichiers
1549 \textsc{pgn} et \textsc{fen}; ajout des commandes d’affichage des lignes
1550 principales d’analyse; suppression du thème \lstinline+staunty+ (pour cause de
1551 licence) et création du thème de pièces \lstinline+mpchess+.
1552 \item[v0.1, 23 mars 2023 :] Première publication sur le \ctan.
1553 \end{description}
1554
1555
1556 \section{Remerciements}
1557 Nous souhaitons remercier Quark67 pour ses retours et ses corrections, Douglas
1558 Johnson pour avoir corrigé la version anglaise de la documentation et Hans
1559 Nieuwenhuis pour ses conseils.
1560 Ces retours et encouragements font extrêmement plaisir !
1561
1562
1563 \printbibliography
1564 \printindex
1565 \end{document}
1566
1567
1568
1569 %%% Local Variables:
1570 %%% flyspell-mode: 1
1571 %%% ispell-local-dictionary: "fr"
1572 %%% End: