
% !TeX encoding = utf8
% !TeX program = pdflatex
% !TeX spellcheck = en_GB

\documentclass[a4paper,11pt,headinclude,footinclude]{scrartcl}

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage[english]{babel}

\usepackage{imakeidx}
\IfFileExists{classic-en.ist}{%
	\makeindex[columns=2,options=-s classic-en,intoc]}{%
	\makeindex[columns=2,options=-s classic,intoc]}

\indexsetup{noclearpage,firstpagestyle=scrheadings}

\PassOptionsToPackage{%
	bookmarks=false,colorlinks,%
	linkcolor=RoyalBlue,linktocpage}{hyperref}
\PassOptionsToPackage{noopticals,loosequotes}{MinionPro}
\PassOptionsToPackage{dvipsnames}{xcolor}
\usepackage[nochapters,minionprospacing]{classicthesis}
\areaset{312pt}{699pt}
\setlength\marginparwidth{8em}

\usepackage[writefile]{listings}
\lstset{%
	morekeywords={v,h,minus,plus,ast,putsymbol,labyrinthsolution,
	autosolution,labyrinthset,solutionset,color}}

\usepackage[scaled=0.80]{beramono}
\renewcommand\sfdefault{iwona}

\usepackage{lettrine}
\usepackage{labyrinth}

\def\ins{~}

\def\stmtitle{The \pkgname{labyrinth} package}
\def\stmauthor{Francesco Zigliotto}
\def\stmdate{April 12, 2014}

\clearscrheadings
\chead{\stmtitle\ $\cdot$ \parbox[b]{\widthof{\stmtitle}}{\textcolor{Orange}{\itshape\stmauthor}}}
\cfoot{\pagemark}
\pagestyle{scrheadings}

\begin{document}

\colorlet{RoyalBlue}{MidnightBlue}

\begin{center}
{\LARGE\stmtitle\par\bigskip}
{\Large\color{Orange}\itshape\stmauthor\par\medskip}
{\itshape\stmdate}
\end{center}
\par\smallskip

\thispagestyle{plain}

\lettrine[findent=2pt,nindent=-2pt,loversize=.2,lraise=0]{\textcolor{Orange}{T}}{\lsstyle he} \pkgname{labyrinth} package provides a code and an environment for typesetting simple labyrinths with \LaTeX\ and generating an automatic or manual solution path.

\tableofcontents

\enlargethispage{2\baselineskip}

\begin{figure}[bh]
\par\bigskip
\begin{labyrinth}[unit=9pt]{19}{20}
\putsymbol(8,\minus1){\Large$\Uparrow$}
\putsymbol(10,20){\Large$\Uparrow$}
                        \h *9+---*7+
\v +*5-+--+--+---+--+   \h -*4+--+-+-*4+--+ 
\v +*4-++-++---+--++-+  \h *4+--+--+++--++--+ 
\v +---++-++---+++--+-+ \h -++--+---++*4-+++ 
\v +--++-+-++-+-+++---+ \h ++--+-+++--++---+++ 
\v +--+-+*4-++-*4+--+   \h -+++-*4+-+*6-+ 
\v +---++---++-++-+-+-+ \h +++---++--++-++---+ 
\v +--++---++--+--+++-+ \h -+--+++--++-++---+ 
\v +-++---++--+--+-++-+ \h +---++--++-++-++--+ 
\v +-+++-+++--+-++--+-+ \h -+*7-++*4-+++ 
\v ++-*6+-+-+-+-+--+    \h --+*8-*4+--++ 
\v ++--*8+-+-++--+      \h -+++*{12}-++ 
\v +-+--+-+-++-+-++--++ \h +--*7+-+++-++ 
\v +-+---+---+---+-+-++ \h -++-+--++-+++-++-+ 
\v ++-+-+---++-+-+--+-+ \h ---+-+++*5-+-++-+ 
\v +++-++--++-++-++-+-+ \h --+---+--++-+*4-+ 
\v ++-+-+-++--++-+-+-++ \h -+-+++--++*4-+++ 
\v +---+-++--*5+-*4+    \h -++*4-++ 
\v ++-*4+--+-+--*6+     \h *6-++-*5+ 
\v *4+-++*8-+-+++       \h ---+++-+-+-*6+ 
\v +-+*4-+--+*8-+       \h *7+---*9+

\autosolution[font=\color{Orange}](8,0)(10,19){u}

\labyrinthsolution[
	font=\color{MidnightBlue}\footnotesize,
	up=\kern2pt$\uparrow$,
	left=$\leftarrow$,
	down=\kern2pt$\downarrow$,
	right=$\rightarrow$,
	hcorr=0.1\unitlength,
	vcorr=0.3\unitlength](7,1){%
	ldlllluulddluuuuuuuruluuurulurrdd%
	dldrruuurrrddddluuuldddlldrrrdr}
\end{labyrinth}
\caption{A labyrinth example (the code is shown at page\ins\pageref{sec:Example}).}
\label{fig:Example}
\end{figure}

\section{A code for writing labyrinths}
\label{sec:GeneralCode}

The key-point in typesetting a labyrinth with \LaTeX\ is finding a way to describe it by a set of characters. The problem can be solved by including the labyrinth in an ideal $m$ by $n$ frame, divided into $m \cdot n$ unit squares. The grid is then split into $m$ horizontal sections, of $n$ unit squares each, as reported in Figure\ins\ref{fig:LabyrinthDivided}.

\begin{figure}
\centering
\begin{minipage}{.2\textwidth}
\centering
	\begin{labyrinth}[unit=10pt]{5}{5}
	\h*5+\v*5-+\h*4+\v++-+++\h\v+-++++\h-+\v+-++-+\h---+	
	\v+++--+\h+-+++
	\end{labyrinth}
\end{minipage}
{\Large$\Rightarrow$}
\quad
\begin{minipage}{.2\textwidth}
\centering
	\begin{labyrinth}[unit=10pt]{5}{5}
		\putsymbol(\minus1,5){1}
		\putsymbol(\minus1,4){2}
		\putsymbol(\minus1,3){3}
		\putsymbol(\minus1,2){4}
		\putsymbol(\minus1,1){5}
		\putsymbol(\minus1,0){6}
		\linethickness{0.1pt}
	\multiput(0,0)(1,0){6}{\line(0,1){6}}
	\multiput(0,0)(0,1){7}{\line(1,0){5}}
		\linethickness{1pt}
	\h*5+\v*5-+\h*4+\v++-+++\h\v+-++++\h-+\v+-++-+\h---+	
	\v+++--+\h+-+++
	\end{labyrinth}
\end{minipage}
{\Large$\Rightarrow$}
\quad
\begin{minipage}{.2\textwidth}
\centering
	\begin{labyrinth}[unit=10pt]{5}{10}
		\putsymbol(\minus1,10){1}
		\putsymbol(\minus1,8){2}
		\putsymbol(\minus1,6){3}
		\putsymbol(\minus1,4){4}
		\putsymbol(\minus1,2){5}
		\putsymbol(\minus1,0){6}
		\linethickness{0.1pt}
	\multiput(0,0)(0,2){6}{%
		\multiput(0,0)(1,0){6}{\line(0,1){1}}
		\multiput(0,0)(0,1){2}{\line(1,0){5}}}
		\linethickness{1pt}
	\h*5+
	\v\v*5-+\h*4+
	\v\v++-+++\h
	\v\v+-++++\h-+
	\v\v+-++-+\h---+
	\v\v+++--+\h+-+++
	\end{labyrinth}
\end{minipage}
\caption{The labyrinth grid split into horizontal sections. (The line thickness has been incremented to differentiate the labyrinth lines from the grid).}
\label{fig:LabyrinthDivided}
\end{figure}

\subsection{Marking horizontal lines}
\label{hlines}

First, we have to differentiate between the horizontal and vertical lines of the labyrinth. Let's focus on horizontal lines. For each unit square, you have to indicate either its bottom line belongs to the labyrinth or not. Accordingly, you will type either “\othname{+}” or “\othname{-}”. For example, with reference to Figure\ins\ref{fig:LabyrinthDivided}, the first four unit squares of the second section have their bottom lines included in the labyrinth, while the last one has not. The corresponding description is “\texttt{++++-}”.

\subsection{Marking vertical lines}
\label{vlines}

Each horizontal section contains $n$ unit squares and thus $(n+1)$ vertical sides. Similarly to horizontal lines, each vertical side is marked by a “\othname{+}” if it is a part of the labyrinth and by a “\othname{-}” if it is not the case. For example, in Figure\ins\ref{fig:LabyrinthDivided}, the vertical lines in the fourth section are marked as “\texttt{+-++++}”. 

\subsection{Merging horizontal and vertical marks}
\label{sec:MarkWhole}

Now we have to arrange the horizontal and vertical descriptions into a unique code. For each section, \emph{first} we write \cmdname{v}, followed by the description of the vertical lines and \emph{then} \cmdname{h}, followed by the description of horizontal lines.

Be careful to keep the correct sequence (\cmdname{v} leading \cmdname{h}), because every \cmdname{v} command also increases the labyrinth section number which we are referring to.

Very often, the first section has no vertical lines (while horizontal lines are quite common). If this is the case, we may start the code with \cmdname{h}, skipping the \cmdname{v} command . Out of the first section, any other one without vertical sides belonging to the labyrinth calls for the \cmdname{v} command. 

With the above rules, the code of the labyrinth of Figure\ins\ref{fig:LabyrinthDivided} is written as follows:
\begin{code}
          \h +++++ % 1st section 
\v -----+ \h ++++- % 2nd section
\v ++-+++ \h ----- % 3rd section
\v +-++++ \h -+--- % 4th section
\v +-++-+ \h ---+  % 5th section
\v +++--+ \h +-+++ % 6th section
\end{code}

\subsection{Simplifying the code}

The labyrinth code can be simplified, by using the rules listed below:
\begin{itemize}
	\item all “\othname{-}” characters at the end of each section can be omitted, for both horizontal and vertical marks;
	\item the \cmdname{h} command can be omitted for any section void of horizontal lines;
	\item if there are more than three consecutive “\othname{+}” or “\othname{-}” characters, you can use the following syntax:\othindex{*}
\begin{code}
*{£*\meta{n}*£}+ £*\normalfont or*£ *{£*\meta{n}*£}-
\end{code}
where \meta{n} is the number of “\othname{+}” or “\othname{-}”.
\end{itemize}

For example, the code of Section\ins\ref{sec:MarkWhole} can be simplified like this:
\begin{code}
          \h *5+   % 1st section 
\v *5-+   \h *4+   % 2nd section
\v ++-+++          % 3rd section
\v +-*4+  \h -+    % 4th section
\v +-++-+ \h ---+  % 5th section
\v +++--+ \h +-+++ % 6th section
\end{code}

\section{The \envname{labyrinth} environment}

To typeset a labyrinth with the \pkgname{labyrinth} package, you can use the \envname{laby\-rinth} environment:

\begin{code}
\begin{labyrinth}[£*\meta{options}*£]{£*\meta{width}*£}{£*\meta{height}*£}
£*\meta{labyrinth code}*£
\end{labyrinth}
\end{code}

where:
\begin{itemize}
	\item \meta{width} is the number of columns ($n$) of the ideal grid described in Section\ins\ref{sec:GeneralCode} (see Figure\ins\ref{fig:LabyrinthDivided});
	\item \meta{heigth} has to be set to ($m-1$), where $m$ is the number of horizontal sections, since only the bottom lines of the first horizontal section belong to the labyrinth (see Figure\ins\ref{fig:LabyrinthDivided});
	\item \meta{options} are optional parameters in the form \texttt{key=value} of the \pkgname{xkeyval} package (see Subsection\ins\ref{sec:Options});
	\item \meta{labyrinth code} is the code using the \cmdname{v} and \cmdname{h} commands, as described in Section\ins\ref{sec:GeneralCode}.
\end{itemize}

\subsection{Options of the \envname{labyrinth} environment}
\label{sec:Options}

There are some options for the labyrinths, which you can put either in the optional argument of the \envname{labyrinth} environment or in the argument of the \cmdname{labyrinthset} command, which should be placed outside the labyrinth environment. It that case, the options work for all the labyrinths from then on.
\begin{code}
\labyrinthset{£*\meta{options}*£}
\end{code}

The possible \meta{options}, in the form \othname*{key=value}, are:
\begin{description}
	\item[\optname{unit}] (default: \othname*{11pt}) sets the width of the side of every unit square of the ideal grid (see).
	\item[\optname{thickness}] sets the thickness of the lines of the labyrinth.
	\item[\optname{centered}] (values: \othname*{true}/\othname*{false}) centres horizontally the labyrinth. It also leaves extra space before and after.
\end{description}

\subsection{Adding elements to the labyrinth}

The content of the \envname{labyrinth} environment is internally put inside a \envname{picture} environment, so that if we need to add to the labyrinth oblique lines, symbols or so we can do it with the usual \LaTeX\ command \cmdname{put}, \cmdname{line}\dots

To put symbols inside the labyrinth, we can use the \cmdname{putsymbol} command, similar to \cmdname{put}, except for it centres its argument horizontally inside the ideal square:
\begin{code}
\putsymbol(£*\meta{h-pos}*£,£*\meta{v-pos}*£){£*\meta{symbol}*£}
\end{code}
%
%The \pkgname{labyrinth} package is compatible with the \pkgname{picture} package.

\subsection{Replacing “\othname{+}”, “\othname{-}” and “\othname{*}” characters}

Of course, inside the \envname{labyrinth} environment, we can't use the characters “\othname{+}”, “\othname{-}” and “\othname{*}” outside the foreseen position, which are substituted by the \cmdname{plus}, \cmdname{minus} and \cmdname{ast} commands, respectively.

\section{Typesetting the solution of the labyrinth}

\subsection{The \cmdname{labyrinthsolution} macro}

If we need to typeset the solution of a labyrinth, we can use the \cmdname{laby\-rinthsolution} command with the following syntax:
\begin{code}
\labyrinthsolution[£*\meta{options}*£](£*\meta{x,y}*£){£*\meta{solution code}*£}
\end{code}
where:
\begin{itemize}
\item \meta{options} are the optional parameters of the command in the form \texttt{key=value} of the \pkgname{xkeyval} package (see the next Subsection\ins\ref{sec:KeyOptions}).

\item \meta{x,y} are the horizontal and vertical coordinates of the starting point of the solution. Please note that these coordinates are automatically increased by half a \cmdname{unitlength} (for more details, see the options \optname{hcorr} and \optname{vcorr} in the Subsection\ins\ref{sec:KeyOptions}).

\item \meta{solution code} is a sequence of characters of the set $\{$\othname{u},\othname{l},\othname{d},\othname{r}$\}$. From the starting point (\meta{x,y}) we describe each segment of the solution path by indicating the direction: up (\othname{u}), left (\othname{l}), down (\othname{d}) or right (\othname{r}). Each step is one \cmdname{unitlength} long.

\end{itemize}
Please note that:
\begin{itemize}
\item the \cmdname{labyrinthsolution} command should be put \emph{inside} the \envname{laby\-rinth} environment;
\item there can be more than one \cmdname{labyrinthsolution} command inside the same labyrinth (e.g. for multiple solutions).
\end{itemize}

\subsection{Options of the \cmdname{labyrinthsolution} command}
\label{sec:KeyOptions}

As the labyrinth options and the \cmdname{labyrinthset} macro (Subsection\ins\ref{sec:Options}), you can put the solution options either in the optional argument of the \cmdname{labyrinthsolution} command or in the argument of the \cmdname{solutionset} command, that should be placed outside the labyrinth environment and that works for all the labyrinth solutions from then on.
\begin{code}
\solutionset{£*\meta{options}*£}
\end{code}

\goodbreak
The possible \meta{options} are:\nobreak
\begin{description}
	\item[\optname{hidden}] (values: \optname*{true}/\optname*{false}, default: \optname*{false}) hides (\optname*{true}) or shows (\optname*{fal\-se}) the solution  the labyrinth.
	\item[\othname{thicklines}] (values: \optname*{true}/\optname*{false}, default: \optname*{true}) sets the lines of the solution thick (\optname*{true}) or thin (\optname*{false});
	\item[\othname{up}] (default: \lstinline!\line(0,1){1}!) defines the symbol that indicates a step up in the solution path (letter \othname{u});
	\item[\othname{left}] (default: \lstinline!\line(-1,0){1}!) as above, for the left step (letter \othname{l});
	\item[\othname{down}] (default: \lstinline!\line(0,-1){1}!) as above, for the down step (letter \othname{d});
	\item[\othname{right}] (default: \lstinline!\line(1,0){1}!) as above, for the right step (letter \othname{r});
	\item[\othname{hcorr}] (default: \lstinline!0.5\unitlength!) sets the increment of the horizontal coordinate (it moves horizontally all the solution route);
	\item[\othname{vcorr}] (default: \lstinline!0.5\unitlength!) sets the increment of the vertical coordinate (it moves vertically all the solution route);
	\item[\othname{font}] (default: \lstinline!\color{red}! if \cmdname{color} is defined) select the font (mainly the colour) of the labyrinth solution.
\end{description}

\subsection{Automatic solution of the labyrinth}

The package also provides the macro \cmdname{autosolution} that finds and draws automatically one of the labyrinth solutions (if any, of course):
\begin{code}
\autosolution[£*\meta{options}*£](£*\meta{$x_A$,$y_A$}*£)(£*\meta{$x_B$,$y_B$}*£){£*\meta{first direction}*£}
\end{code}
where:
\begin{itemize}
\item \meta{options} are the same optional parameters of the \cmdname{labyrinth\-solution} command described in Section\ins\ref{sec:KeyOptions};

\item \meta{$x_A$,$y_A$} and \meta{$x_B$,$y_B$} are the horizontal and vertical coordinates of the starting point (A) and of the arrival point (B) of the  solution path. Please note that the coordinates of both points are automatically increased by half a \cmdname{unitlength} (for more details, see options \optname{hcorr} and \optname{vcorr} in the Subsection\ins\ref{sec:KeyOptions}).

\item \meta{first direction} is one character of the set $\{$\othname{u},\othname{d},\othname{l},\othname{r}$\}$ (up, down, left, right - respectively) that indicates the direction of the first step of the solution path.

\end{itemize}

The \cmdname{autosolution} command also defines \cmdname{solutionpath}, which generates the string of direction-characters that defines the solution path.

\clearpage
\section{Example}

Here you can see the code used for the labyrinth of Figure\ins\ref{fig:Example}:
\label{sec:Example}
\begin{code}
\begin{labyrinth}[unit=9pt]{19}{20}
\putsymbol(8,\minus1){\Large$\Uparrow$}
\putsymbol(10,20){\Large$\Uparrow$}
                        \h *9+---*7+
\v +*5-+--+--+---+--+   \h -*4+--+-+-*4+--+ 
\v +*4-++-++---+--++-+  \h *4+--+--+++--++--+ 
\v +---++-++---+++--+-+ \h -++--+---++*4-+++ 
\v +--++-+-++-+-+++---+ \h ++--+-+++--++---+++ 
\v +--+-+*4-++-*4+--+   \h -+++-*4+-+*6-+ 
\v +---++---++-++-+-+-+ \h +++---++--++-++---+ 
\v +--++---++--+--+++-+ \h -+--+++--++-++---+ 
\v +-++---++--+--+-++-+ \h +---++--++-++-++--+ 
\v +-+++-+++--+-++--+-+ \h -+*7-++*4-+++ 
\v ++-*6+-+-+-+-+--+    \h --+*8-*4+--++ 
\v ++--*8+-+-++--+      \h -+++*{12}-++ 
\v +-+--+-+-++-+-++--++ \h +--*7+-+++-++ 
\v +-+---+---+---+-+-++ \h -++-+--++-+++-++-+ 
\v ++-+-+---++-+-+--+-+ \h ---+-+++*5-+-++-+ 
\v +++-++--++-++-++-+-+ \h --+---+--++-+*4-+ 
\v ++-+-+-++--++-+-+-++ \h -+-+++--++*4-+++ 
\v +---+-++--*5+-*4+    \h -++*4-++ 
\v ++-*4+--+-+--*6+     \h *6-++-*5+ 
\v *4+-++*8-+-+++       \h ---+++-+-+-*6+ 
\v +-+*4-+--+*8-+       \h *7+---*9+

\autosolution[font=\color{Orange}](8,0)(10,19){u}

\labyrinthsolution[
	font=\color{MidnightBlue}\footnotesize,
	up=\kern2pt$\uparrow$,
	left=$\leftarrow$,
	down=\kern2pt$\downarrow$,
	right=$\rightarrow$,
	hcorr=0.1\unitlength,
	vcorr=0.3\unitlength](7,1){%
	ldlllluulddluuuuuuuruluuurulurrdd%
	dldrruuurrrddddluuuldddlldrrrdr}
\end{labyrinth}
\end{code}

%\begin{center}
%\begin{labyrinth}{5}{5}
%\v*2{-+}\h*2{-+}
%\v*2{+-}+\h*2{+-}+
%\v*2{-+}\h*2{-+}
%\v*2{+-}+\h*2{+-}+
%\v*2{-+}
%\end{labyrinth}
%\end{center}

\printindex

\end{document}