summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/rubik/rubikrotation.dtx')
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikrotation.dtx1177
1 files changed, 780 insertions, 397 deletions
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
index 8ffc824499a..57302ac37a7 100644
--- a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
+++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
@@ -1,10 +1,12 @@
% \iffalse meta-comment
% rubikrotation.dtx
%
+% version 3.0
+%
% Authors: RWD Nickalls (dick@nickalls.org)
% and Apostolos Syropoulos (asyropoulos@yahoo.com)
-% Copyright 2014 RWD Nickalls + A Syropoulos
+% Copyright 25 September 2015 RWD Nickalls + A Syropoulos
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
@@ -36,10 +38,12 @@
process rubikrotation.dtx again)^^J}\stop
}%
\usepackage{ifpdf}
-\usepackage{url} %% for references
-\usepackage{graphicx} %% for the two pdf figs
+\usepackage{url,path} %% for references and paths
+\usepackage{graphicx} %% for the two pdf figs
+\usepackage{hypdoc} %% for pdf bookmarks + hyperref documenting of packages
%%\OnlyDescription
\EnableCrossrefs
+\PageIndex
\CodelineIndex
\CodelineNumbered
\RecordChanges
@@ -54,7 +58,7 @@
%
%
%
-% \CheckSum{302}
+% \CheckSum{310}
%
%%% \CharacterTable
%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -74,65 +78,72 @@
%
%
%
-% \title{The \textsf{rubikrotation} package}
+% \title{The \rubikrotation\ package}
%
% \author{
% RWD Nickalls (dick@nickalls.org) \\
% A Syropoulos (asyropoulos@yahoo.com)
% }
-% \date{This file describes version \RRfileversion, last revised \RRfiledate}
+% \date{This file describes version \RRfileversion\ (\RRfiledate)\\
+% \texttt{www.ctan.org/pkg/rubik}}
% \maketitle
%
% \begin{abstract}
-% The \rubikrotation\ package is an extension for the
-% \textsf{rubikcube} package. It provides the \cmd{\RubikRotation} command which
-% processes on-the-fly a sequence of Rubik rotation moves (using the Perl script
-% \texttt{rubikrotation.pl}) and returns the new Rubik cube state. It implements
-% some basic checking of the Rubik state, and also offers a command for displaying
-% any errors (\cmd{\ShowRubikErrors}).
-% This package requires access to the \TeX\ \texttt{write18} facility by using the
-% \texttt{--shell-escape} commandline switch.
-% The \textsf{rubikrotation} package has been road-tested on a Microsoft
-% platform (with MikTeX and Strawberry Perl), on a Linux platform ({\TeX}Live and Mandriva),
-% and on OpenIndiana (a Solaris platform).
+% The \rubikrotation\ package is a dynamic extension for the
+% \textsc{rubikcube} package (both are part of the Rubik `bundle').
+% The package provides the \cmd{\RubikRotation} command which
+% processes a sequence of Rubik rotation moves on-the-fly (using the Perl script
+% \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration).
+% The \rubikrotation\ package also provides a command for implementing some basic
+% checking of the Rubik cube state (\cmd{\CheckRubikState}), and one
+% for displaying any errors (\cmd{\ShowRubikErrors}).
+%
+% The \rubikrotation\ package requires access to the \TeX\ \texttt{write18}
+% facility, which is enabled by using the \texttt{--shell-escape} command-line switch.
+% The~\rubikrotation\ package has been road-tested on a Microsoft
+% platform (with MiKTeX and Strawberry Perl), on a Linux platform
+% (Mandriva using {\TeX}Live), and on a Solaris platform (OpenIndiana).
% \end{abstract}
%
+% \begin{minipage}{11cm}
+% \centering
+% \ifpdf
+% \includegraphics[width=10cm]{Rubikrot-doc-figD.pdf}
+% \else
+% \fi
+% \end{minipage}
%
-% \bigskip
+% \vspace{-1\baselineskip}
%
% \tableofcontents
%
% \section{Introduction}
%
% The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} package.
-% It consists of a style option (\texttt{rubikrotation.sty}) and a
-% Perl script (\texttt{rubikrotation.pl}).
+% It consists of a style option (\texttt{rubikrotation.sty}), a
+% Perl script (\texttt{rubikrotation.pl}) and some examples.
%
-% The primary role of the \rubikrotation\ package is to implement on-the-fly Rubik
-% rotation sequences using the \cmd{\RubikRotation} command. Consequently, this
+% The primary role of the \rubikrotation\ package is to implement a sequence of
+% Rubik rotation moves on-the-fly using the \cmd{\RubikRotation} command. Consequently, this
% package requires the use of the \texttt{--shell-escape} switch to allow
-% commandline control of the Perl script, which is really the `engine' of this package.
-% The \textsf{rubikrotation} package has been road-tested on a Microsoft
-% platform (with MikTeX and Strawberry Perl\,\footnote{`Strawberry Perl'
+% command-line control of the Perl script, which is really the `engine' of this package.
+%
+% The \rubikrotation\ package has been road-tested on a Microsoft
+% platform (with MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl'
% (\texttt{http://strawberryperl.com}) is a free Perl
% environment for MS Windows, designed to be as close as possible to the Perl
-% environment of Unix/Linux systems.})
-% and on a Linux platform ({\TeX}Live and Mandriva).
+% environment of Unix/Linux systems.}), on a Linux platform (Mandriva using
+% {\TeX}Live), and on a Solaris platform (OpenIndiana).
%
-% The following commands are made available by \texttt{rubikrotation.sty}.
+% The following commands are made available by \texttt{rubikrotation.sty}:
% \begin{quote}
% \begin{verbatim}
-% \RubikRotation{}
+% \RubikRotation[]{}
% \SaveRubikState
% \CheckRubikState
% \ShowRubikErrors
%\end{verbatim}
% \end{quote}
-% Note that if the Perl script is not located in the local working directory, then
-% some care is needed regarding placing it where your system can both find it and
-% also run it. In this case, the setting up of a simple one or two-line configuration
-% file may be useful or even necessary, depending on your system
-% (see section on `installation' below).
%
%
% \section{Requirements}
@@ -146,277 +157,403 @@
%
% Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it.
% This will generate the following files:
+%\begin{quote}
% \begin{verbatim}
% rubikrotation.ins
% rubikrotation.dtx
-% rubikrotation.sty
-% rubikrotation.pl
-% rubikrotation.PDF
-% example-rot1.tex
-% example-rot1.PDF
-% example-rot2.tex
-% example-rot2.PDF
-%\end{verbatim}
-% The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on
+% rubikrotation.pdf --this document
+% rubikrotation.pl --Perl script
+% rubikrotationPL.pdf --documentation of rubikrotation.pl
+% rubikrotation.1 --the man file
+% Rubikrot-doc-figA.pdf
+% Rubikrot-doc-figB.pdf
+% Rubikrot-doc-figC.pdf
+% Rubikrot-doc-figD.pdf
+% examples.tex
+% examples.pdf
+% examples.sh
+% examples.bat
+%\end{verbatim}
+%\end{quote}
+% Note that the package includes an `examples' file (\texttt{examples.tex})
+% as well as associated \texttt{.sh} (Linux) and \texttt{.bat} (Microsoft) batch
+% files which can be used to facilitate processing the file.
+% The main package documentation is the file \texttt{rubikrotation.pdf}.
+%
+% The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on
% the file \texttt{rubikrotation.ins} as follows:
+%\begin{quote}
%\begin{verbatim}
% pdflatex rubikrotation.ins
%\end{verbatim}
-% The documentation file (\texttt{rubikrotation.pdf}) was generated using the following
-% steps:
+%\end{quote}
+% The documentation file (\texttt{rubikrotation.pdf}) is then generated using the following
+% sequence of steps\,\footnote{Since the documentation includes a complicated indexing
+% system as well a \textsc{pdf} index and hyperef links (the package \texttt{hypdoc}
+% is used), then a lot of pdflatex runs are required. Prior to the first run it is
+% a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}:
+%\begin{quote}
% \begin{verbatim}
-% pdflatex --shell-escape rubikrotation.dtx
-% pdflatex --shell-escape rubikrotation.dtx
+% pdflatex rubikrotation.dtx
+% pdflatex rubikrotation.dtx
% makeindex -s gind.ist rubikrotation
% makeindex -s gglo.ist -o rubikrotation.gls rubikrotation.glo
-% pdflatex --shell-escape rubikrotation.dtx
+% pdflatex rubikrotation.dtx
+% pdflatex rubikrotation.dtx
%\end{verbatim}
+%\end{quote}
%
-
%
+%
% \subsection{Placing the files}
% \label{sec:placingfiles}
%
-% Place the files either in the local working directory, or where your system
-% will find them. For a Linux system with a standard \TeX\ Directory Structure (TDS), then:
+% Place the files either in a working directory, or where your system
+% will find them, e.g.,~in your \texttt{/texmf-local/} directory tree.
+% For example, on a Linux platform with a standard \TeX\ Directory Structure (TDS), then:
%
%\medskip
-%{\noindent}*.sty $\rightarrow$
-% \texttt{/usr/local/texlive/texmf-local/tex/latex/local/rubikrotation/}
-%{\newline}*.cfg $\rightarrow$
-% \texttt{/usr/local/texlive/texmf-local/tex/latex/local/rubikrotation/}
-%{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubikrotation/}
-%{\newline}*.pl $\rightarrow$ \texttt{/usr/local/bin/}
-%
-% \medskip
-% {\noindent}Finally, (depending on your system) update the \TeX\ file database using the
-% \texttt{texhash} command.
-
-%
-% \subsection{Configuration file}
-% \label{sec:configfile}
-%
-% A plane text configuration file with the name \texttt{rubikrotation.cfg} (if one exists)
-% will be read by the system. Such a file allows the user to
-% adjust (a)~the filename of the Perl script (\texttt{rubikrotation.pl})
-% and (b)~the commandline code used by \texttt{rubikrotation.sty} for calling the
-% Perl script. This sort of fine-tuning is sometimes convenient, and even necessary
-% (depending on your system), for locating and running the Perl script.
-% For example, on some systems it maybe preferable to use a different \textsc{path},
-% file name and/or a different commandline code to call the script.
+%{\noindent}*.sty $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/}
+%{\newline}*.cfg $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/}
+%{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubik/}
+%{\newline}*.pl $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/scripts/rubik/}
%
+%\medskip
+%{\noindent}\textsc{perl script}:\ \ Make the perl script executable
+% (\texttt{chmod +x rubikrotation.pl}), and then
+% rename the file as `rubikrotation' (i.e.,~with no file extension), and then place
+% the executable script into your current TeXLive binary directory,
+% e.g.,~\path!/user/local/texlive/YYYY/bin/i386-linux!.
+%
+% Sometimes the setting up of a simple one or two-line plain-text
+% configuration-file may be useful or even necessary, depending on your system
+% (see Section~\ref{sec:configfile} below). Such a file (if one exists) will
+% automatically be read by \texttt{rubikrotation.sty} providing the
+% file is named \texttt{rubikrotation.cfg}.
%
-% \DescribeMacro{\rubikperlname}
-% \DescribeMacro{\rubikperlcmd}
-% The configuration file is essentially a convenient software vehicle for feeding some
-% additional \LaTeX\ code to the style option, and hence allow the contents of some
-% commands to be adjusted and/or fine-tuned.
-% For the \rubikrotation\ package there are two particular commands we may wish to adjust.
-% The first is that defining the filename of the Perl script, namely
-% \cmd{\rubikperlname}. The second is that defining the commandline call,
-% namely \cmd{\rubikperlcmd}.
-% The default definitions for these (detailed in Section~\ref{sec:usefulcommands})
-% are as follows:
-%\begin{verbatim}
-% \newcommand{\rubikperlname}{rubikrotation.pl}
-% \newcommand{\rubikperlcmd}{perl \rubikperlname}
-%\end{verbatim}
+%\medskip
+%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this file
+% (\texttt{rubikrotation.1}) would be typically located in the
+% directory \verb!/usr/share/man/man1!.
%
+%\medskip
+%{\noindent}\textsc{file database}:\ \ Finally, (depending on your system) update the
+% \TeX\ file database.
+% For example, on a Linux platform this is achieved using the \texttt{texhash} command.
%
-% For example, we might wish to test out a slightly modified Perl script, say
-% with the name \texttt{rubikrotationV3.pl}. In this case we simply create,
-% in the local working directory, a plane text configuration file
-% (called \texttt{rubikrotation.cfg}) which includes the following line:
-%\begin{verbatim}
-%\renewcommand{\rubikperlname}{rubikrotationV3.pl}
+%\medskip
+%{\noindent}\textsc{quick test}:\ \ To test that your system can now run the perl
+% script, just type at the command-line
+%\begin{quote}
+% \begin{verbatim}
+% rubikrotation -h
%\end{verbatim}
-%
-% Alternatively, say, if the Perl script is being installed on a Linux platform, then
-% it would be standard to install it in the directory \texttt{/usr/local/bin}.
-% A convenient approach in this case, therefore, would be to indicate this new \textsc{path}
-% by including the following line in the configuration file:
-%\begin{verbatim}
-%\renewcommand{\rubikperlname}{/usr/local/bin/rubikrotation.pl}
-%\end{verbatim}
-% and, since this would then be an essentially permanent feature, we would then
-% place the configuration file with the style option in the
-% \texttt{texmf-local/...} directory as described in section~\ref{sec:placingfiles}
-% (placing files). Note that in this case, we have \textit{not} made the Perl script
-% `executable', since the default commandline code is effectively
-% \texttt{perl \rubikperlname}, and this works just as it is.
-%
-% However, if the Perl script \textit{is} made `executable', then
-% a different commandline code will have to be used instead.
-% For example, suppose the Perl script is made executable and renamed to just
-% \texttt{rubikrotation} (ie with no filename extension), then we now have to
-% omit the `perl' from the default commandline. Consequently, we now need to make
-% two command changes, which we implement by including the following
-% two lines in the configuration file:
-%\begin{verbatim}
-%\renewcommand{\rubikperlname}{/usr/local/bin/rubikrotation}
-%\renewcommand{\rubikperlcmd}{\rubikperlname}
+%\end{quote}
+% which should generate something like the following:
+% \begin{verbatim}
+% This is rubikrotation version 3.0
+% Usage: rubikrotation [-h] -i <input file> [-o <out file>]
+% where,
+% [-h] gives this help listing
+% [-i] creates specified input file
+% [-o] creates specified output file
+% For documentation see: rubikrotation.pdf,
+% rubikrotationPL.pdf and rubikcube.pdf
%\end{verbatim}
%
%
% \section{Usage}
-%
+% \label{sec:usage}
% Load the packages \texttt{rubikcube.sty}
-% and \texttt{rubikrotation.sty} in the \TeX\ file \textit{after} loading
-% the TikZ package, as follows:
-% \begin{verbatim}
-% \usepackage{tikz}
-% \usepackage{rubikcube,rubikrotation}
+% and \texttt{rubikrotation.sty} in the \TeX\ file preamble \textit{after} loading
+% the TikZ package (both Rubik packages require the TikZ package), for example, as follows:
+%\begin{quote}
+% \begin{verbatim}
+% \usepackage{tikz}
+% \usepackage{rubikcube,rubikrotation}
%\end{verbatim}
-% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} commandline switch
-% (see following section).
+%\end{quote}
+% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line switch
+% (see the following section).
%
%
% \subsection{Enabling the \TeX\ `shell' facility}
%
% In order to enable the \TeX\ `write18' facility (so it can run the Perl script)
-% we will need to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch; say, as follows.
+% it is necessary to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch
+% as follows:
+%\begin{quote}
% \begin{verbatim}
% pdflatex --shell-escape filename.tex
%\end{verbatim}
-% In practice, it is probably most convenient to run this via a
-% bash/batch file---something like the following, both of which
-% automatically show the graphic output:
+%\end{quote}
+% In practice, it is probably most convenient to run this command via a
+% bash/batch file. For example, on a Linux platform the following bash file
+% will run the file, show any errors, and open the \textsc{pdf} using AcrobatReader.
+%\begin{quote}
% \begin{verbatim}
% pdflatex --shell-escape filename.tex
-% xpdf filename.pdf
-%\end{verbatim}
-% or
-% \begin{verbatim}
-% latex --shell-escape filename.tex
-% dvips filename.dvi
-% gv filename.ps
+% echo "...checking error file"
+% grep ERROR ./rubikstateERRORS.dat
+% acroread filename.pdf &
%\end{verbatim}
+%\end{quote}
%
%
-% \subsection{Test files}
+% \subsection{Test file}
%
-% Two example tex files (which demonstrate the use of the package commands) are
-% included in the package, namely:
+% An example tex file (which demonstrates the use of some of the package commands)
+% is included in the package, namely:
+%\begin{quote}
% \begin{verbatim}
-% example-rot1.tex (shows 5 worked examples)
-% example-rot2.tex (is a `test' file for experimenting with different commands)
+% example-rot.tex (shows 8 worked examples)
%\end{verbatim}
-% These need to be run using \texttt{--shell-escape} switch; for example:
+%\end{quote}
+% This file needs to be run using \texttt{--shell-escape} switch; for example:
+%\begin{quote}
% \begin{verbatim}
-% pdflatex --shell-escape example-rot1.tex
+% pdflatex --shell-escape example-rot.tex
%\end{verbatim}
-% If the files give unexpected results, check-out the log file to see if the system
-% has had any difficulties finding files etc.
+%\end{quote}
+% Batch files (\texttt{.sh} for Linux, and \texttt{.bat} for Microsoft) are also provided
+% to facilitate running the `example' file.
+% For example, on a Linux platform one would run a \texttt{bash} file as follows:
+%\begin{quote}
+% \begin{verbatim}
+% bash example-rot.sh
+%\end{verbatim}
+%\end{quote}
+% If processing this file gives unexpected results (e.g.,~the cubes appear not to
+% have experienced any rotations) check-out the associated log file to see if
+% the operating system had any difficulties finding files etc.
+%
%
+% \subsection{Configuration-file}
+% \label{sec:configfile}
%
+% A plain-text configuration-file with the name \texttt{rubikrotation.cfg}
+% (if one exists) will automatically be read by \texttt{rubikrotation.sty}.
+% The \rubikrotation\ package's facility to use a configuration-file allows the
+% user to change not only (a)~the filename of the Perl script (\texttt{rubikrotation.pl}),
+% but also (b)~the command-line code used by \texttt{rubikrotation.sty} for calling the
+% Perl script. This~sort of fine-tuning can be very useful, and sometimes may
+% even be necessary (depending on your system) for running the Perl script.
%
+% For example, on some systems it maybe preferable to use a different \textsc{path},
+% file-name and/or a different command-line code to call the script.
+% Such~a configuration-file can also facilitate testing a new Perl script having
+% a different name and location.
+%
+%
+% \DescribeMacro{\rubikperlname}
+% \DescribeMacro{\rubikperlcmd}
+% The configuration-file is essentially a convenient software vehicle for feeding
+% additional \LaTeX\ code to the style option \texttt{rubikrotation.sty}, and hence
+% allows the contents of some commands to be easily adjusted and/or fine-tuned.
+% For~the \rubikrotation\ package there are two particular commands we may wish to adjust.
+% The~first is that defining the filename of the Perl script, namely
+% \cmd{\rubikperlname}. The second is that defining the command-line call,
+% namely \cmd{\rubikperlcmd}.
+% The~default definitions in \texttt{rubikrotation.sty} (which assume the Perl
+% script is executable), are as follows: (they are detailed in
+% Section~\ref{sec:usefulcommands})
+%\begin{quote}
+%\begin{verbatim}
+% \newcommand{\rubikperlname}{rubikrotation}
+% \newcommand{\rubikperlcmd}{\rubikperlname\space%
+% -i rubikstate.dat -o rubikstateNEW.dat}
+%\end{verbatim}
+%\end{quote}
+% Note the need here to use the \cmd{\space} command on the end of the backslash
+% command (\cmd{\rubikperlname}) in order to force a following
+% space---i.e.,~before the first command-line argument. The following examples
+% illustrate how the configuration-file may be used.
+%
+% \medskip
+% {\noindent}\textsc{example~1}:\ \ Suppose we wish to test out
+% a slightly modified Perl script
+% with the working (executable) name \texttt{rubikrotationR77}. In this case we
+% simply create, in the local working directory, a plain-text configuration-file
+% (called \texttt{rubikrotation.cfg}) which contains just the following line:
+%\begin{quote}
+%\begin{verbatim}
+%\renewcommand{\rubikperlname}{rubikrotationR77}
+%\end{verbatim}
+%\end{quote}
+%
+% \medskip
+% {\noindent}\textsc{example~2}:\ \ Alternatively, suppose we wish to test out
+% a new Perl script with the (non-executable) name \texttt{rubikrotationR55.pl}.
+% Now, in this particular case we will need to run the script using a
+% slightly different command, namely,
+% {\linebreak}\texttt{perl rubikrotationR55.pl ...}, and consequently we
+% need to implement both these changes in the configuration-file, as follows:
+%\begin{quote}
+%\begin{verbatim}
+%\renewcommand{\rubikperlname}{rubikrotationR55.pl}
+%\renewcommand{\rubikperlcmd}{perl \rubikperlname\space\%
+% -i rubikstate.dat -o rubikstateNEW.dat}
+%\end{verbatim}
+%\end{quote}
+%{\noindent}\textsc{placing the configuration-file}:\ \ The simplest arrangement is
+% just to include the \texttt{.cfg} file in the working `test' directory.
+% Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/}
+% directory tree (say, in \path!/usr/local/texlive/texmf-local/tex/latex/rubik/!),
+% but in this case one would then have to be careful to specify the
+% correct PATH for everything in order to enable your system to find all the
+% various components etc.
+%
+% Note that you can, of course, have several \texttt{.cfg} files, since the system will
+% read only one such file (the first one it finds starting with the current working
+% directory). Consequently, it may be useful to have one \texttt{.cfg} file in
+% your \texttt{/texmf-local/} dir (for running the standard Rubik package),
+% and another (different) \texttt{.cfg} file in your `test' directory.
+%
+%
% \section{Commands}
%
-% The \textit{only} commands which \textit{must} be used inside a TikZ picture
+% The \textit{only} `Rubik bundle' commands which \textit{must} be used inside a TikZ picture
% environment are the \cmd{\Draw...} commands (these are all provided by
% the \textsc{rubikcube} package), although most commands can be placed
-% inside a TikZ environment if necessary. However, using commands outside the environment
-% generally offers maximum flexibility, since the effects of commands used inside
-% a TikZ picture environment are `local' to that picture environment, and are not
-% therefore accessable outside the environment.
-%
-% The only command which must \textit{not}
-% be inside a TikZ environment is the \cmd{\ShowRubikErrors} command
+% inside a TikZ environment if you wish.
+%
+% However, using commands which influence the Rubik colour state
+% (e.g.,~the \cmd{\RubikRotation} command) outside the \texttt{tikzpicture},
+% \texttt{minipage} or \texttt{figure} environments
+% generally offers maximum flexibility, since the effects of such commands when
+% used inside these environments remain `local' to the environment, and are not
+% therefore accessable outside that \textit{particular} environment
+% (see also Section~4.1 in the \textsc{rubikcube} documentation).
+%
+% Conversely, the only \rubikrotation\ command which should \textit{not}
+% be used inside a TikZ environment is the \cmd{\ShowRubikErrors} command
% (see the notes on this command below).
%
%
-% \subsection{\cmd{\RubikRotation} command}
+% \subsection[RubikRotation command]{\cmd{\RubikRotation} command}
+% \label{sec:rubikrotationcmd}
%
% \DescribeMacro{\RubikRotation}
-% The \cmd{\RubikRotation}\marg{comma separated sequence} command processes
-% a comma separated sequence of rotations, and returns the final state.
+% The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence}
+% command processes a comma separated sequence of rotations, and returns
+% the final state. The optional \oarg{integer} argument specifies the number
+% of times the command should be repeated.
+%
% For example, if we wanted to see the effect of the rotations
% \textbf{R, R, L, U, D} on a solved Rubik cube, we could use the
% following commands.
+%\begin{quote}
% \begin{verbatim}
+% \RubikCubeSolved % sets up the colours for a solved cube state
+% \RubikRotation{R2,L,U,D}
% \begin{tikzpicture}[scale=0.7]
-% \RubikCubeSolved
-% \RubikRotation{R2,L,U,D}
% \DrawRubikCubeRU
-% \end{tikzpicture}
+% \end{tikzpicture}%
%\end{verbatim}
+%\end{quote}
% The \cmd{\RubikRotation} command results in \LaTeX\ first writing
% the current Rubik state to a text file (\texttt{rubikstate.dat}),
-% and then calling the Perl program \texttt{rubikrotation.pl}. The Perl
-% program then reads the current rubik state from the (\texttt{rubikstate.dat})
-% file, performs all the rotations, and then writes the new rubik state
+% and then calling the Perl script \texttt{rubikrotation.pl}. The Perl
+% script then reads the current Rubik state from the (\texttt{rubikstate.dat})
+% file, performs all the rotations, and then writes the new Rubik state
% (and any error messages) to the file \texttt{rubikstateNEW.dat},
-% which is then input on-the-fly by the \LaTeX\ file and used to generate
-% some graphic image of the cube.
-%
-% Note that the \cmd{\RubikRotation} command can be either inside
-% or before the Tikz picture environment. In fact only the `\cmd{\Draw...}'
-% commands (from the \textsc{rubikcube} package) actually need to be inside
-% a TikZ picture environment. Consequently this makes for great flexibility.
-%
-% \subsubsection{Arguments prefixed with a *}
-%
-% If any of the comma separated arguments (strings) is prefixed with a * it is
-% not processed as a rotation. This feature therefore allows a string argument
-% to be used as a label, which can be very useful.
-% For example, we can use the * feature to label the following
-% sequence as generating the so-called
-% `sixspot' configuration (described by Reid):
+% which is then input on-the-fly by the \LaTeX\ file. This new Rubik state
+% can then either used as the input for another \cmd{\RubikRotation}, or used
+% to generate a graphic image of the cube.
+%
+% A given rotation sequence can be repeated multiple times, say $n$ times, by
+% using the optional \verb![n]!. For example, the following two commands are equivalent:
+%\begin{quote}
% \begin{verbatim}
-% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+% \RubikRotation[3]{x,R,U}
+% \RubikRotation{x,R,U,x,R,U,x,R,U}
%\end{verbatim}
-% Alternatively, and probably more conveniently, we could simply use
-% the name `sixspot' to define a new command, as follows (which therefore allows
-% one to store lots of different rotation sequences by name alone):
+%\end{quote}
+%
+
+% \subsubsection{Sequences as macros}
+% \label{sec:seq-as-macros}
+%
+% Macros which are arguments of the \TeX\ \cmd{\write} command are expanded
+% on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see refs Section~\ref{sec:references}\,].
+% Consequently we are able to use a sequence-defining macro as an argument for
+% the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows
+% one to store lots of different rotation sequences by name alone.
+%
+% For example, we can use the name `sixspot' for a macro denoting the rotation sequence
+% which generates the well known `sixspot' configuration (see the `patterns' page on the
+% Reid website)[\,see refs Section~\ref{sec:references}\,], as follows:
+%\begin{quote}
% \begin{verbatim}
% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp}
%\end{verbatim}
-% With this `newcommand' we are now able to generate the graphic (sixspot cube)
-% much more easily using the following code:
+%\end{quote}
+% With this new \cmd{\sixspot} command we are now able to generate the graphic (sixspot cube)
+% very easily using the following code---this time we demonstrate the use of the more convenient
+% \cmd{\ShowCube} command (which includes the \texttt{tikzpicture} environment):
%
% \medskip
%
% \begin{minipage}{6cm}
% \begin{verbatim}
-% \begin{tikzpicture}[scale=0.7]
-% \RubikCubeSolved
-% \RubikRotation{\sixspot}
-% \DrawRubikCubeRU
-% \end{tikzpicture}
+% \RubikCubeSolved
+% \RubikRotation{\sixspot}
+% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU}
%\end{verbatim}
% \end{minipage}
% \begin{minipage}{3.4cm}
% \centering
% \ifpdf
-% \includegraphics[height=3cm]{Rubikrot_doc_figA.pdf}
+% \includegraphics[height=3cm]{Rubikrot-doc-figA.pdf}
% \else
% \fi
% \end{minipage}
%
-%
% \medskip
+% Providing such macros (when used as arguments) are comma separated (as the rotation codes
+% must be), then the \cmd{\RubikRotation} command can accommodate both rotation codes
+% and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!.
%
+%
+% \subsubsection{Arguments prefixed with *, [, ]}
+% \label{sec:prefixedargument}
+%
+% If any of the comma separated arguments is prefixed with either *, [ or ] they are
+% interpreted as an inactive `string', and not as a rotation. This feature therefore
+% allows a string argument to be used as a label, which can be very useful.
+%
+% For example, we can use this facility to label the `sixspot' configuration mentioned above,
+% as follows:
+%\begin{quote}
+% \begin{verbatim}
+% \RubikRotation{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp}
+%\end{verbatim}
+%\end{quote}
% In practice, it is quite useful to go one step further and include
-% the \texttt{*} label feature as well in the newcommand, as follows:
+% the [\,] label feature in the \cmd{\sixspot} command, as follows,
+%\begin{quote}
% \begin{verbatim}
-% \newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+% \newcommand{\sixspot}{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp}
%\end{verbatim}
-% since this has the great advantage of making the particular
-% rotation sequence identified by the label-name visible in the log file.
-% For example, the following command, which uses the rotations \textbf{x2}
+%\end{quote}
+% since this has the great advantage of making the label-name visible in the log file.
+% For example, the following command, which uses the rotations \textbf{x}, \textbf{x}
% and \textbf{y} to initially rotate the `solved' cube before applying
% the `sixspot' sequence of rotations,
+%\begin{quote}
% \begin{verbatim}
% \RubikRotation{x2,y,\sixspot}
%\end{verbatim}
+%\end{quote}
% will then be represented in the log file as
+%\begin{quote}
% \begin{verbatim}
-% ...command=rotation,x2,y,*sixspot,U,Dp,R,Lp,F,Bp,U,Dp
-% ...arguments passed to `rotation' sub = x2 y *sixspot U Dp R Lp F Bp U Dp (n= 11)
+% ...command=rotation,x2,y,[sixspot],U,Dp,R,Lp,F,Bp,U,Dp
+% ...arguments passed to `rotation' sub = x2 y [sixspot] U Dp R Lp F ...
% ...rotation x OK (= rrR + rrSr + rrLp)
% ...rotation x OK (= rrR + rrSr + rrLp)
% ...rotation y OK (= rrU + rrSu + rrDp)
-% ...*sixspot is a label OK
+% ...[sixspot] is a label OK
% ...rotation U OK
% ...rotation Dp OK
% ...rotation R OK
@@ -426,8 +563,60 @@
% ...rotation U OK
% ...rotation Dp OK
%\end{verbatim}
+%\end{quote}
% In this way, several named rotation sequences can be easily distinguished
-% in the log file from adjacent rotation commands.
+% in the log file from adjacent rotation sequences.
+% This feature is also useful when typesetting a sequence of rotation codes, since the first
+% element will then appear in the form \verb![name]!, obviating the need to typeset the
+% name of the sequence separately.
+%
+% To this end, the
+% \verb!ForEachX! macro---from the \verb!forarray! package---can be very useful.
+% For example, this macro is central to the following example macro for typesetting
+% a rotation sequence using the Rubik \cmd{\rr} command:
+%\begin{quote}
+%\begin{verbatim}
+%\def\x{\thislevelitem}
+%\def\xcount{\thislevelcount}
+%
+%\newcommand{\showseq}[1]{%
+% \ForEachX{,}{%
+% \ifthenelse{\xcount=1}{\texttt{\x}}{,\ \rr{\x}}%
+% }{#1}.
+%}
+%\end{verbatim}
+%\end{quote}
+% Now, for a sequence defined as |\newcommand{\myseq}{[myseq],U,D,Lwp,R}|, then
+% the command |\showseq{\myseq}| will result in the following output:
+%\begin{quote}
+% \texttt{[myseq]},\ \textbf{U},\ \textbf{D},\ \textbf{Lwp},\ \textbf{R}.
+%\end{quote}
+% Note that we are able to typeset the name \texttt{[myseq]} differently from the
+% remaining sequence since the counter \verb!\xcount! allows us to locate the first item.
+% However, this macro as it stands needs further development in order to handle
+% sequence elements with a terminal digit (e.g.,~\texttt{R2})---the macro will need
+% to first expand this to \texttt{R, R} if the Rubik commands are to be used.
+%
+% \subsubsection{Groups}
+%
+% The \cmd{\RubikRotation} command is a convenient tool for
+% illustrating how Rubik rotations and sequences of rotations are elements
+% of groups and subgroups.
+% For~example, using the \rubikrotation\ package it is easy to
+% show that three cycles of the `sixspot' sequence return the Rubik cube to its
+% original state. More formally this is equivalent to $($\cmd{\sixspot}$)3 \equiv 0$,
+% and can be nicely illustrated by implementing the following pseudocode:
+%\begin{verbatim}
+% \RubikCubeSolved . \RubikRotation[3]{\sixspot} = \RubikCubeSolved
+%\end{verbatim}
+%
+% \begin{minipage}{11cm}
+% \centering
+% \ifpdf
+% \includegraphics[width=10cm]{Rubikrot-doc-figC.pdf}
+% \else
+% \fi
+% \end{minipage}
%
%
% \subsubsection{Random rotations}
@@ -438,65 +627,78 @@
% is an integer $n$, ($1\leq n \leq 200$), then a random sequence
% of $n$ rotations will be performed; otherwise a default value
% of 50 is used (for example, if the second argument is not an integer).
-% If $n > 200$ then the value $n=200$ will be used.
-%
+% If $n > 200$ then the currently set maximum value $n=200$ will be used.
+%
+% As a safety feature the maximum $n$ can be changed only by editing the
+% set value of the Perl variable \verb!$maxn! in the Perl script
+% \texttt{rubikrotation.pl}, where (see line~583) we currently have
+%\begin{quote}
+%\begin{verbatim}
+% my $maxn=200;
+%\end{verbatim}
+%\end{quote}
+%
% For example, the following commands will scramble a solved cube using a
% sequence of 120 random rotations, and display the state in the form of
% a semi-flat cube.
%
-% \medskip
-%
-% \begin{minipage}{5.5cm}
-%\begin{verbatim}
-% \RubikCubeSolved%
-% \RubikRotation{random,120}%
-% \begin{tikzpicture}[scale=0.5]
-% \DrawRubikCubeFlat
-% \end{tikzpicture}
-%\end{verbatim}
-% \end{minipage}
+
% \begin{minipage}{3.4cm}
% \centering
% \ifpdf
-% \includegraphics[height=4cm]{Rubikrot_doc_figB.pdf}
+% \includegraphics[height=4cm]{Rubikrot-doc-figB.pdf}
% \else
% \fi
% \end{minipage}
+% \begin{minipage}{6cm}
+% \vspace{1.6cm}
+%\begin{verbatim}
+% \RubikCubeSolved%
+% \RubikRotation{random,120}%
+% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeFlat}
+%\end{verbatim}
+% \end{minipage}
%
% Note that in this particular example (above), only
-% the \cmd{\Draw..} command is inside the TikZ picture environment---a useful
-% method when more than one figure is being drawn. Note also, that when such
+% the \cmd{\Draw..} command is inside the TikZ picture environment (i.e.,~inside
+% the \cmd{\ShowCube} command). Note also that when Rubik
% commands are outside a TikZ picture environment, they should have a
% trailing \% to stop additional white space being included.
%
% \medskip
%
-% The procedure is that all the possible rotations are first allocated
-% a different number (integer) and collected into an array. Then a
-% sequence of $n$ randomised numbers is generated and mapped to the array
-% to generate the associated sequence of random rotations.
+% The randomisation procedure is as follows: all the possible rotations are first allocated
+% a different cardinal number (positive integer) and collected into an array.
+% Then a sequence of $n$ randomised numbers is generated and mapped to
+% the array to generate the associated sequence of random rotations.
% The sequence used is detailed in the \texttt{.log} file.
%
%
-% \subsection{\cmd{\SaveRubikState}}
+% \subsection[SaveRubikState]{\cmd{\SaveRubikState} command}
+% \label{saverubikstate}
%
% \DescribeMacro{\SaveRubikState}
% The command \cmd{\SaveRubikState}\marg{filename} saves the state (configuration)
% of the Rubik cube to the file \marg{filename} in the standard \cmd{\RubikFace...}
-% format. Consequently such a file can then be input at a later stage so it can be
-% drawn or processed in the usual way (inside the TikZ picture environment).
+% format so that it can be read by \LaTeX. Consequently such a file can then be input
+% so it can be drawn or processed in the usual way. The output file is `closed' immediately
+% following the `write' in order to allow it to be available for input later by the same
+% file if required.
%
% For example, the following commands would save the so-called `sixspot' configuration
% (generated by the rotations \textbf{U, Dp, R, Lp, F, Bp, U, Dp})
% to the file \verb!sixspot.tex!.
+%\begin{quote}
%\begin{verbatim}
% \RubikCubeSolved%
% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}%
% \SaveRubikState{sixspot.tex}%
%\end{verbatim}
+%\end{quote}
% The form of the file \verb!sixspot.tex! will then be as follows---the
% filename (commented out) is automatically written to the top of the
% file for convenience.
+%\begin{quote}
%\begin{verbatim}
% % filename: sixspot.tex
% \RubikFaceUp{O}{O}{O}{O}{W}{O}{O}{O}{O}%
@@ -506,75 +708,81 @@
% \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}%
% \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}%
%\end{verbatim}
+%\end{quote}
% We can therefore access and draw this configuration later, when required,
% simply by inputting the file as follows:
+%\begin{quote}
%\begin{verbatim}
-%\begin{tikzpicture}
-% \input{sixspot.tex}
-% \DrawRubikCubeFlat
-%\end{tikzpicture}
+%\input{sixspot.tex}
+%\ShowCube{7cm}{0.7}{\DrawRubikCubeFlat}
%\end{verbatim}
+%\end{quote}
%
%
-% \subsection{\cmd{\CheckRubikState} command}
+% \subsection[CheckRubikState]{\cmd{\CheckRubikState} command}
%
% \DescribeMacro{\CheckRubikState}
% Since it is easy to inadvertently define an invalid Rubik cube
-% (eg enter an invalid number of, say, yellow cubies), this command
+% (e.g.,~enter an invalid number of, say, yellow facelets), this command
% checks the current colour state of all the cubies
-% of a 3x3x3 Rubik cube, and shows the number of cubies of each colour.
-% An ERROR: code is issued if the number of cubies having a given colour exceeds 6.
+% of a 3x3x3 Rubik cube, and shows the number of facelets of each colour.
+% An ERROR: code is issued if the number of facelets having a given colour exceeds~6.
% The results are written to the the \texttt{.log} file, and displayed under
% the graphic if the \cmd{\ShowRubikErrors} command is used.
%
% One can check the current Rubik state (for errors) by issuing the command
+%\begin{quote}
%\begin{verbatim}
% \CheckRubikState%
%\end{verbatim}
+%\end{quote}
% Note that such a check is implemented automatically with each \cmd{\RubikRotation} command.
%
%
%
%
-% \subsection{\cmd{\ShowRubikErrors} command}
+% \subsection[ShowRubikErrors]{\cmd{\ShowRubikErrors} command}
%
% \DescribeMacro{\ShowRubikErrors}
-%
% Any errors which arise can be made visible using the
% command \cmd{\ShowRubikErrors}.
% This command places a copy of the `error' file (\texttt{rubikstateERRORS.dat})
-% underneath the image so you can see any errors if there are any---all this
+% underneath the graphic image so you can see any errors if there are any---all this
% detail can also be found in the \texttt{.log} file.
%
% Consequently, this command must be placed \textit{after} a TikZ picture
% environment---it cannot be used inside a TikZ environment. In fact this command
% is probably best placed at the end of the document (if there are several such
% environments), where it will reveal all rotation errors generated while
-% processing the document.
-%
+% processing the whole document.
+% Once the document is free of errors this command can be removed or just commented out.
+% Run the test file \texttt{example-rot.tex} to see an example of the use of this command.
%
% \section{Files generated}
%
%
% Whenever the \cmd{\RubikRotation} or \cmd{\CheckRubikState} commands are used,
-% three small temporary plain text files for holding data are generated as
+% three small temporary plain-text files for holding data are generated as
% follows (they are refreshed with each \LaTeX\ run, and are not actively deleted).
% \begin{itemize}
% \item \LaTeX\ writes Rubik state data to the file \texttt{rubikstate.dat}.
%
-% \item Perl reads the file \texttt{rubikstate.dat} and then writes
+% \item The Perl script \texttt{rubikrotation.pl} reads the file
+% \texttt{rubikstate.dat} and then writes
% the new rubik state to the file \texttt{rubikstateNEW.dat}.
%
-% \item Perl also writes error data to the file \texttt{rubikstateERRORS.dat}.
-% A copy of this file is displayed under the image when the command
-% \cmd{\ShowRubikErrors} is used after (outside) the TikZ picture environment.
+% \item The Perl script \texttt{rubikrotation.pl} also writes error data
+% to the file \texttt{rubikstateERRORS.dat}. A copy of this file is displayed
+% under the graphic image when the command
+% \cmd{\ShowRubikErrors} is used after the TikZ picture environment.
%
% \end{itemize}
%
%
% \section{General overview}
-%
-% When \LaTeX\ loads the \rubikrotation\ package the following steps are implemented.
+% \label{generaloverview}
+% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps
+% are implemented.
% \begin{itemize}
%
%
@@ -582,13 +790,13 @@
% then this package is loaded if it is available (this package is required
% for inputting the file \texttt{rubikstateERRORS.dat}).
%
-% \item[2.] A check is made to see if a configuration file (\texttt{rubikrotation.cfg})
+% \item[2.] A check is made to see if a configuration-file (\texttt{rubikrotation.cfg})
% exists: if so then this file is input.
%
% \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists):
% otherwise the file is created (this prevents an `old' file being used by \LaTeX).
%
-% \item[4.] The plain text file \texttt{rubikstateERRORS.dat} is created.
+% \item[4.] The plain-text file \texttt{rubikstateERRORS.dat} is created.
% This file collects error messages generated by the Perl script.
%
% \end{itemize}
@@ -597,13 +805,14 @@
% When a \cmd{\RubikRotation} command is processed it first writes the current
% colour configuration of each face (the `rubik state') to the temporary file
% \texttt{rubikstate.dat} (to be read by the Perl script \texttt{rubikrotation.pl}).
-% The \cmd{\RubikRotation} command also appends the keyword `
-% \texttt{checkrubik}' as well as a copy of the string of Rubik rotations.
-% It then calls the Perl script \texttt{rubikrotation.pl}.
+% The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}'
+% as well as a copy of the string of Rubik rotations.
+% It~then calls the Perl script \texttt{rubikrotation.pl}.
%
% For example, if we use the command \cmd{\RubikCubeSolved}
-% followed by the command \verb!\RubikRotation{U,D,L,R}! then the associated
+% followed by the command \verb!\RubikRotation[2]{U,D,L,R}!, then the associated
% \texttt{rubikstate.dat} file would be as follows:
+%\begin{quote}
% \begin{verbatim}
% % filename: rubikstate.dat
% up,W,W,W,W,W,W,W,W,W
@@ -614,39 +823,141 @@
% back,R,R,R,R,R,R,R,R,R
% checkstate
% rotation,U,D,L,R
+% rotation,U,D,L,R
%\end{verbatim}
-% Alternatively, if the \cmd{\RubikRotation} command was
+%\end{quote}
+% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the line \texttt{rotation,U,D,L,R}
+% being written twice to the \texttt{rubikstate.dat} file, as shown above.
+%
+% Alternatively, if we used the command
% \verb!\RubikRotation{random, 45}! then the last line written to the file
-% would be the string `\texttt{rotation,random,45}'
+% would be the string `\texttt{rotation,random,45}', as follows:
+%\begin{quote}
+% \begin{verbatim}
+% % filename: rubikstate.dat
+% up,W,W,W,W,W,W,W,W,W
+% down,Y,Y,Y,Y,Y,Y,Y,Y,Y
+% left,B,B,B,B,B,B,B,B,B
+% right,G,G,G,G,G,G,G,G,G
+% front,O,O,O,O,O,O,O,O,O
+% back,R,R,R,R,R,R,R,R,R
+% checkstate
+% rotation,random,45
+%\end{verbatim}
+%\end{quote}
% A \cmd{\CheckRubikState} command triggers the same sequence of events except
% no `rotation' line is written.
%
-% The action of the Perl program is controlled by the keywords (first argument of
+% The action of the Perl script \texttt{rubikrotation.pl} is controlled by
+% the keywords (first argument of
% each line) associated with each line of the file \texttt{rubikstate.dat}.
-% When control passes to Perl, the Perl program starts by loading the
-% rubikstate (prompted by the keywords up, down,
-% left, right, front, back). Next the program performs
-% some basic checks (prompted by the key word `checkstate'), and then it processes
-% the sequence of Rubik rotations (prompted by the keyword `rotation').
-% If, instead, the second argument of the `rotation' string is the keyword `random', and
-% provided this is followed by a valid integer, say $n$, then the Perl program performs
-% a sequence of $n$ random rotations.
-% Finally, the Perl program writes the final `rubikstate' to the text file
+% When control passes to Perl, the script \texttt{rubikrotation.pl} starts
+% by loading the current rubikstate (prompted by the keywords \texttt{up}, \texttt{down},
+% \texttt{left}, \texttt{right}, \texttt{front}, \texttt{back}, in the file
+% \texttt{rubikstate.dat}). Next the Perl script
+% performs some basic checks (prompted by the key word \texttt{checkstate}), and
+% then it processes the sequence of Rubik rotations (prompted by the keyword
+% \texttt{rotation}). If, instead, the second argument of the `rotation' string
+% is the keyword `random', and provided this is followed by a valid integer, say $n$,
+% then the Perl script performs a sequence of $n$ random rotations.
+% Finally, the Perl script writes the final `rubikstate' to the text file
% \texttt{rubikstateNEW.dat}. All error messages are written to the
% text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log file.
%
% Control then reverts to \LaTeX\ which then inputs the file
% \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands
-% then this cycle repeats accordingly. Eventually a `\texttt{Draw...}' command
+% then this cycle repeats accordingly. Eventually a \cmd{\Draw...} command
% of some form is reached and the final rubikstate is drawn in a TikZ picture
% environment.
%
% If the TikZ picture environment is followed by a \cmd{\ShowRubikErrors} command,
% then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed
% immediately under the graphic. Once the graphic is error-free, then the
-% \cmd{\ShowRubikErrors} can be removed or commented out.
+% \cmd{\ShowRubikErrors} command can be removed or commented out.
+%
+% Note that if a \textsc{bash} file is used to coordinate the process then it is often
+% convenient to use the linux \texttt{grep} utility to alert the user to any run-time errors,
+% by using \texttt{grep} to scan the \texttt{rubikstateERRORS.dat} file at the end of
+% the run; for example, as follows:
+%\begin{quote}
+%\begin{verbatim}
+% pdflatex --shell-escape myfile.tex
+% echo "...checking error file"
+% grep ERROR ./rubikstateERRORS.dat
+%\end{verbatim}
+%\end{quote}
+%
+%
+% \section{References}
+% \label{sec:references}
+%
+%\begin{itemize}
+%
+% \item Abrahams PW, Berry K and Hargreaves KA (1990). \textit{\TeX\ for the impatient}
+% (Addison-Wesley Publishing Company), page~292.
+% {\newline}Available from: \url{http://www.ctan.org/pkg/impatient}
+% {\newline}[\,re:~\cmd{\rubikpercentchar} and \cmd{\@comment} in Section~\ref{sec:abrahams}\,]
+%
+%
+% \item Eijkhout V (1992). \textit{\TeX\ by topic: a {\TeX}nician's reference}.
+% (Addison-Wesley Publishing Company), pages~232 \&~238.
+% {\newline}Available from: \url{https://bitbucket.org/VictorEijkhout/tex-by-topic/}
+% [\,re:~\cmd{\string} in Section~\ref{sec:eijkhout}\,]
+% [\,re:~\cmd{\write} in Section~\ref{sec:seq-as-macros}\,]
+%
+%
+% \item Feuers\"{a}nger C (2015). Notes on programming in \TeX.
+% {\newline}(revision: 1.12.1-32-gc90572c; 2015/07/29)
+% \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf}
+% {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,]
+%
+%
+% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package.
+% \newline\url{http://www.ctan.org/pkg/rubik},
+%
+% \item Reid M. \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html}
+% {\newline}[\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,]
+%
+%\end{itemize}
+%
+%
%
+% \section{Change history}
%
+% \begin{itemize}
+% \item Version 3.0 (25 September 2015)
+%
+% --- The \cmd{\RubikRotation} command now actions multiple instances of its argument
+% as determined by an optional `repeat' \oarg{integer}. For example the command
+% \cmd{\RubikRotation[3]\{R,x\}} is equivalent to the command \cmd{\RubikRotation\{R,x,R,x,R,x\}}
+% (see Sections~\ref{sec:rubikrotationcmd} and \ref{sec:rubikrotationcode}).
+%
+% --- If a comma separated element used as an argument for the \cmd{\RubkRotation}
+% command is prefixed with either a * or [ or ] character then it is not actioned
+% as a rotation (see Section~\ref{sec:prefixedargument}).
+%
+% --- The Perl script \texttt{rubikrotation.pl} now has command-line switches,
+% including \texttt{-h} to show some `help' and `usage' information
+% (see Section~\ref{sec:placingfiles}).
+%
+% --- A `man' file for the Perl script \texttt{rubikrotation.pl} is now included in the package.
+%
+% --- The Perl script \texttt{rubikrotation.pl} now uses as input and output filenames
+% those specified in the command-line of the CALLing program. This now allows the
+% script \texttt{rubikrotation.pl} to be used as a stand-alone tool (see the
+% \texttt{rubikrotation} `man' file for details).
+%
+% --- The documentation for the Perl script \texttt{rubikrotation.pl} is in the
+% accompanying file \texttt{rubikrotationPL.pdf}.
+%
+% --- Fixed typos, index and minor errors in the documentation.
+%
+%
+% \item Version 2.0 (5 February, 2014)
+%
+% --- First release.
+%
+% \end{itemize}
%
% ^^A ==================================================
% \StopEventually{\PrintIndex}
@@ -654,21 +965,27 @@
%
%
% \section{The code (\texttt{rubikrotation.sty})}
-%
+%
+% {\noindent}In the following, the term `Perl script' denotes the script
+% \texttt{rubikrotation.pl}. Useful information regarding the
+% \TeX\ \cmd{\write} command is given in Eijkhout (1992), \S\,30.2.3 (page~238).
+% For the means of including a `\%' character in the token list of \cmd{\write} see
+% Abrahams \textit{et.~al} (1990).
+%
% \subsection{Package heading}
%
% \begin{macrocode}
%<*rubikrotation>
-\def\RRfileversion{2.0}%
-\def\RRfiledate{2014/01/20}%
+\def\RRfileversion{3.0}%
+\def\RRfiledate{2015/09/25}%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)]
% \end{macrocode}
%
%
-% {\noindent}The package requires rubikcube.sty. Do not automatically
-% load rubikcube.sty since this makes it difficult to errorcheck new
-% versions (for the moment at least).
+% {\noindent}The package requires \texttt{rubikcube.sty}. However \texttt{rubikcube.sty}
+% is not automatically loaded (for the moment at least) since this makes it difficult
+% to errorcheck new versions.
% \begin{macrocode}
\@ifpackageloaded{rubikcube}{}{%
\typeout{---rubikrotation requires the rubikcube package.}%
@@ -678,23 +995,34 @@
%
%
% {\noindent}The \rubikrotation\ package requires access to the fancyvrb package
-% for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying
-% the error file.
+% for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying
+% the error file (see Section~\ref{sec:showrubikerrors}).
% \begin{macrocode}
\@ifpackageloaded{fancyvrb}{}{%
\typeout{---rubikrotation requires the fancyvrb package%
for VerbatimInput{} command.}%
\RequirePackage{fancyvrb}}
% \end{macrocode}
-% \medskip
%
+% \medskip
%
-%\subsection{Some useful commands}
-% \label{sec:usefulcommands}
+% \subsection{Some useful commands}
+% \label{sec:usefulcommands}
+%
% \begin{macro}{\rubikrotation}
% First we create a suitable logo
% \begin{macrocode}
-\newcommand{\rubikrotation}{\textsf{rubikrotation}}
+\newcommand{\rubikrotation}{\textsc{rubikrotation}}
+\newcommand{\Rubikrotation}{\textsc{Rubikrotation}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@print}
+% We need a simple print command to facilitate writing output to a file.
+% \begin{macrocode}
+\newcommand{\@print}[1]{\immediate\write\outfile{#1}}
% \end{macrocode}
% \end{macro}
%
@@ -702,11 +1030,17 @@
%
% \begin{macro}{\@comment}
% \begin{macro}{\@commentone}
-% We require access to the percent character so we can write comments
-% in files, including the log file.
-% We first define percentchar for the write statement
-% (From Abrahams PW, Berry K and Hargreaves KA (1990), ``TeX for the Impatient'', p~292;
-% available from: CTAN.../info/impatient/)
+% We also require access to the `\%' character so we can (a)~write comments to
+% files, including the log file, and (b)~place a trailing `\%' in a line of code
+% written to a file.
+%
+% To achieve this we define the `\%' character as \cmd{\rubikpercentchar}
+% (modified from: Abrahams PW, Berry K and Hargreaves KA (1990), p~292)
+% [see refs Section~\ref{sec:references}]\label{sec:abrahams},
+% and also two `comment' commands which implement it. This `workaround'
+% is necessary because \TeX\ does not allow the use of the \cmd{\%} command
+% for placing a `\%' character in the token list of \cmd{\write}.
+% See Abrahams \textit{et.~al} (1990) for details.
% \begin{macrocode}
{\catcode`\%=12 \global\def\rubikpercentchar{%}}%
\newcommand{\@comment}{\rubikpercentchar\rubikpercentchar\space}%
@@ -716,39 +1050,50 @@
% \end{macro}
%
%
-% \begin{macro}{\@print}
-%% We need a simple print command for writing comments to a file.
-% \begin{macrocode}
-\newcommand{\@print}[1]{\immediate\write\outfile{#1}}
-% \end{macrocode}
-% \end{macro}
-%
-%
%
% \begin{macro}{\rubikperlname}
-% This holds the name of the Perl-5 script . It is used later to check
-% whether the Perl script exists or not. A plain text configuration file
-% \verb!rubikrotation.cfg! can be used to change the default name of the
-% Perl script using a renewcommand.
+% This holds the name of the Perl script. A configuration-file
+% (\verb!rubikrotation.cfg!) can be used to change the default name of the
+% Perl script using a renewcommand (see Section~\ref{sec:configfile}).
% \begin{macrocode}
-\newcommand{\rubikperlname}{rubikrotation.pl}
+\newcommand{\rubikperlname}{rubikrotation}
% \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\rubikperlcmd}
-% This holds the commandline code for calling the the Perl script.
-% A plain text configuration file \verb!rubikrotation.cfg! can be used to
-% change the default commandline code using a renewcommand.
+% This holds the command-line code for calling the Perl script
+% (assumed to be an executable file).
+% Note that the command-line requires a mandatory input filename preceded
+% by the \texttt{-i}~switch. An optional output filename (preceded by the
+% \texttt{-o}~switch) may be used, otherwise the default output filename of
+% \texttt{rubik-OUT.dat} will be used.
+%
+% Note that it is very important that this .sty file actually specifies an
+% output filename (for receiving data from the Perl script). This is because
+% (a)~The Perl script \texttt{rubikrotation.pl} is currently configured to read its
+% output filename as an argument from the command-line (so it can be flexibly
+% used as a stand-alone script for processing a given Rubik state through a
+% sequence of rotations), and (b)~\texttt{rubikrotation.sty} is currently
+% configured to read its input from the file \texttt{rubikstateNEW.dat}.
% \begin{macrocode}
-\newcommand{\rubikperlcmd}{perl \rubikperlname}
+\newcommand{\rubikperlcmd}{\rubikperlname\space%
+ -i rubikstate.dat -o rubikstateNEW.dat}
% \end{macrocode}
+% Remember to use the \cmd{\space} command following the \LaTeX\ backslash
+% command in order to generate the mandatory space between it and the first
+% command-line argument).
+%
+% A plain-text configuration-file \verb!rubikrotation.cfg! can be used to
+% change the default command-line code using a renewcommand
+% (see Section~\ref{sec:configfile}).
% \end{macro}
%
%
-%\subsection{Configuration file}
-% If a config file exists (rubikrotation.cfg) then input it here,
-% ie \textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd}
+% \subsection{Configuration file}
+%
+% If a configuration file exists (\texttt{rubikrotation.cfg}) then input it here,
+% i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd}
% commands and \textit{before} creating the \texttt{rubikstateERRORS.dat} file.
% \begin{macrocode}
\typeout{---checking for config file (rubikrotation.cfg)...}
@@ -761,71 +1106,61 @@
%
% \subsection{Clean file rubikstateNEW.dat}
%
-% {\noindent}We need to clean any existing (old) rubikstateNEW.dat file,
-% since if the TeX shell switch is accidentally not used then Perl will
-% not be CALLed and hence this file will not be renewed
-% (ie an `old' image may be used).
+% {\noindent}We need to clean out any existing (old) rubikstateNEW.dat file,
+% since if the TeX shell command-line switch is accidentally not used then the Perl script
+% \texttt{rubikrotation.pl} will not be CALLed, and hence this file will not be renewed
+% (i.e.,~an `old' image may be used).
% \begin{macrocode}
\typeout{---cleaning file rubikstateNEW.dat}%
\newwrite\outfile%
\immediate\openout\outfile=rubikstateNEW.dat%
-\@print{\@comment rubikstateNEW.dat (by TeX)}%
+\@print{\@comment rubikstateNEW.dat}%
\immediate\closeout\outfile%
% \end{macrocode}
%
%
% \subsection{rubikstateERRORS.dat}
%
-% {\noindent}The \rubikrotation\ package requires the Perl program.
-% We first open the file \texttt{rubikstateERRORS.dat} which is used
-% by the Perl program (\texttt{rubikrotation.pl}) for writing its error
-% messages to. This file is accessed and displayed by the command
+% {\noindent}We first open the file \texttt{rubikstateERRORS.dat} which is used
+% by the Perl script \texttt{rubikrotation.pl} for writing its error-messages to.
+% This file is displayed by the command
% \cmd{\ShowRubikErrors}.
%
-% \textsc{important note}: this file is created fresh each time LaTeX is run
-% and hence the Perl program only appends data to it during the \LaTeX\ run,
-% so this file just grows until either it is destroyed or recreated---a useful
-% feature to keep since the file accumulates all error messages as the
-% .tex file is processed.
-% We can't make the Perl program create the file since the Perl program is only
+% \textsc{important note}: this file is created fresh each time LaTeX is run,
+% and hence the Perl script only appends data to it during the \LaTeX\ run,
+% so this file just grows until either it is destroyed or recreated---this is
+% a useful feature since the file accumulates all error messages as the
+% \texttt{.tex} file is processed.
+% We can't make the Perl script create the file since the Perl script is only
% CALLed if we use a \cmd{\RubikRotation} or \cmd{\CheckRubikState}
-% command (which we may not!)---so it has to be created (opened) here.
-%
-% The following code first opens the file, and then checks to see if
-% the Perl program (\cmd{\rubikperlname}) exists;
-% if the Perl prog does exist then all is OK,
-% otherwise we write an error message to the file.
+% command (which we may not\,!)---so it has to be created here.
% \begin{macrocode}
\typeout{---creating file rubikstateERRORS.dat}%
\newwrite\outfile%
\immediate\openout\outfile=rubikstateERRORS.dat%
\@print{\@comment rubikstateERRORS.dat}%
-\typeout{---checking for Perl script \rubikperlname...}
- \IfFileExists{\rubikperlname}{%
- \typeout{---\rubikperlname\space exists OK}%
- }{\typeout{** ERROR: cannot find Perl program \rubikperlname}%
- \@print{\@comment ** ERROR: cannot find Perl program \rubikperlname}}%
+\@print{\@comment ---(RR.sty v\RRfileversion): comments output by Perl script}%
\immediate\closeout\outfile%
% \end{macrocode}
%
%
-% \subsection{Setting up a newwrite and file-access for new files}
+% \subsection{Setting up file-access for new files}
%
% Having set up all the primary files, we now need to set up a newwrite for
-% all subsequent files openings (eg for rubikstate.dat and saving
+% all subsequent file openings (e.g.,~for \texttt{rubikstate.dat} and saving
% to arbitrary filenames by the \cmd{\SaveRubikState} command). Otherwise, we
-% can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use openout7
-% when opening and writing to files. We will implement new openings using
-% the command \verb!\@openstatefile! (see below).
+% can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use
+% \texttt{openout7} when opening and writing to files. We will implement new
+% openings using the command \verb!\@openstatefile! (see below).
% \begin{macrocode}
-\typeout{---setting up newwrite for rubikrotation to use...}%
+\typeout{---setting up newwrite for rubikrotation.sty to use...}%
\newwrite\outfile%
% \end{macrocode}
%
%
% \begin{macro}{\@openstatefile}
% \begin{macro}{\@closestatefile}
-% We also need commands for easy file opening and and closing
+% We also need commands for easy file opening and closing
% for new instances of the file \texttt{rubikstate.dat} etc.
% Note that for this we are therefore using the same outfile number as set up
% by the \verb!\newwrite...! above.
@@ -840,12 +1175,19 @@
% \subsection{Saving the Rubik state}
%
% \begin{macro}{\@printrubikstate}
-% This command writes the Rubik configuration (state) to
-% the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command.
-% The file \texttt{rubikstate.dat} is read by the Perl program, and represents
+% This internal command writes the Rubik configuration to
+% the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command
+% (see Sections~\ref{saverubikstate} and \ref{generaloverview}).
+% The file \texttt{rubikstate.dat} is read by the Perl script, and represents
% the state on which the new \cmd{\RubikRotation} command acts.
% Note that we append the key-word \texttt{checkstate} to the end of the file
-% in order to trigger the Perl program to implement its \texttt{checkstate} subroutine.
+% in order to trigger the Perl script to implement its \texttt{checkstate} subroutine.
+%
+% The actual state is simply an ordered sequence of the faces and the colours
+% associated with each facelet of that face. The colour associated with a particular facelet
+% is held by the variable for that facelet. For example, the top-left facelet associated with
+% the \textsc{front} face is held in the variable \cmd{\Flt} (see Section~\ref{saverubikstate}).
+% Further relevant documentation is in the \textsc{rubikcube} package.
% \begin{macrocode}
\newcommand{\@printrubikstate}{%
\@print{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}%
@@ -860,43 +1202,123 @@
% \end{macro}
%
%
+% \subsection{SaveRubikState command}
+% \label{sec:eijkhout}
+%
+% \begin{macro}{\SaveRubikState}
+% The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state
+% to a named file in the format of a Rubik command (so it can then be processed
+% by \LaTeX). Note that in order to actually write a LaTeX
+% command to a file without a trailing space one must prefix the command with the
+% \cmd{\string} command (see Eijkhout (1992), p~238)
+% [see refs Section~\ref{sec:references}]\label{sec:eijkhout}.
+%
+% Note that this macro uses the internal commands \cmd{\@comment} (`\%\%'),
+% \cmd{\@commentone} (`\%') and \cmd{\@print}. \#1 is the output filename.
+% We use several \cmd{\typeout} commands to write to the log file.
+% An example of the line of code we are trying to output to the
+%\texttt{rubikstateNEW.dat} file is as follows:
+% {\newline}\verb!\RubikFaceUp{W}{W}{G}{W}{W}{G}{B}{B}{Y}%!
+% \begin{macrocode}
+\newcommand{\SaveRubikState}[1]{%
+\typeout{---NEW save command------------------}%
+\typeout{---command = SaveRubikState{#1}}%
+\typeout{---saving Rubik state data to file #1}%
+\immediate\openout\outfile=#1%
+\@print{\@comment filename: #1\@commentone}%
+\@print{\string\RubikFaceUp%
+ {\Ult}{\Umt}{\Urt}{\Ulm}{\Umm}{\Urm}{\Ulb}{\Umb}{\Urb}\@commentone}%
+\@print{\string\RubikFaceDown%
+ {\Dlt}{\Dmt}{\Drt}{\Dlm}{\Dmm}{\Drm}{\Dlb}{\Dmb}{\Drb}\@commentone}%
+\@print{\string\RubikFaceLeft%
+ {\Llt}{\Lmt}{\Lrt}{\Llm}{\Lmm}{\Lrm}{\Llb}{\Lmb}{\Lrb}\@commentone}%
+\@print{\string\RubikFaceRight%
+ {\Rlt}{\Rmt}{\Rrt}{\Rlm}{\Rmm}{\Rrm}{\Rlb}{\Rmb}{\Rrb}\@commentone}%
+\@print{\string\RubikFaceFront%
+ {\Flt}{\Fmt}{\Frt}{\Flm}{\Fmm}{\Frm}{\Flb}{\Fmb}{\Frb}\@commentone}%
+\@print{\string\RubikFaceBack%
+ {\Blt}{\Bmt}{\Brt}{\Blm}{\Bmm}{\Brm}{\Blb}{\Bmb}{\Brb}\@commentone}%
+\immediate\closeout\outfile%
+\typeout{-----------------------------------------}%
+}%
+% \end{macrocode}
+% \end{macro}
+%
+%
% \subsection{RubikRotation command}
+% \label{sec:rubikrotationcode}
%
% \begin{macro}{\RubikRotation}
-% The \cmd{\RubikRotation}\marg{comma separated sequence}
-% command (a)~writes the current Rubik state to the file
-% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl program.
-% It also writes comments to the data file and also to the log file.
+% The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence}
+% command (a)~writes the current Rubik state to the file \texttt{rubikstate.dat},
+% (b)~writes the rotation sequence (either once or multiple times depending
+% on the value of the optional integer argument), and then (c)~CALLs the
+% Perl script \texttt{rubikrotation.pl}. It~also writes comments to the
+% data file and also to the log file.
+%
+% In order to allow the user to (optionally) write the main argument multiple
+% times to the output data-file, we require this command to allow an optional
+% argument (a non-negative integer) to specify the number of such repeats.
+% In order to implement an optional argument facility we use two macros
+% (countingloop and loopcounter) detailed by Feuers\"{a}nger (2015)
+% [\,see refs Section~\ref{sec:references}\,]\label{sec:feuersanger},
+% as follows:
% \begin{macrocode}
-\newcommand{\RubikRotation}[1]{\IfFileExists{\rubikperlname}{%
+%% Two macros detailed by Feuersaenger (2015)
+\long\def\@countingloop#1 in #2:#3#4{%
+ #1=#2 %
+ \@loopcounter{#1}{#3}{#4}%
+}
+%%--------------------------
+\long\def\@loopcounter#1#2#3{%
+ #3%
+ \ifnum#1=#2 %
+ \let\next=\relax%
+ \else
+ \advance#1 by1 %
+ \def\next{\@loopcounter{#1}{#2}{#3}}%
+ \fi
+ \next
+}
+% \end{macrocode}
+% Having defined the above two macros we can now implement an optional
+% argument (a repeat number) indicating the number of times we want
+% the command to write the main argument to the output data file.
+% \begin{macrocode}
+\newcommand{\RubikRotation}[2][1]{%
\typeout{---NEW rotation command------------------}%
\typeout{---command = RubikRotation{#1}}%
- \typeout{---Perl script \rubikperlname\space exists OK}%
\typeout{---writing current Rubik state to file rubikstate.dat}%
\@openstatefile% open data file
\@print{\@comment filename: rubikstate.dat}%
+ \@print{\@comment written by rubikrotation.sty%
+ =v\RRfileversion\space (\RRfiledate)}%
\@printrubikstate%
- \@print{rotation,#1}%
+%% countingloop code from Feuersaenger (2015)
+ \newcount\ourRRcounter%
+ \@countingloop{\ourRRcounter} in 1:{#1}{%
+ \immediate\write\outfile{rotation,#2}}%
\@closestatefile% close data file
- \typeout{---running Perl script}%
+ \typeout{---running Perl script (rubikrotation)}%
\immediate\write18{\rubikperlcmd}%
- \typeout{---inputting NEW datafile (from Perl)}%
+ \typeout{---inputting NEW datafile (written by Perl script)}%
\input{rubikstateNEW.dat}%
\typeout{-----------------------------------------}%
- }{\typeout{** ERROR: \rubikperlname\space does not exist}%
-}}
+ }
% \end{macrocode}
% \end{macro}
%
%
% \subsection{ShowRubikErrors command}
+% \label{sec:showrubikerrors}
%
% \begin{macro}{\ShowRubikErrors}
% This command inputs the file \texttt{rubikstateERRORS.dat}.
% \begin{macrocode}
\newcommand{\ShowRubikErrors}{%
\typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}%
- \VerbatimInput{rubikstateERRORS.dat}}
+ \VerbatimInput{rubikstateERRORS.dat}%
+ }
% \end{macrocode}
% \end{macro}
%
@@ -904,69 +1326,30 @@
% \subsection{CheckRubikState command}
%
% \begin{macro}{\CheckRubikState}
-% This command triggers the Perl program to implement
+% This command triggers the Perl script to implement
% some simple error checking of the Rubik configuration (state).
% This command (a)~writes the current Rubik state to the file
-% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl program.
+% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl script.
% It also writes comments to the data file and also to the log file..
% \begin{macrocode}
-\newcommand{\CheckRubikState}{\IfFileExists{\rubikperlname}{%
+\newcommand{\CheckRubikState}{%
\typeout{---NEW check command------------------}%
\typeout{---command = CheckRubikState}%
- \typeout{---Perl script \rubikperlname\space exists OK}%
\typeout{---writing current Rubik state to file rubikstate.dat}%
\@openstatefile% opens data file
\@print{\@comment filename: rubikstate.dat}%
\@printrubikstate%
\@closestatefile% close data file
- \typeout{---running Perl script}%
+ \typeout{---running Perl script (rubikrotation)}%
\immediate\write18{\rubikperlcmd}%
- \typeout{---inputting NEW datafile (from Perl)}%
+ \typeout{---inputting NEW datafile (written by Perl script)}%
\input{rubikstateNEW.dat}%
\typeout{-----------------------------------------}%
- }{\typeout{** ERROR: \rubikperlname\space does not exist}%
-}}
+ }
% \end{macrocode}
% \end{macro}
%
%
-%
-% \subsection{SaveRubikState macro}
-%
-% \begin{macro}{\SaveRubikState}
-% The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state
-% to a file. Note that in order to actually write a LaTeX
-% command to a file without a trailing space one must use the
-% \cmd{\string} command (see the book ``TeX by Topic'', p~238).
-% Note that this macro uses the two internal commands \cmd{\Rubik@comment}
-% and \cmd{\Rubik@print}. \#1 is the output filename.
-% We use several \cmd{\typeout} commands to write to the log file.
-% \begin{macrocode}
-\newcommand{\SaveRubikState}[1]{%
-\typeout{---NEW save command------------------}%
-\typeout{---command = SaveRubikState{#1}}%
-\typeout{---saving Rubik state data to file #1}%
-\immediate\openout\outfile=#1%
-\@print{\@comment filename: #1\@commentone}%
-\@print{\string\RubikFaceUp%
- {\Ult}{\Umt}{\Urt}{\Ulm}{\Umm}{\Urm}{\Ulb}{\Umb}{\Urb}\@commentone}%
-\@print{\string\RubikFaceDown%
- {\Dlt}{\Dmt}{\Drt}{\Dlm}{\Dmm}{\Drm}{\Dlb}{\Dmb}{\Drb}\@commentone}%
-\@print{\string\RubikFaceLeft%
- {\Llt}{\Lmt}{\Lrt}{\Llm}{\Lmm}{\Lrm}{\Llb}{\Lmb}{\Lrb}\@commentone}%
-\@print{\string\RubikFaceRight%
- {\Rlt}{\Rmt}{\Rrt}{\Rlm}{\Rmm}{\Rrm}{\Rlb}{\Rmb}{\Rrb}\@commentone}%
-\@print{\string\RubikFaceFront%
- {\Flt}{\Fmt}{\Frt}{\Flm}{\Fmm}{\Frm}{\Flb}{\Fmb}{\Frb}\@commentone}%
-\@print{\string\RubikFaceBack%
- {\Blt}{\Bmt}{\Brt}{\Blm}{\Bmm}{\Brm}{\Blb}{\Bmb}{\Brb}\@commentone}%
-\immediate\closeout\outfile%
-\typeout{-----------------------------------------}%
-}%
-% \end{macrocode}
-% \end{macro}
-%
-%
% --------------------------
% End of this package
% --------------------------