summaryrefslogtreecommitdiff
path: root/graphics/metapost/contrib/macros/mpchess/doc/mpchess-doc-en.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/metapost/contrib/macros/mpchess/doc/mpchess-doc-en.tex')
-rw-r--r--graphics/metapost/contrib/macros/mpchess/doc/mpchess-doc-en.tex1224
1 files changed, 1224 insertions, 0 deletions
diff --git a/graphics/metapost/contrib/macros/mpchess/doc/mpchess-doc-en.tex b/graphics/metapost/contrib/macros/mpchess/doc/mpchess-doc-en.tex
new file mode 100644
index 0000000000..fdf595c199
--- /dev/null
+++ b/graphics/metapost/contrib/macros/mpchess/doc/mpchess-doc-en.tex
@@ -0,0 +1,1224 @@
+
+% LTeX: language=en
+
+% mpchess: draw chess boards and positions with MetaPost
+%
+% Originally written by Maxime Chupin <notezik@gmail.com>,
+% 2023.
+%
+% Distributed under the terms of the GNU free documentation licence:
+% http://www.gnu.org/licenses/fdl.html
+% without any invariant section or cover text.
+
+\documentclass[english]{ltxdoc}
+\usepackage{tcolorbox}
+\tcbuselibrary{listings,breakable}
+%\tcbuselibrary{documentation}
+\usepackage{enumitem}
+\usepackage[tikz]{bclogo}
+\usepackage{mflogo}
+\usepackage{hologo}
+\usepackage{luamplib}
+\mplibtextextlabel{enable}
+\usepackage{biblatex}
+\addbibresource{ctan.bib}
+\usepackage{wrapfig}
+\usepackage{siunitx}
+\usepackage{imakeidx}
+\usepackage{fancyvrb,xparse,xargs}
+\usepackage[sfdefault]{FiraSans}
+\usepackage[mathrm=sym]{firamath-otf}
+%\setmonofont{Fira Mono}
+\setmonofont{FiraCode-Regular.ttf}[BoldFont= FiraCode-Bold.ttf,ItalicFont= FiraCode-RegularItalic.otf,BoldItalicFont= FiraCode-BoldItalic.otf,]
+
+\usepackage{xspace}
+\usepackage{animate}
+\usepackage[english]{babel}
+\newcommand{\ctan}{\textsc{ctan}}
+\NewDocumentCommand{\package}{ m }{%
+ \href{https://ctan.org/pkg/#1}{#1}\xspace
+}
+
+\definecolor{darkred}{rgb}{0.6,0.1,0.1}
+\definecolor{vert}{rgb}{0.1,0.4,0.1}
+\definecolor{bleu}{rgb}{0.2,0.2,0.6}
+\definecolor{orange}{rgb}{0.6,0.4,0.}
+\colorlet{code}{blue!80!black}
+
+\usepackage[colorlinks=true,urlcolor=orange,linkcolor=orange,menucolor=black,citecolor=orange]{hyperref}
+
+\newcommand \file {\nolinkurl}
+\renewcommand \cmd {\texttt}
+\renewcommand \code [1] {\texorpdfstring {\texttt{\color{code}#1}} {#1}}
+\renewcommand*\cs [1] {\code{\textbackslash #1}}
+
+
+
+\newcommand*\commande{\par\bigskip\noindent\hspace{-30pt}%
+ \SaveVerb[aftersave={%
+ \UseVerb{Vitem}%
+ }%
+ ]{Vitem}%
+ }
+ \newcommand\vitem[1][]{\SaveVerb[%
+ aftersave={\item[\textnormal{\UseVerb[#1]{vsave}}]}]{vsave}}
+\newcommand*\textme[1]{\textcolor{black}{\rmfamily\textit{#1}}}
+%\renewcommand*\meta[1]{% % meta
+% \textme{\ensuremath{\langle}#1\ensuremath{\rangle}}}
+\newcommand*\optstar{% % optional star
+ \meta{\ensuremath{*}}\xspace}
+\DefineShortVerb{\|}
+\newcommand\R{\mathbf{R}}
+\setlength{\fboxsep}{2pt}
+\fvset{%
+ codes={\catcode`\«\active \catcode`\×\active },
+ defineactive={\makefancyog\makefancytimes},
+ formatcom=\color{darkred},
+ frame=single
+}
+% rendre «...» équivalent à \meta{...}
+{\catcode`\«\active
+ \newcommandx\makefancyog[0][addprefix=\global]{%
+ \def«##1»{\meta{##1}}}}
+% rendre × équivalent à \optstar
+{\catcode`\×\active
+ \newcommandx\makefancytimes[0][addprefix=\global]{%
+ \def×{\optstar{}}}}
+
+
+\newcommand\mpchess{\textbf{\textlogo{MP}}\textit{chess}\xspace}
+
+
+
+%\addbibresource{biblio.bib}
+
+
+\lstset{
+ numberstyle=\footnotesize\color{vert},
+ keywordstyle=\ttfamily\bfseries\color{bleu},
+ basicstyle=\ttfamily,
+ commentstyle=\itshape\color{vert},
+ stringstyle=\ttfamily\color{orange},
+ showstringspaces=false,
+ language=MetaPost,
+ breaklines=true,
+ breakindent=30pt,
+ defaultdialect=MetaPost,
+ classoffset=1,% frame=tb
+ morekeywords={init_backboard,set_backboard_width,set_backboard_size,set_color_theme,get_backboard_width,get_backboard_size,set_backboard_width,get_square_dim,set_white_color,set_black_color,set_coords_inside,set_coords_outside,set_coords_font,set_coords,
+ set_no_coords,set_white_view,set_black_view,
+ set_white_player,set_black_player,set_pieces_theme,set_players_side,init_chessboard,set_empty_chessboard,add_white_pieces,add_black_pieces,clear_areas,clear_files,clear_ranks,clear_squares,build_chessboard_from_fen,build_chessboards_from_pgn,clear_chessboard,
+ color_square,draw_arrows,draw_circles,draw_comment,draw_crosses,get_halfmove_number,get_totalmove_number,
+ reset_mpchess,set_black_to_move,set_last_move_color,set_comment_color,set_white_to_move,set_whos_to_move,show_last_move,unset_whos_to_move,set_arrow_width,clip_chessboard},
+ keywordstyle=\color{darkred},
+ classoffset=2,% frame=tb
+ morekeywords={backboard,chessboard,chessboard_step},
+ keywordstyle=\color{vert},
+ classoffset=0,% frame=tb
+ morekeywords={draw},
+ keywordstyle=\color{bleu}
+}
+
+\makeatletter
+\tcbset{%
+ listing metapost/.code={%
+ \def\tcbuselistingtext@input{\begin{mplibcode} input \jobname.listing; \end{mplibcode}}%
+ }
+}
+\makeatother
+\newtcblisting[auto counter,]{ExempleMP}[1][]{%
+ arc=0pt,outer arc=0pt,
+ colback=darkred!3,
+ colframe=darkred,
+ breakable,fontupper=\small,
+ boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
+ 3pt, toptitle=3pt,
+ boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
+ 0pt, bottomrule at break = 0pt,
+ listing side text,
+ listing metapost,
+ title=Exemple~\thetcbcounter,
+ listing options={breaklines},#1
+}
+
+\newtcblisting{commandshell}{colback=black,colupper=white,colframe=black,
+ arc=0pt,
+ listing only,boxsep=0pt,listing
+ options={style=tcblatex,language=sh},
+ every listing line={\textcolor{red}{\small\ttfamily\bfseries user \$> }}}
+
+
+ \newtcblisting{mpcode}{
+ arc=0pt,outer arc=0pt,
+ colback=darkred!3,
+ colframe=darkred,
+ breakable,
+ boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
+ 3pt, toptitle=3pt,
+ boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
+ 0pt, bottomrule at break = 0pt,
+ listing only,boxsep=0pt,listing
+ options={breaklines}
+}
+
+\newtcblisting{latexcode}{
+ arc=0pt,outer arc=0pt,
+ colback=darkred!3,
+ colframe=darkred,
+ breakable,
+ boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
+ 3pt, toptitle=3pt,
+ boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
+ 0pt, bottomrule at break = 0pt,
+ listing only,boxsep=0pt,listing
+ options={breaklines,language={[LaTeX]TeX}}
+}
+
+
+\makeindex[title=Command Index, columns=2]
+
+
+
+%\lstset{moredelim=*[s][\color{red}\rmfamily\itshape]{<}{>}}
+%\lstset{moredelim=*[s][\color{blue}\rmfamily\itshape]{<<}{>>}}
+
+\begin{document}
+
+\title{{MPchess} : drawing chess boards and positions with \hologo{METAPOST}}
+\author{Maxime Chupin, \url{notezik@gmail.com}}
+\date{\today}
+
+%% === Page de garde ===================================================
+\thispagestyle{empty}
+\begin{tikzpicture}[remember picture, overlay]
+ \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
+ \includegraphics{fond.pdf}%
+ };
+\end{tikzpicture}%
+
+\noindent
+{\Huge \mpchess}\par\medskip
+\noindent
+{\Large drawing chess boards and positions with \hologo{METAPOST}}\\[1cm]
+\parbox{0.6\textwidth}{
+ \begin{mplibcode}
+ input mpchess
+ string pgnstr;
+ pgnstr:="1. e4 e5 2. Bc4 d6 3. Nf3 Bg4 4. Nc3 g6 5. Nxe5 Bxd1 ";
+ build_chessboards_from_pgn(pgnstr);
+ beginfig(0);
+ set_backboard_width(8cm);
+ init_backboard;
+ draw backboard;
+ show_last_move(10);
+ draw_comment("?","d1");
+ color_square(0.3[green,black])("c4","c3","e5");
+ color_square(0.3[red,black])("e8");
+ draw chessboard_step(10);
+ draw_arrows(0.3[green,black])("e5|-f7","c3-|d5");
+ draw_arrows(0.3[red,black])("c4--f7");
+ endfig;
+ \end{mplibcode}
+}\hfill
+\parbox{0.5\textwidth}{\Large\raggedleft
+ \textbf{Contributor}\\
+ Maxime \textsc{Chupin}\\
+ \url{notezik@gmail.com}
+}
+\vfill
+\begin{center}
+ Version 0.1, 2023, March, 23th \\
+ \url{https://plmlab.math.cnrs.fr/mchupin/mpchess}
+\end{center}
+%% == Page de garde ====================================================
+\newpage
+
+%\maketitle
+
+\begin{abstract}
+ This package allows you to draw chess boards and positions.
+ The appearance of the drawings is modern and largely inspired by what is offered by
+ the excellent web site \url{Lichess.org}.
+ Relying on \MP{} probably allows more graphic flexibility than the
+ excellent \LaTeX{} packages.
+\end{abstract}
+
+
+\begin{center}
+ \url{https://plmlab.math.cnrs.fr/mchupin/mpchess}
+\end{center}
+
+\tableofcontents
+
+\bigskip
+
+\begin{tcolorbox}[ arc=0pt,outer arc=0pt,
+ colback=darkred!3,
+ colframe=darkred,
+ breakable,
+ boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
+ 3pt, toptitle=3pt,
+ boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
+ 0pt, bottomrule at break = 0pt,]
+ \itshape
+ This package is in beta version, do not hesitate to report bugs, as well as requests for improvement.
+\end{tcolorbox}
+
+\section{Installation}
+
+\mpchess is on the \ctan{} and can be installed via the package manager of your
+distribution.
+
+\begin{center}
+ \url{https://www.ctan.org/pkg/mpchess}
+\end{center}
+
+
+\subsection{With \TeX live under Linux or MacOS}
+
+To install \mpchess with \TeX live, you will have to create the directory
+\lstinline+texmf+ directory in your \lstinline+home+.
+
+\begin{commandshell}
+mkdir ~/texmf
+\end{commandshell}
+
+Then, you will have to place the \lstinline+.mp+ files in the
+\begin{center}
+ \lstinline+~/texmf/tex/metapost/mpchess/+
+\end{center}
+
+\mpchess consists of 7 files \hologo{METAPOST} :
+\begin{itemize}
+ \item \verb+mpchess.mp+;
+ \item \verb+mpchess-chessboard.mp+;
+ \item \verb+mpchess-pgn.mp+;
+ \item \verb+mpchess-fen.mp+;
+ \item \verb+mpchess-cburnett.mp+;
+ \item \verb+mpchess-staunty.mp+;
+ \item \verb+mpchess-skak.mp+.
+\end{itemize}
+
+Once this is done, \mpchess will be loaded with the classic
+\begin{mpcode}
+input mpchess
+\end{mpcode}
+
+\subsection{With Mik\TeX{} and Windows}
+
+These two systems are unknown to the author of \mpchess, so we refer to their documentation to add local packages:
+\begin{center}
+ \url{http://docs.miktex.org/manual/localadditions.html}
+\end{center}
+
+
+
+\subsection{Dependencies}
+
+
+\mpchess depends on the packages \MP: \package{hatching} and, if
+\mpchess is not used with \hologo{LuaLaTeX} and \package{luamplib},
+\package{latexmp}.
+
+\subsection{Use with \hologo{LuaLaTeX} and \package{luamplib}}
+
+It is possible to use \mpchess directly in a \LaTeX{} file with
+\hologo{LuaLaTeX} and the package \package{luamplib}. This is what is done to
+write this documentation.
+
+For certain functionalities, \mpchess uses the \MP{} operator
+\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 :
+\begin{latexcode}
+\mplibtextextlabel{enable}
+\end{latexcode}
+
+For more details on these mechanisms, we refer to the documentation of the
+package \package{luamplib}~\cite{ctan-luamplib}.
+
+\section{Why this package and general philosophy}
+
+There are already \LaTeX{} packages for drawing chess boards and positions,
+including the very good \package{xskak}~\cite{ctan-xskak}coupled with the
+package \package{chessboard}~\cite{ctan-chessboard}.
+Ulrike Fisher has done there improvement, maintenance work, and provided us with
+excellent tools to make chess diagrams and to handle the different formats of
+game descriptions\footnote{She even developed the
+package to handle various chess fonts.}. The
+documentations of these packages are very good.
+
+Several things motivated the creation of \mpchess. First of all, with
+\package{chessboard} the addition of a set of pieces is not very easy, because
+it relies on fonts. Moreover, I find that drawing chess game diagrams is
+something diagrams is a very graphical thing, and that using a dedicated drawing
+language offers more flexibility and what better than \MP~\cite{ctan-metapost}.
+
+With \mpchess, we build the final image of the chess board with the pieces
+by successive layers. Thus, we begin by producing and drawing the board
+(\lstinline+backboard+), which we can modify by coloring some squares for
+example, then we will add the pieces of the position (\lstinline+chessboard+),
+and finally, we can annotate the whole with marks, colors, arrows, etc.
+
+
+
+Moreover, \mpchess produces images that are graphically close to what can be
+provided by excellent \emph{open source} website \url{https://lichess.org}. You
+will see that the colors, the pieces and the general aspect are largely inspired
+of what this website offers.
+
+\section{Board}
+
+The board is called with \mpchess{} \lstinline+backboard+.
+You have to initialize the board before drawing it. This is done with the
+following command:\par
+
+\commande|init_backboard|\smallskip\index{init_backboard@\lstinline+init_backboard+}
+
+This command constructs a \MP{} \lstinline+picture+ named
+\mbox{\lstinline+backboard+.} It should then be drawn as illustrated in the following example.
+\begin{ExempleMP}
+input mpchess
+
+beginfig(0);
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+
+This initialization will make it possible to take into account the various options and features that we will describe in the following.
+
+\subsection{Setting the size}
+
+When creating the \lstinline+backboard+, you can decide on the width of it. This is done with the following command:\par\bigskip
+
+\commande|set_backboard_width(«dim»)|\smallskip\index{set_backboard_width@\lstinline+set_backboard_width+}
+
+\begin{description}
+ \item[\meta{dim}:] is the width of the board (with units). By default, this dimension is \SI{5}{cm}.
+\end{description}
+
+The use of this command is illustrated in the example~\ref{ex:widthcase}. This
+command should be used before \lstinline+init_backboard+ so that it is taken
+into account when creating the \lstinline+picture+.
+\bigskip
+
+The size of the board can be retrieved with the following command:
+
+\commande|get_backboard_width|\smallskip\index{get_backboard_width@\lstinline+get_backboard_width+}
+
+This command returns a \lstinline+numeric+.
+
+\subsection{Number of squares}
+
+By default, the game board contains 64 squares ($8\times 8$). You can change
+this with the following command:
+\commande|set_backboard_size(«nbr»)|
+\smallskip\index{set_backboard_size@\lstinline+set_backboard_size+}
+
+\begin{description}
+ \item[\meta{nbr}:] is the desired number of squares. The board will then be
+ square of size \meta{nbr}$\times$\meta{nbr}. By default this number is 8.
+\end{description}
+
+Again, this command must be used before \lstinline+init_backboard+ for it to be
+taken into account as shown in the following example.
+
+\begin{ExempleMP}[label=ex:widthcase]
+input mpchess
+
+beginfig(0);
+set_backboard_width(3cm);
+set_backboard_size(6);
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+
+To obtain the size of the game board, you can use the following command the
+following command
+
+\commande|get_backboard_size|\smallskip\index{get_backboard_size@\lstinline+get_backboard_size+}
+
+This command returns a \lstinline+numeric+.
+
+\subsection{Dimension of a square}
+
+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
+serves as a general unit. To obtain it, use the following command.
+
+\commande|get_square_dim|\smallskip\index{get_square_dim@\lstinline+get_square_dim+}
+
+This command returns a \lstinline+numeric+.
+
+\subsection{Setting the color theme}
+
+\subsubsection{Predefined themes}
+
+Several color themes are available. To choose a color theme, use the following
+command:
+
+\commande|set_color_theme(«string»)|\smallskip\index{set_color_theme@\lstinline+set_color_theme+}
+
+\begin{description}
+ \item[\meta{string}] can be:
+\begin{itemize}
+\item \lstinline+"BlueLichess"+ (thème par défaut);
+\item \lstinline+"BrownLichess"+ ;
+\item or \lstinline+"Classical"+.
+\end{itemize}
+\end{description}
+
+The following examples show the results obtained.
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+set_color_theme("BrownLichess");
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+set_color_theme("Classical");
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+
+The two color themes provided borrow the colors of the Lichess themes.
+
+
+\subsubsection{Configuration of a personal theme}
+
+A color theme is really just the definition of two colors.
+These can be defined with the following commands.
+
+\commande|set_white_color(«color»)|\index{set_white_color@\lstinline+set_white_color+}\par
+\commande|set_black_color(«color»)|\index{set_black_color@\lstinline+set_black_color+}\smallskip
+
+\meta{color} is a \MP{} \lstinline+color+.
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+set_white_color((0.9,0.8,0.8));
+set_black_color((0.7,0.6,0.6));
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+\subsection{Display coordinates}
+
+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.
+
+\mpchess allows to position these coordinates outside the board with the
+following command.
+
+\commande|set_coords_outside|\index{set_coords_outside@\lstinline+set_coords_outside+}\smallskip
+
+The result is as follows.
+
+
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+set_coords_outside;
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+
+There is also a command to position the coordinates inside the board.
+
+\commande|set_coords_inside|\index{set_coords_inside@\lstinline+set_coords_inside+}\smallskip
+
+You can see in this documentation that with \package{luamplib} and
+\LaTeX, the font is the font of the current document. To draw these letters and
+these numbers, \mpchess uses the \MP{} operator \lstinline+infont+ and the font
+is set to \lstinline+defaultfont+ by default\footnote{With \package{luamplib}
+the \lstinline+infont+ operator is redefined and its argument is simply
+ignored}, so it is not possible to modify the composition font of the
+coordinates. This font can be changed with the following command.
+
+\commande|set_coords_font(«font»)|\index{set_coords_font@\lstinline+set_coords_font+}\smallskip
+
+It will then be necessary to use the naming conventions specific to the \MP{}
+operator
+\lstinline+infont+ and we refer to the
+documentation~\cite{ctan-metapost} for more details.
+
+You can also delete the coordinates with the following command.
+
+\commande|set_no_coords|\index{set_no_coords@\lstinline+set_no_coords+}\smallskip
+
+And the reverse command also exists.
+
+\commande|set_coords|\index{set_coords@\lstinline+set_coords+}\smallskip
+
+
+\subsection{White or black side}
+
+To choose if you want to see the tray on the white or black side, \mpchess
+provides two commands.
+
+\commande|set_white_view|\index{set_white_view@\lstinline+set_white_view+}\smallskip
+
+\commande|set_black_view|\index{set_black_view@\lstinline+set_black_view+}\smallskip
+
+By default, we see the board on the white side.
+
+\subsection{Players' names}
+
+You can fill in the names of the players so that they are noted around the
+chessboard. This is done with the following commands.
+
+\commande|set_white_player(«string»)|\index{set_white_player@\lstinline+set_white_player+}\smallskip
+
+\commande|set_black_player(«string»)|\index{set_black_player@\lstinline+set_black_player+}\smallskip
+
+\begin{description}
+ \item[\meta{string} :] is the string interpreted by \LaTeX to display.
+\end{description}
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+set_white_player("\textbf{GM} Kasparov");
+set_black_player("\textbf{GM} Kramnik");
+
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+
+It is possible to place the names on the right side of the board without the
+black bands present by default.
+This happens either if the coordinates are printed outside the tray, or if the
+following command is used.
+
+\commande|set_players_side|\index{set_players_side@\lstinline+set_players_side+}\smallskip
+
+\begin{ExempleMP}[righthand width=0.6\linewidth]
+input mpchess
+beginfig(0);
+set_white_player("\textbf{GM} Kasparov");
+set_black_player("\textbf{GM} Kramnik");
+set_players_side;
+init_backboard;
+draw backboard;
+endfig;
+\end{ExempleMP}
+
+
+
+\section{Pieces et positions}
+
+\mpchess, as described above, builds the picture of a chess position
+layer by layer. This part is dedicated to the configuration of pieces and
+positions.
+
+Internally, \mpchess builds a table on the board grid. Then, some
+macros allow to generate a \lstinline+picture+ to be drawn \emph{over} the board (\lstinline+backboard+).
+
+\subsection{Setting the theme of the pieces}
+
+\mpchess provides for the moment three themes of pieces, two borrowed from
+Lichess, and the other borrowed from the
+package~\package{skak}~cite{ctan-skak}\footnote{Which provides the \MF{} code
+for a chess font, which has been easily adapted to \MP{} for \mpchess.}.
+
+To choose the theme we will use the following command.
+
+\commande|set_pieces_theme(«string»)|\index{set_pieces_theme@\lstinline+set_pieces_theme+}\smallskip
+
+\begin{description}
+ \item[\meta{string}:] can be:
+\begin{itemize}
+\item \lstinline+"cburnett"+ (default), to get the Lichess \emph{cburnett}
+pieces set;
+\item \lstinline+"staunty"+, to get the Lichess \emph{staunty}
+pieces set;
+\item \lstinline+"skak"+, to get the \package{skak}
+pieces set.
+\end{itemize}
+\end{description}
+
+
+The table~\ref{tab:pieces} shows the result of the three sets of pieces.
+\begin{table}
+ \centering
+\begin{tabular}{cc}
+
+\lstinline+cburnett+ theme&\lstinline+staunty+ theme\\
+\begin{mplibcode}
+ input mpchess
+ beginfig(0);
+ init_chessboard;
+ set_backboard_width(4cm);
+ set_pieces_theme("cburnett");
+ unset_whos_to_move;
+ init_backboard;
+ draw backboard;
+ draw chessboard_step(0);
+ endfig;
+\end{mplibcode}
+&\begin{mplibcode}
+ input mpchess
+ beginfig(0);
+ init_chessboard;
+ set_backboard_width(4cm);
+ set_pieces_theme("staunty");
+ unset_whos_to_move;
+ init_backboard;
+ draw backboard;
+ draw chessboard_step(0);
+ endfig;
+\end{mplibcode}\\
+\lstinline+skak+ theme&\\
+\begin{mplibcode}
+ input mpchess
+ beginfig(0);
+ init_chessboard;
+ set_backboard_width(4cm);
+ set_pieces_theme("skak");
+ unset_whos_to_move;
+ init_backboard;
+ draw backboard;
+ draw chessboard_step(0);
+ endfig;
+\end{mplibcode}&\\
+\end{tabular}
+\caption{The different themes of pieces provided by \mpchess.}\label{tab:pieces}
+\end{table}
+
+
+\subsection{Who’s to move}
+
+\mpchess indicates who has the move between white and black. This is done by
+a small colored triangle (white or black) at the end of the board (which you can
+you can see in the following examples).
+
+To specify who has to move we use the following commands.
+
+\commande|set_white_to_move|\index{set_white_to_move@\lstinline+set_white_to_move+}\smallskip
+
+
+\commande|set_black_to_move|\index{set_black_to_move@\lstinline+set_black_to_move+}\smallskip
+
+By default, white has to move, and this information is displayed.
+
+To activate or deactivate this display, use one of the following two
+commands.
+
+\commande|set_whos_to_move|\index{set_whos_to_move@\lstinline+set_whos_to_move+}\smallskip
+
+
+\commande|unset_whos_to_move|\index{unset_whos_to_move@\lstinline+unset_whos_to_move+}\smallskip
+
+\subsection{Draw position}
+
+The commands described below allow you to build a position in several ways
+(adding pieces one by one, reading a \textsc{fen} file, etc.). Once a position
+has been constructed, it can be plotted
+using the following command which generates a \MP{} \lstinline+picture+.
+
+
+\commande|chessboard|\index{chessboard@\lstinline+chessboard+}\smallskip \label{com:chessboard}
+
+The use of this command will be widely illustrated in the following examples.
+
+\subsection{Build a position}
+
+\subsubsection{Initialization}
+
+To obtain the initial position of a game, simply use the following command.
+
+\commande|init_chessboard|\index{init_chessboard@\lstinline+init_chessboard+}\smallskip
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+init_backboard;
+draw backboard;
+init_chessboard;
+draw chessboard;
+endfig;
+\end{ExempleMP}
+
+You can also initialize an empty \lstinline+chessboard+ with the following command.
+
+\commande|set_empty_chessboard|\index{set_empty_chessboard@\lstinline+set_empty_chessboard+}\smallskip
+
+\subsubsection{Adding pieces}
+
+You can add pieces to build a position with the following two commands.
+
+\commande|add_white_pieces(«piece1»,«piece2»,etc.)|\index{add_white_pieces@\lstinline+add_white_pieces+}\smallskip
+
+
+\commande|add_black_pieces(«piece1»,«piece2»,etc.)|\index{add_black_pieces@\lstinline+add_black_pieces+}\smallskip
+
+These commands take lists of \textbf{\meta{piece}} which are strings
+that describe the piece and the position using the
+algebraic notation. There is no limitation on the number of pieces in the list.
+
+The following example illustrates the use of these commands.
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+init_backboard;
+draw backboard;
+set_empty_chessboard;
+add_white_pieces("e1","Kd2");
+add_black_pieces("e7","f6","Kb8");
+draw chessboard;
+endfig;
+\end{ExempleMP}
+
+
+\subsubsection{Delete piece}
+
+\mpchess provides several commands to remove items from a position.
+
+The first command allows you to delete an item from a square. This command takes
+a list of squares, using algebraic notation.
+
+\commande|clear_squares(«square1»,«square2»,etc.)|\index{clear_squares@\lstinline+clear_squares+}\smallskip
+
+The \textbf{\meta{square1}}, \textbf{\meta{square2}}, etc., are strings, for example \lstinline+"a3"+.
+\medskip
+
+The following command allows to delete a set of squares in a region
+determined by two coordinates on the board. This command allows to take
+a list of regions.
+
+\commande|clear_areas(«area1»,«area2»,etc.)|\index{clear_areas@\lstinline+clear_areas+}\smallskip
+
+The \textbf{\meta{area1}}, \textbf{\meta{area2}}, etc., are strings consisting of two coordinates separated by a dash, for example \lstinline+"a3-g7"+.
+\medskip
+
+The following command deletes all the cells in a file (column) determined by a
+letter on the board. This command allows to take a list of files.
+
+
+\commande|clear_files(«file1»,«file2»,etc.)|\index{clear_files@\lstinline+clear_files+}\smallskip
+
+The \textbf{\meta{file1}}, \textbf{\meta{file2}}, etc., are strings of characters consisting of a letter, for example \lstinline+"a"+.
+\medskip
+
+The following command deletes all the cells in a rank (line) determined by a
+number on the board. This command allows to take a list of ranks.
+
+\commande|clear_ranks(«rank1»,«rank2»,etc.)|\index{clear_ranks@\lstinline+clear_ranks+}\smallskip
+
+The \textbf{\meta{rank1}}, \textbf{\meta{rank2}}, etc., are strings made up of a number, for example \lstinline+"4"+.
+
+The use of all these commands is illustrated in the following example.
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+init_backboard;
+draw backboard;
+init_chessboard;
+clear_squares("a1","b2");
+clear_areas("c2-d7");
+clear_files("f","h");
+clear_ranks("8");
+draw chessboard;
+endfig;
+\end{ExempleMP}
+
+
+
+\subsection{Reading data in \textsc{fen} format}
+
+\mpchess allows you to read a position in the \textsc{fen} format thanks to the following command.
+
+\commande|build_chessboard_from_fen(«string»)|\index{build_chessboard_from_fen@\lstinline+build_chessboard_from_fen+}\smallskip
+
+\begin{description}
+\item[\meta{string}:] is a string describing a position in
+\textsc{fen} format. Note that all information after the
+\texttt{w} or \texttt{b} character is ignored.
+\end{description}
+
+\begin{ExempleMP}
+input mpchess;
+beginfig(0);
+init_backboard;
+draw backboard;
+string fenstr;
+fenstr := "7r/2p1kp1p/p1B2p2/1pb5/8/2PP4/PP1N1PPP/R5K1 b - - 2 19";
+build_chessboard_from_fen(fenstr);
+draw chessboard;
+endfig;
+\end{ExempleMP}
+
+
+\subsection{Reading data in \textsc{pgn} format}
+
+\mpchess also makes it possible to read a string in the \textsc{pgn}
+format.
+When such a functionality is used, \mpchess stores all the
+intermediate positions and thus allows to represent them.
+
+To construct the positions, we use the following command.
+
+\commande|build_chessboards_from_pgn(«string»)|\index{build_chessboards_from_pgn@\lstinline+build_chessboards_from_pgn+}\smallskip
+
+The \textsc{pgn} format accepted is a simplified one which does not accept variants or comments.
+
+Once the positions are built, we can represent them with the following command.
+
+\commande|chessboard_step(«int»)|\index{chessboard_step@\lstinline+chessboard_step+}\smallskip
+\begin{description}
+\item[\meta{int}:] is the number of the step. The initial configuration is numbered 0, and then each move, white or black, is numbered.
+\end{description}
+
+This command, like \lstinline+chessboard+ (see page~\pageref{com:chessboard}),
+returns a \lstinline+picture+.
+
+The following example illustrates the use of these commands.
+
+\begin{ExempleMP}
+input mpchess;
+string pgnstr;
+pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+init_backboard;
+draw backboard;
+draw chessboard_step(3); % Nf3
+endfig;
+\end{ExempleMP}
+
+\subsubsection{Show last move}
+
+The last move can be displayed automatically with the following command.
+
+\commande|show_last_move(«int»)|\index{show_last_move@\lstinline+show_last_move+}\smallskip
+
+\begin{description}
+\item[\meta{int}:] is the number of the step. The initial setup is numbered 0, and then each move, white or black, is numbered.
+\end{description}
+
+This command colors in transparency the two squares where the last move starts
+and ends. Thus, it must be used between the drawing of the board
+(\lstinline+draw backboard+) and the drawing of the pieces
+(\lstinline+draw chessboard_step(i)+).
+
+\begin{ExempleMP}
+input mpchess;
+string pgnstr;
+pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+init_backboard;
+draw backboard;
+show_last_move(3);
+draw chessboard_step(3); % Nf3
+endfig;
+\end{ExempleMP}
+
+You can configure the color used to color the squares of the last
+move with the following command.
+
+\commande|set_last_move_color(«color»)|\index{set_last_move_color@\lstinline+set_last_move_color+}\smallskip
+\begin{description}
+ \item[\meta{color}:] is a \MP{} \lstinline+color+.
+\end{description}
+
+
+
+\subsubsection{Get the number of moves}
+
+You can get the number of half moves with the following command.
+
+\commande|get_halfmove_number|\index{get_halfmove_number@\lstinline+get_halfmove_number+}\smallskip
+
+This command returns a \lstinline+numeric+.
+
+You can also get the total number of moves in the sense that they are numbered
+in the \textsc{pgn} format, with the following command:
+
+\commande|get_totalmove_number|\index{get_totalmove_number@\lstinline+get_totalmove_number+}\smallskip
+
+This command returns a \lstinline+numeric+.
+
+\section{Annotation}
+
+Numerous commands allow to annotate the chessboard (arrow, color, circle, cross,
+etc.).
+
+\subsection{Arrows}
+
+The command for drawing arrows on the chessboard is the following.
+
+\commande|draw_arrows(«color»)(«string1»,«string2», etc.)|\index{draw_arrows@\lstinline+draw_arrows+}\smallskip
+\begin{description}
+\item[\meta{color}:] is a \MP{} \lstinline+color+.
+\item[\meta{string1}:] is a string (between double-quotes) consisting of two
+coordinates (letter and number) separated by two characters which can be
+\begin{description}
+\vitem+--+ to connect the two squares in a straight line;
+\vitem+-|+ to connect the two squares in a broken line, first horizontally then
+vertically;
+\vitem+|-+ to connect the two squares in a broken line, first vertically then
+horizontally.
+\end{description}
+\end{description}
+
+The following example illustrates the use of this command.
+\begin{ExempleMP}
+input mpchess;
+string pgnstr;
+pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+init_backboard;
+draw backboard;
+show_last_move(3);
+draw chessboard_step(3); % Nf3
+draw_arrows(red)("f8--b4","g1|-f3");
+endfig;
+\end{ExempleMP}
+
+The thickness of the arrows can be changed with the following command.
+\commande|set_arrow_width(«coeff»)|\index{set_arrow_width@\lstinline+set_arrow_width+}\smallskip
+
+\begin{description}
+ \item[\meta{coeff}:] is a coefficient (\lstinline+numeric+) which allows you
+ 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+.
+\end{description}
+
+The following example illustrates the use of this command.
+\begin{ExempleMP}
+input mpchess;
+string pgnstr;
+pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+set_black_view;
+init_backboard;
+draw backboard;
+show_last_move(3);
+draw chessboard_step(3); % Nf3
+set_arrow_width(0.12);
+draw_arrows(red)("f8--b4","g1|-f3");
+endfig;
+\end{ExempleMP}
+
+\subsection{Coloring squares}
+
+\mpchess also allows you to color squares with the following command.
+
+\commande|color_square(«color»)(«coord1»,«coord2», etc.)|\index{color_square@\lstinline+color_square+}\smallskip
+
+\begin{description}
+\item[\meta{color}:] is a \MP{} \lstinline+color+.
+\item[\meta{coord1}:] is a string (between double quotes) consisting of two
+coordinates (letter and number).
+\end{description}
+
+The following example illustrates the use of this command.
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+init_backboard;
+draw backboard;
+color_square(red)("e2","e7","c5");
+init_chessboard;
+draw chessboard;
+endfig;
+\end{ExempleMP}
+
+This command colors the squares with a certain transparency to fit to the white
+and black squares.
+
+\subsection{Circles}
+
+\mpchess allows you to surround squares with circles using the following command
+ below.
+
+\commande|draw_circles(«color»)(«coord1»,«coord2», etc.)|\index{draw_circles@\lstinline+draw_circles+}\smallskip
+
+\begin{description}
+\item[\meta{color}:] is a \MP{} \lstinline+color+.
+\item[\meta{coord1}:] is a string (between double quotes) consisting of two
+coordinates (letter and number).
+\end{description}
+
+The following example illustrates the use of this command.
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+init_backboard;
+draw backboard;
+init_chessboard;
+draw chessboard;
+draw_circles(green)("e2","e7","c5");
+endfig;
+\end{ExempleMP}
+
+
+
+\subsection{Crosses}
+
+
+\mpchess allows you to draw crosses on squares with the following command.
+
+\commande|draw_crosses(«color»)(«coord1»,«coord2», etc.)|\index{draw_crosses@\lstinline+draw_crosses+}\smallskip
+
+\begin{description}
+\item[\meta{color}:] is a \MP{} \lstinline+color+.
+\item[\meta{coord1}:] is a string (between double quotes) consisting of two
+coordinates (letter and number).
+\end{description}
+
+The following example illustrates the use of this command.
+
+
+\begin{ExempleMP}
+input mpchess
+beginfig(0);
+init_backboard;
+draw backboard;
+init_chessboard;
+draw chessboard;
+draw_crosses(0.7[green,black])("e2","e7","c5");
+endfig;
+\end{ExempleMP}
+
+\subsection{Move comments}
+
+\mpchess allows you to display the classic move comments of the type
+``!?’’ with the following command.
+
+\commande|draw_comment(«str»,«pos»)|\index{draw_comment@\lstinline+draw_comment+}\smallskip
+
+\begin{description}
+\item[\meta{str}:] is a string (between double-quotes) to display.
+\item[\meta{pos}:] is a string (between double-quotes) consisting of a coordinate (letter and number).
+\end{description}
+
+\begin{ExempleMP}
+input mpchess;
+string pgnstr;
+pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+init_backboard;
+draw backboard;
+show_last_move(3);
+draw chessboard_step(3); % Nf3
+draw_comment("?!","f3");
+endfig;
+\end{ExempleMP}
+
+The color of the comment annotation can be changed with the following command
+following command.
+\commande|set_comment_color(«color»)|\index{set_comment_color@\lstinline+set_comment_color+}\smallskip
+
+
+
+\section{Miscellaneous}
+
+\subsection{Reset the \lstinline+chessboard+}
+
+To reset the internal structure storing the positions of the parts, you can use
+the following command.
+
+
+\commande|clear_chessboard|\index{clear_chessboard@\lstinline+clear_chessboard+}\smallskip
+
+
+\subsection{Global reset}
+
+To reinitialize the values of the different parameters of \mpchess, you can use
+the following command.
+
+\commande|reset_mpchess|\index{reset_mpchess@\lstinline+reset_mpchess+}\smallskip
+
+
+\subsection{Clip the board}
+
+We can clip the chessboard with the following command.
+
+\commande|clip_chessboard(«string»)|\index{clip_chessboard@\lstinline+clip_chessboard+}\smallskip
+
+
+\begin{description}
+\item[\meta{string}:] is a string (between double quotes)
+composed of two coordinates (letter and number) separated by a dash, for example \lstinline+"a1-c6"+.
+\end{description}
+
+Here is an example of an illustration.
+\begin{ExempleMP}
+input mpchess;
+string pgnstr;
+pgnstr := "1. e4 e5 2. Nf3 Nc6 3. Nxe5 Nxe5 4. Bb5 c6";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+set_black_view;
+init_backboard;
+draw backboard;
+show_last_move(3);
+draw chessboard_step(3); % Nf3
+draw_comment("?!","f3");
+clip_chessboard("e1-g4");
+endfig;
+\end{ExempleMP}
+
+\section{To do}
+
+Many things can be added to \mpchess. Among these, we can think of:
+\begin{itemize}
+\item display the captured pieces, or the differential of the captured pieces;
+\item afficher le temps restant pour chaque joueur ;
+\item show the accessible squares for a chosen piece (the
+Lichess points);
+\item display the $n$ arrows indicating the $n$ moves of the first lines of a
+position (with a decreasing thickness of the arrows);
+\item adding the coordinates outside the board when it is clipped;
+\item add piece themes.
+\end{itemize}
+
+\section{Complete example}
+
+\begin{ExempleMP}[sidebyside=false]
+input mpchess
+string pgnstr;
+pgnstr:="1. e4 e5 2. Bc4 d6 3. Nf3 Bg4 4. Nc3 g6 5. Nxe5 Bxd1";
+build_chessboards_from_pgn(pgnstr);
+beginfig(0);
+set_white_player("Kermur de Legal");
+set_black_player("Saint-Brie");
+set_backboard_width(8cm);
+init_backboard;
+draw backboard;
+show_last_move(10);
+draw_comment("?","d1");
+color_square(0.3[green,black])("c4","c3","e5");
+color_square(0.3[red,black])("e8");
+draw chessboard_step(10);
+draw_arrows(0.3[green,black])("e5|-f7","c3-|d5");
+draw_arrows(0.3[red,black])("c4--f7");
+endfig;
+\end{ExempleMP}
+
+
+\printbibliography
+\printindex
+\end{document}
+
+
+
+%%% Local Variables:
+%%% flyspell-mode: 1
+%%% ispell-local-dictionary: "fr"
+%%% End: