summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/skak/skakdoc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/skak/skakdoc.tex')
-rw-r--r--Master/texmf-dist/doc/latex/skak/skakdoc.tex417
1 files changed, 417 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/skak/skakdoc.tex b/Master/texmf-dist/doc/latex/skak/skakdoc.tex
new file mode 100644
index 00000000000..69c11c8c29d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/skak/skakdoc.tex
@@ -0,0 +1,417 @@
+\documentclass[11pt,twocolumn]{article}
+
+\usepackage{lambda,ifthen,calc}
+\usepackage{tabularx}
+\usepackage[ps,mover]{skak}
+
+\newcommand{\package}[1]{\textsf{#1}}
+\newcommand{\pgn}{PGN\ }
+\newcommand{\san}{SAN\ }
+\newcommand{\fen}{FEN\ }
+\newcommand{\xboard}{xboard}
+\newcommand{\metafont}{\textsc{Metafont}\ }
+\newcommand{\filename}[1]{\texttt{#1}}
+%\usepackage[a5paper]{anysize}
+%\tracingmacros=1
+
+\newcommand{\Guido}{Guido Governatori\ }
+\newcommand{\Harri}{Harri Haanpaa\ }
+\newcommand{\Ingo}{Ingo Sander\ }
+\newcommand{\Dirk}{Dirk B\"achle\ }
+\newcommand{\Ulrike}{Ulrike Fischer\ }
+\newcommand{\Andreas}{Andreas Wilm\ }
+
+\title{Typesetting Chess in \LaTeX with the \package{skak} Package\\
+Version 1.3}
+\author{Torben Hoffmann\\ e-mail: \texttt{Torben.Hoffmann@motorola.com}}
+\begin{document}
+\maketitle
+
+\begin{abstract}
+ This user guide shows how to use an enhancement to the existing
+ package for typesetting chess in \LaTeX (\package{skak}). The
+ primary improvement over the old package is that it has become
+ easier to typeset chess games with this new package.
+\end{abstract}
+
+\newpage
+\tableofcontents
+\newpage
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Change History}
+\label{sec:change-history}
+
+
+\subsection*{Version 1.3}
+\label{sec:version-1.3}
+
+\begin{itemize}
+\item \Dirk has reworked the typesetting of chess moves:
+ \begin{itemize}
+ \item A new capture symbol has been introduced to make the spacing around
+ it better.
+ \item The figurine symbols have been improved so that the spacing around
+ them are more uniform --- it looks really good now, at least to my eyes.
+ \item A proposal for what syntax the \package{skak} package should handle in
+ the future has been included in the distribution.
+ \item The Informator symbols ``novelty'', ``comment'' and ``various'' needed
+ another pair of curly braces in order to work right within the
+ ``mainline'' and ``variation'' environments.
+ \item The check for trailing spaces in the macro ``typeset@cmoves'' had to
+ be removed because it led to problems at the end of a ``mainline'' or
+ ``variation'' environment when an additional Informator symbol was
+ involved.
+ \end{itemize}
+\item A reference to the \textsf{pgn2ltx} tool created by \Dirk has been added
+ to the document.
+\item A reference to an URL decribing the \pgn standard has been added.
+\end{itemize}
+
+
+\subsection*{Version 1.2}
+\label{sec:version-1.2}
+
+\begin{itemize}
+\item \Dirk has --- once again --- done a great job:
+ \begin{itemize}
+ \item the informator symbols have been improved and now scale as
+ they should (I have in the same go done some \metafont clean-up
+ associated with the symbols).
+ \item he has also discovered that the selection of other fonts for
+ the typesetting of moves can be done by redefining the
+ \verb|\skakfamily| command!
+ \item added the \verb|\movecomment| for flexible typesetting of
+ comments --- see the Reference Manual for details.
+ \item The PostScript file are now 10 times smaller (for large files)
+ and a comprehensive test of the PostScript ornaments has been
+ created.
+ \end{itemize}
+\item All dead code has been removed from \texttt{skak.sty}.
+\end{itemize}
+
+
+\subsection*{Version 1.1}
+\label{sec:version-1.1}
+
+\begin{itemize}
+\item \Dirk's enhancements have been incorporated:
+ \begin{itemize}
+ \item extension of the \verb|\highlight| command; it now accepts X,
+ x, O and o as optional arguments and produces a cross and a
+ circle on the square, respectively, instead of a frame around the
+ square.
+ \item unwanted generation of spaces removed.
+ \item a set of Informator symbols were added to the fonts and made
+ available through commands documented in the
+ \texttt{informator.ps} file.
+ \end{itemize}
+\item Two fixes by \Ulrike have been incorporated:
+ \begin{itemize}
+ \item a bug in \verb|\ParseCoordinates|.
+ \item a problem in the fonts regarding size.
+ \end{itemize}
+\item \Ulrike reported a problem with opening spaces causing the input
+ to be ignored --- this has been fixed and \filename{test/test2.tex}
+ verifies this.
+\end{itemize}
+
+
+
+\subsection*{Version 1.0}
+\label{sec:version-1.0}
+
+The major novelty in this release is that the documentation has been
+updated and a reference manual has been created.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Terms of Usage}
+\label{sec:terms-usage}
+
+This package is distributed under the terms described in the Latex
+Project Public Licence, i.e.,
+
+\begin{quote}
+ This software is copyright but you are granted a license which gives
+ you, the ``user'' of the software, legal permission to copy,
+ distribute, and/or modify the software. However, if you modify the
+ software and then distribute it (even just locally) you must change
+ the name of the software to avoid confusion.
+\end{quote}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Acknowledgements}
+\label{sec:acknowledgements}
+
+I would like to thank the creator of the \package{lambda} package,
+Alan Jeffrey, for making a splendid package that made this package
+possible.
+
+For discussions and alpha-testing I send my thanks to \Guido --- some
+of his ideas have already been implemented; the rest? Time will show.
+
+Thanks to \Harri for finding a nasty bug in the castling routine.
+
+A big thank goes to \Dirk for adding the Informator symbols to the
+fonts and for removing a couple of nasty bugs as well as improving
+some of the commands.
+
+I thank \Ulrike for spotting as well as fixing a big problem with the
+parsing of moves and for her hints to improving the fonts.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{The Old \package{chess} Package Versus the New \package{skak}
+ Package}
+\label{sec:old-vs-new}
+
+The main reason for considering an improvement of the \package{chess}
+package that Piet Tutelaers made back in 1991 is the cumbersome user
+interface the package has when one wants to write about a chess game
+and display a diagram every now and then. Typesetting the two opening
+moves where white and black move their kingside knights is done as
+follows in the \package{chess} package:
+
+\begin{verbatim}
+\move g1f3 g8f6
+\end{verbatim}
+
+The package then produces a nice typesetting of these moves in figurine
+notation, but it is hard to keep track of what is going on because one usually
+uses the \san (Short Algebraic Notation, employed in the \pgn standard for
+typing the moves --- see \texttt{http://pgn.freeservers.com/standard.txt} for
+details) to write down the moves of a chess game. The \san version of the two
+moves above is: \verb|1. Nf3 Nf6|, which is much clearer to most chess
+players. In the \package{skak} package the author of a chess article is
+allowed to use the \san notation as input to the command that updates the
+chess board. In addition to making it easier for the author to write about
+chess using a familiar notation it also provides an easy way to include moves
+generated by a chess program such as \xboard\ in the document---most other
+chess programs can also output a \pgn version of a chess game and from that
+you can extract the \san recording of the moves.
+
+The \package{skak} package can also input chess board positions given
+in the \fen notation (also used in the \pgn standard), which is also quite
+standard in the domain of chess programs.
+
+Apart from a better user interface the \package{skak} chess font
+contains three small modifications of the font created by Piet
+Tutelaers: the knight now looks a bit more ``youthful'', the contour
+of the queen has been smoothened and all the chess pieces have been
+shrunk such that they do not fill as much of a square as before. I
+find this font nicer to look at, but your milage may vary.
+
+
+
+
+\section{How to use the \package{skak} Package}
+\label{sec:how-use-skak-package}
+
+Writing about a chess game can be done straightforward:
+
+\begin{verbatim}
+\newgame
+
+\mainline{1. e4 e5 2. Nf3 Bc5}
+\end{verbatim}
+
+\newgame
+\noindent
+starts a new game and produces the following in your document:
+
+\mainline{1. e4 e5 2. Nf3 Bc5}
+
+So far, so good. If you want to show the current position you just
+type \verb|\[\showboard\]| in your document to get:
+
+\[\showboard\]
+
+\noindent
+(the use of math \verb|\[...\]| is just to make sure the board is centered.)
+
+This is the basic functionality of the \package{skak} package, but it
+offers many different ways in which one can talk about chess
+games. I think that a good way to show how the \package{skak} package
+can be used is to typeset the Fischer--Tal game from the old
+\package{chess} package. The result is in the file named
+\filename{tuggame.ps}.
+
+Further information about all the bells and whistles the
+\package{skak} package provides can be found in the \emph{Reference
+ Manual} where all commands of relevance are described.
+
+
+\subsection{Handling of Variations}
+\label{sec:handling-variations}
+
+
+The \package{skak} package does \emph{not} support
+\pgn variations such as
+\begin{verbatim}
+\mainline{12. Bb4 (12. Ng5 h6) 12... Ra8}
+%gives an error
+\end{verbatim}
+
+You have to type this as
+\begin{verbatim}
+\mainline{12. Bb4}
+\variation{12. Ng5 h6}
+\mainline{12...Ra8}
+\end{verbatim}
+
+I do not have the nerves to update the parsing algorithm to cope with
+this so the best thing to do would be to craft a tool for translating
+\pgn to \TeX (see \ref{sec:transl-pgn-files}).
+
+
+\subsection{Changing the Font}
+\label{sec:changing-font}
+
+(New in Version 1.2)
+
+\Dirk has discovred that you can change the font used for typesetting
+of moves if you redefine the \verb|\skakfamily| font.
+
+I do not --- however --- know how to handle different chess fonts, so
+if someone could work this out I'll include that in a future version.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Installing the \package{skak} Package}
+\label{sec:install}
+
+I could not get the makefile to do the job, so if someone could help
+me out on this I would be very glad indeed.
+
+Basically all you have to do is to follow the guidelines in the
+makefile. First you create all the required directories (stated in the
+\texttt{install} section of the makefile) and then you run the
+\texttt{make install} command. Remember to run \texttt{texhash} after
+you have updated your texmf tree.
+
+Sorry that it is not working $100\%$--- I just do not have the time for
+it right now.
+
+If you cannot get the things working just put the files where \TeX and
+the other tools can find them and you will be just fine.
+
+
+\subsection{Using the \package{lambda} Package}
+\label{sec:using-lambda}
+
+The \package{skak} package uses the \package{lambda} package to do
+some of the hard processing necessary to allow the \pgn notation as
+input --- since it is not standard in \LaTeX distributions it is
+included in the distribution of the \package{skak} package.
+
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\section{Future Additions/Wish-list}
+\label{sec:future-additions}
+
+
+\subsection{Choosing Language for \texttt{mainline}}\label{sec:choos-lang-mainline}
+
+(Proposal date: mid 2002.)
+
+It would be nice if one could choose the language for the
+\verb|mainline|, \verb|variation| and \verb|\hidemoves| for each invocation
+as it allows for easier inclusion of analysis from chess programs when
+using a non-english language.
+
+
+\subsection{Algebraic Notation used for Typesetting}
+\label{sec:algebraic-notation-in-typesetting}
+
+(Proposal date: mid 2001.)
+
+\Ingo has suggested that the output of the typesetting should be the
+old algebraic notation where the from and to squares always are
+given. This requires a modification to the game engine: after each
+move has been made you should store the algebraic notation of the move
+since you have the to and from squares calculated at that
+moment. Changing the game engine is a bit hairy --- even for me --- so I'll
+postpone this.
+
+
+\subsection{Fonts}
+\label{sec:ps-font}
+
+(Proposal date: dec-2002.)
+
+\Ulrike has suggested the creation PostScript version of the \metafont
+font.
+
+I do not know how to do this, but perhaps someone can help me?
+
+Furthermore, \Ulrike would like to see a more transparent
+fonthandling, so that it becomes easy to change to another chess-font.
+(Version 1.2 news: see Section~\ref{sec:changing-font}.)
+
+
+\subsection{Optimisation of the Implementation}
+\label{sec:optim-impl}
+
+(Proposal date: 2-Jan-2003.)
+
+I would like to improve some areas of the implementation since they
+are unnecessary slow and/or complicated, e.g., \verb|\IsPieceName|
+could easily be implemented as a case statement instead of a list
+look-up. I have a strong feeling that this would be a lot faster than
+the current implementation which has a very functional programming
+flavour --- this was very helpful during the development, but it has a
+tendency to be a bit inefficient.
+
+Another great improvement would be to let the commands
+\verb|\Mainline| and \verb|\typeset@A| use the same parsing algorithm
+--- then one could implement the long algebraic notation as suggested
+by \Ingo by letting the action taken on a move be both updating of the
+board \emph{and} typesetting of the move!
+
+\subsection{Test Suite}
+\label{sec:test-suite}
+
+(Proposal date: 03-Jan-2003.)
+
+It would be a very good idea to create a test suite created using
+normal testing techniques.
+Areas of test should include:
+\begin{itemize}
+\item resolving ambiguous moves, i.e., ensuring that moves like
+ \wmove{Rad1} moves the right rook.
+\item all legal \san moves are accepted.
+\end{itemize}
+
+
+
+\subsection{Translating \pgn Files}
+\label{sec:transl-pgn-files}
+
+(Proposal date: 03-Jan-2003.)
+
+It would be very nice if one had a command line tool that could
+translate \pgn files to a \TeX file.
+
+27-Sep-2003: Take a look at \texttt{http://pgn2ltx.sourceforge.net} for a nice
+helper tool.
+
+
+\subsection{Typesetting \textsl{e.p.} after en passant moves}
+\label{sec:typeset-en-passant}
+
+\Andreas asked how one should input en passant moves, especially the addition
+of \textsl{e.p.} after the capture.
+
+This is not part of the \san notation as described in the \pgn standard and it
+requires that the improvement described in Section \ref{sec:optim-impl} is in
+place before it is possible to add the possibility to add the
+\textsl{e.p.}. It has to be this way because I do not want to support more
+than what is described by the \pgn standard.
+
+
+\end{document}
+
+
+
+
+