diff options
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.tex | 1224 |
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: |