\documentclass{ltxdoc}
\title{The \textsf{maze} package}
\usepackage[margin=2cm]{geometry}
\usepackage{graphicx}
\usepackage[T1]{fontenc}
\usepackage{inconsolata}
\usepackage{xcolor}
\usepackage{indentfirst}
\usepackage{hypdoc}
\hypersetup{colorlinks,urlcolor=cyan!20!blue}
\usepackage{cleveref}
\usepackage{maze}
\author{Sicheng Du\\\href{mailto:siddsc@foxmail.com}{siddsc@foxmail.com}}
\date{May 25, 2026~~v1.3}
\begin{document}
\maketitle
\section{Changes in this version}
\begin{enumerate}
\item Added input validation for the \verb|size| argument: it must be an integer in the range 2--99; the package now raises an error for out-of-range values.
\item Added a storage feature: \cs{mazesave\{name\}\{size\}[seed]} saves the rendered maze in a named box register so that the exact same maze can be reproduced later. Stored mazes also keep a solved overlay, and \cs{mazeuse[view]\{name\}} can typeset that overlay on demand.
\end{enumerate}
\section{User instructions}
The \textsf{maze} package can generate random square mazes, which can be played by navigating from the bottom-left corner to the top-right corner. The user can specify the size of the maze or whether to show its solution.

\begin{macro}{\maze}
\marg{size}\oarg{seed} is the syntax of the command that generates a maze. Thereinto
\begin{description}
\item[\marg{size}] controls the density of the walls inside the maze and directly influences its complexity. It must be a positive integer in the range \textbf{[2,99]}.

\item[\oarg{seed}] is an optional parameter that specifies the seed for random numbers. If it is omitted, the current time (minute) will be used as the seed instead.
\end{description}\end{macro}

For example, the mazes in \Cref{fig:maze-1} can be created by \cs{maze\{30\}[4]} and \cs{maze\{25\}} respectively.
\begin{figure}[htbp]
\centering
\maze{30}[4]\hspace{2cm}\maze{25}
\caption{Examples of mazes}
\label{fig:maze-1}
\end{figure}

\begin{macro}{\mazesave}
\marg{name}\marg{size}\oarg{seed} generates a maze once, stores the rendered result and allows that exact maze to be typeset again later.
\begin{description}
\item[\marg{name}] is the identifier of the stored maze. It is advised to use a string composed of ordinary printable text characters, although special ones like \verb|#| would probably work.
\item[\marg{size}] Same meaning and requirements as in \cs{maze}.
\item[\oarg{seed}] Same meaning and requirements as in \cs{maze}.
\end{description}
\end{macro}

\begin{macro}{\mazeuse}
\oarg{view}\marg{name} typesets a maze that was previously stored with \cs{mazesave}.
\begin{description}
\item[\oarg{view}] controls the display of an automatically generated solution to the maze. Put \verb|solution=line| or simply \verb|solution| to generate a line along the solution path, and \verb|solution=cells| to place a circle in each cell along the solution path. If left out, only the maze will be output.
\item[\marg{name}] must match the name set when \cs{mazesave} is called. 
\end{description}
\end{macro}

As an example, the mazes in Figure \ref{fig:maze-2} can be created by \cs{mazesave\{demo\}\{20\}} followed by \cs{mazeuse\{demo\}}, \cs{mazeuse[solution]\{demo\}}, and \cs{mazeuse[solution=cells]\{demo\}}.
\begin{figure}[htbp]
\centering
\mazesave{demo}{20}
\mazeuse{demo}\hspace{\fill}\mazeuse[solution]{demo}\hspace{\fill}\mazeuse[solution=cells]{demo}
\caption{Example of a saved maze and solution display}\label{fig:maze-2}
\end{figure}
\end{document}