path: root/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx

% \iffalse meta-comment
% rubikrotation.dtx
%
% version 5.0  
%
%
% Authors:   RWD Nickalls (dick@nickalls.org) 
%        and Apostolos Syropoulos (asyropoulos@yahoo.com)
%
% Copyright   25 February 2018  RWD Nickalls + A Syropoulos
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3c of this license or (at your option) any
% later version. The latest version of this licence is in 
%
%       http://www.latex-project.org/lppl.txt
%
%<*readme>
%
% The rubikrotation package provides a collection of LaTeX commands and macros 
% for the typesetting of Rubik cube configurations and rotation 
% sequences using the TikZ graphic language.
%
% Please report errors or suggestions for improvement to
%
%         Dick Nickalls or Apostolos Syropoulos
%
% This package requires the basic TikZ package to be loaded already
%</readme>
%
%<*driver>
\listfiles
\documentclass{ltxdoc}
\IfFileExists{rubikrotation.sty}{\usepackage{rubikrotation}}{%
    \GenericWarning{rubikrotation.dtx}{Package file rubikrotation.sty not found.
    Documentation will be messed up!^^J
    (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J
    process rubikrotation.dtx again)^^J}\stop
}%
\pagestyle{myheadings}
\markright{\texttt{rubikrotation} \ \ (Rubik bundle v5.0, 2018) \ \ \texttt{www.ctan.org/pkg/rubik}}
\usepackage{ifpdf}
\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
\setcounter{StandardModuleDepth}{1}
\begin{document}
  \DocInput{rubikrotation.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
%
% 
%%% \CheckSum{332}
%
%%% \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
%%   Lower-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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
%
%
% \title{%
%       \ifpdf\pdfbookmark[1]{Title}{Title}\else\fi%
%       The \rubikrotation\ package}
%
% \author{
%      RWD Nickalls (dick@nickalls.org) \\
%     A Syropoulos (asyropoulos@yahoo.com)
%       }
%  \date{This file describes version \RRfileversion\ (\RRfiledate)\\
%  \texttt{www.ctan.org/pkg/rubik}}
%  \maketitle
%
%  \begin{abstract}
%  The \rubikrotation\ package is a dynamic extension for  the 
%  \textsc{rubikcube} package (both are part of the Rubik `bundle'). 
%  This 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  commands for saving the cube state 
%  to a file (\cmd{\SaveRubikState}), and for displaying any 
%  errors (\cmd{\ShowErrors}).
%  \end{abstract}
% 
% 
% \begin{minipage}{11cm}
% \centering
% \ifpdf
%  \strut\hspace{6mm}\includegraphics[width=10cm]{rubikrot-doc-figD.pdf}
% \else
% \fi
% \end{minipage}
% 
%
% \vspace{-1\baselineskip}
%
%  \tableofcontents
%
% \pagebreak
%
% \section{Introduction}
%
% The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} 
% and \textsc{rubiktwocube} packages.
% It consists of a style option (\texttt{rubikrotation.sty}), a 
%  Perl script  (\texttt{rubikrotation.pl}).
% 
% 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 the \rubikrotation\  package requires access to the \TeX\ \texttt{write18} 
%  facility, which is enabled by using the \texttt{--shell-escape} command-line switch.
%  This allows 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 (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.}), on a Linux platform (Debian v8.2.0,  
%  {\TeX}Live 2017, and Perl v5.20.2), and on  a Solaris platform (OpenIndiana).
%
% The following  commands are made available  by  \texttt{rubikrotation.sty}:
% \begin{quote}
% \begin{verbatim}
%    \RubikRotation[]{}
%    \SaveRubikState
%    \CheckState
%    \ShowErrors
%    \SequenceName
%    \SequenceInfo
%    \SequenceShort
%    \SequenceLong
%\end{verbatim}
% \end{quote}
% Note that the \textsc{rubiktwocube} package  makes available the (equivalent) 
% \verb!\TwoRotation[]{}! and \verb!\SaveTwoState! commands.
%
%  \section{Requirements}
% 
% The \rubikrotation\ package  requires the TikZ and the \textsc{rubikcube} packages.
% 
%
%   \section{Installation}
%
%  \subsection{Generating the files}
%
%  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.pdf     --this document
% rubikrotation.pl      --Perl script
% rubikrotationPL.pdf   --documentation of rubikrotation.pl
% rubikrotation.1       --manual file for rubikrotation.pl (`man' file)
% rubikrot-doc-figA.pdf
% rubikrot-doc-figB.pdf
% rubikrot-doc-figC.pdf
% rubikrot-doc-figD.pdf
%\end{verbatim}
%\end{quote}
% The main package documentation is the file \texttt{rubikrotation.pdf}.
% The documentation of the Perl program \texttt{rubikrotation.pl} is the file \texttt{rubikrotationPL.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}
%\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 as an 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    rubikrotation.dtx
%  pdflatex    rubikrotation.dtx
%  makeindex -s gind.ist  rubikrotation
%  makeindex -s gglo.ist -o rubikrotation.gls  rubikrotation.glo
%  pdflatex    rubikrotation.dtx
%  pdflatex    rubikrotation.dtx
%\end{verbatim}
%\end{quote}
%
%
% 
%  \subsection{Placing the files}
% \label{sec:placingfiles}
%
% Place the files either in a working directory, or where your system 
% will find them, e.g.,~in the `\textsc{path}'. The \texttt{/texmf-local/} directory tree 
% is often a good place; 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/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  in the `\textsc{path}', or possibly, directly into your 
% {\TeX}Live 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}.
%
%\medskip
%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform the manual file 
% (\texttt{rubikrotation.1}) is  typically  located in 
% either \verb!/usr/local/man/man1! or \verb!/usr/local/share/man/man1!.
% \TeX{Live} typically places such files in the directory
% \verb!/texmf-dist/doc/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,
% or by using the {\TeX}Live Manager (\texttt{tlmgr}). 
%
%\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}
%\end{quote}
% which should generate something like the following:
% \begin{verbatim}
% This is rubikrotation version ...
%       Usage: rubikrotation [-h] -i <input file> [-o <out file>]
%       where,
%       [-h|--help]      gives this help listing
%       [-v|--version]   gives version
%       [-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}, 
%  \texttt{rubikrotation.sty}, \texttt{rubikpatterns.sty} 
%  and \texttt{rubiktwocube.sty} in the \TeX\ file 
%  preamble  \textit{after} loading the TikZ package (all the  Rubik packages 
%  require the TikZ package). Load the \texttt{rubikcube.sty} \textit{before} the other
% Rubik bundle packages; for example, as follows: 
%\begin{quote}
% \begin{verbatim}
% \usepackage{tikz}
% \usepackage{rubikcube,rubikrotation,rubikpatterns,rubiktwocube}
%\end{verbatim}
%\end{quote}
% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line option 
% (see the following section).
%
%
%
%   \subsection{Enabling the \TeX\ `shell' facility}
%   \label{sec:shellescape}
%
%  In order to access the  \TeX\  \cmd{\write18} syntax (so we can access system commands, 
%  and hence run the Perl script), 
% it is necessary to invoke  the \LaTeX\ engine (e.g.,~(pdf)\LaTeX\  or Lua\LaTeX) 
% using the \texttt{--shell-escape} command-line option; for example: 
%\begin{quote}
% \begin{verbatim}
% pdflatex  --shell-escape  filename.tex
%\end{verbatim}
%\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
% echo "...checking error file" 
% grep ERROR  ./rubikstateERRORS.dat
% acroread filename.pdf &
%\end{verbatim}
%\end{quote}
%  If the \LaTeX\ engine is  Lua\LaTeX, e.g.,
%\begin{quote}
% \begin{verbatim}
% lualatex  --shell-escape  filename.tex
%\end{verbatim}
%\end{quote}
%then  \texttt{rubikrotation.sty} will automatically load 
%  the recently developed  \textsf{shellesc} package in order to facilitate system access to  Perl 
%  (see Section~\ref{sec:CodePackageHeading}). See \textit{\LaTeX\ News}, issue~24, 
%  Feb~2016 for further details of the \textsf{shellesc} package.
%  Consequently, if you intend to use Lua\LaTeX\ then you will need to ensure your system
%  has access to the \textsf{shellesc} package (it can always be downloaded from CTAN directly).
%
%
%   \subsection{Configuration-file}
%   \label{sec:configfile}
%
% It is important to realise that the default action of \texttt{rubikrotation.sty} is to 
% access the Perl script as an executable file. This is because the~default definitions 
% in \texttt{rubikrotation.sty} 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 (in the second macro) to use  \cmd{\space} on the end of 
%   (\cmd{\rubikperlname}) in  order to force a following 
% space---i.e.,~before the  first command-line argument.
%
% If the Perl script has not been made executable, or if you wish to alter how 
% the \textsc{rubikrotation} package accesses the Perl script, 
% then you need to create a plain-text configuration file  in order to redefine one 
% or both of the above commands, as described below. 
%
%  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 macros we may wish to adjust
%  (see above).
% The~first is that  holding the filename of the Perl script, namely  
% \cmd{\rubikperlname}. The second is that holding the command-line call, 
% namely  \cmd{\rubikperlcmd}.
% 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 
% (it \textit{must} be named exactly \texttt{rubikrotation.cfg})  containing 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 \textit{both} these  changes (of name and  command) 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}Remember to make sure the PATH associated with the command is also correct.
%
% \medskip
%{\noindent\textsc{placing the configuration-file}:\ \ The simplest arrangement is
% just to include the \texttt{.cfg} file in the working  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} `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 you wish. 
%
%  Using commands which influence the Rubik colour state 
% (e.g.,~\cmd{\RubikFace..}, \cmd{\RubikCubeSolvedWY} etc.) 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 accessible  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{\ShowErrors} command 
%  (see the notes on this command below). 
% 
%
%
%
%   \subsection[RubikRotation]{\cmd{\RubikRotation} command}
%       \label{sec:rubikrotationcmd}
%
%  \DescribeMacro{\RubikRotation}
% The  \cmd{\RubikRotation}\oarg{integer}\marg{comma-separated sequence}  
% command processes  a sequence of rotation codes, and returns 
% the final state. The inverse sequence can also be 
% implemented (see  \textbf{Inverse} below). Note that the equivalent \cmd{\TwoRotation}
% command (see the \textsc{rubiktwocube} package) behaves in the same way as the 
% \cmd{\RubikRotation} command  in all respects.
%
%
% The first (optional) argument \oarg{integer}  of the \cmd{\RubikRotation} command  is the number
% of times the whole command itself should be repeated; for example
% as follows: \verb!\RubikRotation[2]{...}!.
%
% The second (mandatory) argument consists of a comma-separated sequence
% of  rotation codes, e.g.,~\texttt{U, D2}, which may be encoded as a macro. In addition, there 
% may be additional comma-separated macros and optional \verb![name]!,  
%  `repeat blocks' and `info blocks' (see below).  
% The general structure of the second argument is as follows:
% \verb!\RubikRotation{[name],...,\macro,...,(repeat)n,...,<info>}!.  
% These elements are now described in detail.
% 
%
%
% \textbf{Square brackets}: \ This is an optional `sequence name' facility. 
% The contents of square  brackets are not processed 
% as rotations, and can  therefore be used  as a `name' of the sequence, e.g.,~\verb![CrossSeq]!,
% or as a tag, to be visible in the log file. The contents must \textit{not} include commas, but 
% can have other  separators, e.g.,~spaces, semicolons etc. Importantly, the contents of the 
% first square bracket  will be designated the sequence name and will be held as the 
% macro \cmd{\SequenceName}. Square brackets can also be used in repeat blocks (see below). 
%  Square brackets must be separated by a comma from adjacent codes.
%
%
% \textbf{Repeat block}: \  This is an optional comma-separated sequence of rotation
% codes which is to be repeated a specified number of times. It must be delimited 
% by balanced curved brackets, and an optional terminal integer $n$ (repeat number) 
% can be used.   For example, \verb!(F,B3)2,! where the `2' indicates that the rotation 
% sequence \verb!F,B3!  is to be processed twice. If the repeat number is omitted 
% then $n=1$ is assumed. Repeat blocks must be separated by a comma from adjacent codes, 
% and can include balanced square brackets (see below).
%
%
% \textbf{Info block}: \ 
% This  is an optional  block of meta information, and must be
% delimited by  balanced  angle-brackets \verb!<..>!. An info-block  typically carries
% information  regarding the sequence itself; typically,  something 
% like \verb!<(20f*) //C2(a)>!. If an infoblock includes the keyword `inverse' then
% the program will implement the inverse sequence of rotations (see below).
% An info-block must be separated by a comma from the adjacent codes.
% The contents of all info blocks will be held collectively as the macro \cmd{\SequenceInfo}.
%
%
% \textbf{Inverse sequence}: \
% The (mathematically) inverse sequence  of the given sequence can be implemented by including 
% the keyword `inverse' (or INVERSE) in an infoblock, 
% as follows \verb!\RubikRotation{<inverse>, ... }!. The keyword can be either in its 
% own separate infoblock, or inside a larger infoblock. The program simply checks for the 
% string `inverse',  which can be either lower-case or upper-case. The implemented sequence
% can be checked by looking  at (or printing) the contents of the macro 
% \cmd{\SequenceLong} (see  section on \textit{Sequence strings} below). Note that the macro 
% \cmd{\SequenceLong} is also shown (expanded) in the log file. 
%
%
% \subsubsection{Examples}
% 
% Some examples of the use of the \cmd{\RubikRotation} command are as follows; the commas are important and brackets must
% be balanced and not nested:
%\begin{quote}
% \begin{verbatim}
% \RubikRotation[2]{x,R2,U}   
% \RubikRotation{\sixspot}
% \RubikRotation{<inverse>,[myseqB],U,D,L,R2,(M,U)3,D2}  
% \RubikRotation{[K32466],U,F,U2,F,L2,B,U2,F,Lp,Rp,F2,D,R2,U2,L2,B,Fp,
%  L,F2,D,<(20f*) //Oh{I}>} 
%\end{verbatim}
%\end{quote}
%
% \noindent\textbf{Inverse sequence}
%
% Inverting a sequence involves (a)~reversing the order, and (b)~inverting each element.
% Thus, the inverse of the sequence  \verb!(Up,D,L2,Rp)! is  \verb!(R,Lp,Lp,Dp,U)!. 
% But~\verb!(Lp,Lp)! $\equiv$  \verb!L2!, and so the inverse 
% of \verb!(Up,D,L2,Rp)! would generally be expressed as  \verb!(R,L2,Dp,U)!.
% However, since the macro \cmd{\SequenceLong} records the individual elements as they are processed,
% when a sequence is inverted notational compressions such as \verb!Lp,Lp! $\rightarrow$ \verb!L2! 
% are not  made. 
% For example, processing the command \verb!\RubikRotation{<inverse>,Up,D,L2,Rp}! results in the  macro 
% \cmd{\SequenceLong}  being displayed in the subsequent  \texttt{rubikstateNEW.dat} file as
%\begin{quote}
% \begin{verbatim}
% \renewcommand\SequenceLong{R,Lp,Lp,Dp,U}%
%\end{verbatim}
%\end{quote}
% A more extensive example is given at the end of Section~\ref{sec:sequencestrings}.
%
%
% \medskip\noindent\textbf{Repetitions}
%
% Repetitions can be achieved in various ways. First, all the rotations  in the second argument 
% can be repeated  multiple times, say $n$ times, by 
% using the optional \verb![n]! argument of the \cmd{\RubikRotation[]\{\}} command; 
% i.e.,~the whole of the mandatory argument of the \cmd{\RubikRotation} command is then 
% executed $n$ times.  
%
% Second, a sub-sequence of rotations  can be repeated within the main 
%  argument  multiple times,  by delimiting such groups with curved brackets 
% and a trailing integer (i.e.,~in a repeat-block), as described above.
% If no integer is given, then $n=1$ is assumed, and hence curved brackets can also be used
% simply to highlight particular sequences. 
%  For example, the following five commands are equivalent:
%\begin{quote}
% \begin{verbatim}
% \RubikRotation[3]{x,R2,U}
% \RubikRotation{(x,R2,U)3}   
% \RubikRotation{(x,R2,U)2,x,R2,U}
% \RubikRotation{x,R2,U,x,R2,U,x,R2,U}
% \RubikRotation{(x,R2,U),(x,R2,U),(x,R2,U)}
%\end{verbatim}
%\end{quote}
%
%
% \medskip\noindent\textbf{Macros}
%
% Note also that macros representing a rotation sequence can also appear  as part of the main argument.
% So, extending the previous example, if we were to define  \verb!\newcommand{\ShortSeq}{x,R2,U}!, then 
% the following three commands would also be equivalent to the five previous ones:
%\begin{quote}
% \begin{verbatim}
% \RubikRotation[3]{\ShortSeq}
% \RubikRotation{(\ShortSeq)3}
% \RubikRotation{(x,R2,U),\ShortSeq,\ShortSeq}
%\end{verbatim}
%\end{quote}
%
%
% \medskip\noindent\textbf{Process overview}
%
% 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 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 the four \cmd{\Sequence...} macros (see below), and any error messages, all to the 
% file \texttt{rubikstateNEW.dat}, 
% which is then input on-the-fly by the \texttt{.tex} file. This new Rubik state 
% can then be  used either as the input for another \cmd{\RubikRotation} command, or used
% to generate a graphic image of the cube. The \cmd{\Sequence...} macros  can then
%  be used for typesetting the sequence of rotations in various formats.
%
%
%  \subsubsection{Sequence strings}
%    \label{sec:sequencestrings}
%
%  \DescribeMacro{\SequenceName}
%  \DescribeMacro{\SequenceInfo}
%  \DescribeMacro{\SequenceShort}
%  \DescribeMacro{\SequenceLong}
%  The sequence of rotation codes  used as the main argument for the \cmd{\RubikRotation}
% command is also returned in the form of four macros, namely \cmd{\SequenceName} (contains the 
% `name' of the sequence if a \texttt{[name]} exists), \cmd{\SequenceInfo} (contains any sequence 
%  meta data  in `info-blocks'),   \cmd{\SequenceShort} (contains the original 
% sequence of rotation codes), and \cmd{\SequenceLong} (contains the expanded or `Long' form of the 
% original sequence---i.e.,~in which any `short'  rotation codes (e.g.,~\texttt{R2, L3}) in the original 
% sequence have been expanded into their separate codes---e.g.,~\texttt{R, R, L, L, L} etc.).
%
% For example, if we wanted to see the effect of  the sequence associated with the `SixTs'
% cube configuration  
% \verb![SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>! 
% on a solved Rubik cube  (where `SixTs' is the `name' of the sequence),
%  we  could use the  following commands: 
%\begin{quote}
% \begin{verbatim}
% \RubikCubeSolved   % sets up the colours for a solved cube state
% \RubikRotation{[SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>}
% \ShowCube{2.8cm}{0.7}{\DrawRubikCubeRU}
%\end{verbatim}
%\end{quote}
% Note (a)~contents of a square bracket [..] are not processed as rotations, (b)~the contents
% of the first square bracket in a sequence is taken to be the `name' of the sequence
%  (see Section~\ref{sec:prefixedargument}  for more details).
% In this example the four \cmd{\Sequence..} macros described above would now hold 
% the following strings:
%\begin{quote}
% \cmd{\SequenceName}  = SixTs
%{\newline} \cmd{\SequenceInfo}  = (14q*,14f*)
%{\newline} \cmd{\SequenceShort} = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B
%{\newline} \cmd{\SequenceLong}  = F,F,R,R,U,U,Fp,B,D,D,L,L,F,B
%\end{quote}
%
% As another example, we now show how to  implement  the inverse of the  above \verb!SixTs! 
% sequence,  by including  the key word `inverse' in an infoblock, and, more conveniently, 
% using the macro \verb!\sixts! from  the  \textsc{rubikpatterns} package, as follows:
%\begin{quote}
% \begin{verbatim}
% \RubikRotation{<inverse>,\sixts}
%\end{verbatim}
%\end{quote}
% In this case, the log file would then show the associated \cmd{\Sequence..} macros as follows:
%\begin{quote}
% \begin{verbatim}
%...SequenceName = SixTs
%...SequenceInfo = inverse; (14q*; 9f*)
%...SequenceShort = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B
%...SequenceLong = Bp,Fp,Lp,Lp,Dp,Dp,Bp,F,Up,Up,Rp,Rp,Fp,Fp
%\end{verbatim}
%\end{quote}
% showing that the macro \cmd{\SequenceShort}  holds the \verb!\sixts! sequence, while
%  the macro \cmd{\SequenceLong}  holds the inverse sequence which was actually implemented.
%
% For further details  regarding the use of these \cmd{\Sequence..} macros  for typesetting
% the various components of a sequence, and why the \cmd{\SequenceLong} command is 
% particularly useful, see Section~10 in the \textsc{rubikcube} documentation
% (the \cmd{\ShowSequence} command).
%
%
%
%  \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 references 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. Note that 
% \texttt{rubikpatterns.sty} (part of the Rubik bundle)  is a collection/database 
% of many such well-known named sequences. 
%
% For example, by installing the \textsc{rubikpatterns} package we  are able to 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 references Section~\ref{sec:references}\,]. The `sixspot' sequence is 
% defined as follows:
%\begin{quote}
% \begin{verbatim}
% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>}
%\end{verbatim}
%\end{quote}
% Armed with the \cmd{\sixspot} macro 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}{7cm}
% \begin{verbatim}
% \usepackage{rubikcube,rubikrotation}
% \usepackage{rubikpatterns}
% ...
% \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}
% \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  in square brackets }
%    \label{sec:prefixedargument}
%
%  The contents of a square bracket  are not processed as rotations, but are simply  
% interpreted as an inactive `string'. This feature therefore 
% allows  the contents to be used as a label, which can be very useful.
% Note the contents of square brackets must not include commas, but spaces  and semicolons 
% are allowed.
%
%  For example, we can use this facility to `name' 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 [\,]  label-name feature  in the \cmd{\sixspot} command, as follows,
%\begin{quote}
% \begin{verbatim}
% \newcommand{\sixspot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp}
%\end{verbatim}
%\end{quote}
% Note that using the \texttt{[name]} facility has the great advantage of making the 
% label-name visible in the log-file.
% For example, the following command, which uses the rotations \textbf{x2},
% and \textbf{y} to   rotate the Rubik cube after applying 
% the `sixspot' sequence  of rotations:
%\begin{quote}
% \begin{verbatim}
% \RubikRotation{\sixspot,x2,y}
%\end{verbatim}
%\end{quote}
% will then be represented in the log file as 
%\begin{quote}
% \begin{verbatim}
% ...dataline = rotation,[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*; 8f*)>,x2,y
% ...[SixSpot] is a label OK
% ...rotation U, OK
% ...rotation Dp, OK 
% ...rotation R, OK
% ...rotation Lp, OK
% ...rotation F, OK
% ...rotation Bp, OK
% ...rotation U, OK
% ...rotation Dp, OK 
% ...Expanding x2 ...
% ...rotation x, OK (= x = R + Sr + Lp)
% ...rotation x, OK (= x = R + Sr + Lp)
% ...rotation y, OK (= y = U + Su + Dp)
% ...writing new Rubik state to file rubikstateNEW.dat
% ...SequenceName = SixSpot
% ...SequenceInfo = (8q*; 8f*)
% ...SequenceShort = [SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,x2,y
% ...SequenceLong = U,Dp,R,Lp,F,Bp,U,Dp,x,x,y
%\end{verbatim}
%\end{quote}
% Note that the \verb!\sixspot! macro, as held in the \textsc{rubikpatterns} package, includes  a terminal 
% infoblock holding the  `SequenceInfo' as indicated in the  above example.
%
% Also, note that the square bracket feature allows for several named rotation sequences 
% to be  easily distinguished 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. 
%
% See also the \cmd{\ShowSequence} command (in the \textsc{rubikcube} package)
% for a convenient way of displaying a sequence of rotations in various formats.
%
%
%   \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 e$\,\footnote{$e$ is the `identity' element},
%  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}
%
%  The \cmd{\RubikRotation} command  can also be used to  scramble the 
% cube using a random sequence of rotations. If  the first argument 
% is the word `random' \textsc{and} the second argument 
% is an integer $n$, ($1\leq n \leq 200$), then a random sequence 
% of $n$ rotations will be performed. 
% 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 we  currently have
%  (see  the `random' subroutine in the document \texttt{rubikrotationPL.pdf})
%\begin{quote}
%\begin{verbatim}
% my $maxn=200;
%\end{verbatim}
%\end{quote}
%
% For example, the following commands scramble a solved cube using a 
% sequence of 120 random rotations, and display the state in the form of 
%  a  semi-flat (SF) cube. 
%

% \begin{minipage}{3.4cm}
% \centering
% \ifpdf
%   \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}{\DrawRubikCubeSF}
%\end{verbatim}
% \end{minipage}
%
% Note that in this particular example (above), only 
% 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 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[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 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{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}%
% \RubikFaceDown{R}{R}{R}{R}{Y}{R}{R}{R}{R}%
% \RubikFaceLeft{Y}{Y}{Y}{Y}{B}{Y}{Y}{Y}{Y}%
% \RubikFaceRight{W}{W}{W}{W}{G}{W}{W}{W}{W}%
% \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 in a Semi-Flat  format 
% later, when required,  simply by inputting  the file as follows:
%\begin{quote}
%\begin{verbatim}
%\input{sixspot.tex} 
%\ShowCube{7cm}{0.7}{\DrawRubikCubeSF}
%\end{verbatim}
%\end{quote}
%
%
%  \subsection[CheckState]{\cmd{\CheckState} command}
%   \label{sec:checkstate}
%
%  \DescribeMacro{\CheckState}
%  Since it is easy to inadvertently define an invalid Rubik cube 
% (e.g.,~enter an invalid number of, say, yellow facelets), this command 
%  simply checks the current colour state of all the cubies
% 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~9 for a 3x3x3 cube (Rubik cube), or exceeds 4 for a 2x2x2 cube (Two cube).
% The results are written to the the \texttt{.log} file, and displayed at the point
% the \cmd{\ShowErrors} command is used (for code see Section~\ref{sec:checkstatecode}).
%
% One can check the current Rubik state (for errors) by issuing  the command
%\begin{quote}
%\begin{verbatim}
% \CheckState%
%\end{verbatim}
%\end{quote}
% Note (1)~that  such a check is implemented automatically with each \cmd{\RubikRotation} and 
% \cmd{\TwoRotation} command, and (2)~and makes only a very superficial check---simply counting the number 
% of cubies of each colour.
%
% Note that the \cmd{\CheckState} command replaces the earlier \cmd{\CheckRubikState}, but
% we retain the old command for backwards compatibility (for the moment).
%
%
%   \subsection[ShowErrors]{\cmd{\ShowErrors} command}
%   \label{sec:showerrors}
%
%
%   \DescribeMacro{\ShowErrors}
% Any errors which arise  can be made visible using  the 
% command  \cmd{\ShowErrors}. 
% This command  places a copy of the `error' file (\texttt{rubikstateERRORS.dat})  
% underneath the graphic image so you can see any errors if there are any (note that 
% details  of all errors are are written by default to the \texttt{.log} file)
% (for code see Section~\ref{sec:showerrorscode}).
%
%  Consequently, the \cmd{\ShowErrors} 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 where it will reveal all 
%  rotation errors  generated while  processing the whole document.
% Once the document is free of errors this command can be removed or just commented out. 
% The file \texttt{rubikexamples.pdf} shows an example of the use of this command. 
%
% Note that the \cmd{\ShowErrors} command replaces the  original \cmd{\ShowRubikErrors} command, 
% which will be retained for backward compatibility.
%
%
%    \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 
% 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  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   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{\ShowErrors} is used after  the TikZ picture environment.
%
% \end{itemize}
%
% 
%     \section{General overview}
%   \label{generaloverview}
%
%  When \LaTeX\  processes  \texttt{rubikrotation.sty}  the following steps
%  are implemented (see Section~\ref{sec:thecode}):
% \begin{itemize}
% 
% \item[1.]  A check is made to see if  \texttt{fancyvrb.sty} is loaded: if not 
% then this package  is loaded  (this package supplies the command \cmd{\VerbatimInput} which 
% is required for inputting the  file  \texttt{rubikstateERRORS.dat} in verbatim form).
% 
% \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' version of the file being 
%  used by \LaTeX).
%
% \item[4.]  The plain-text file \texttt{rubikstateERRORS.dat} is created. 
% This file collects error  messages generated by the Perl script.
%
% \end{itemize}
%
%
% When a \cmd{\RubikRotation} command is processed 
% (see Section~\ref{sec:rubikrotationcode}, line~102), it first  writes the current 
% colour configuration of each face (the `rubik state') to the temporary file 
% \texttt{rubikstate.dat} (this will 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}. 
%
% For example, if we use the command \cmd{\RubikCubeSolved}
% followed by the command \verb!\RubikRotation[2]{U,D,L,R}!, then the associated 
%  \texttt{rubikstate.dat} file  will be written as follows:
%\begin{quote}
% \begin{verbatim}
% % filename: rubikstate.dat
% cubesize,three
% 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,U,D,L,R
% rotation,U,D,L,R
%\end{verbatim}
%\end{quote}
% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the string ``\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}'', as follows:
%\begin{quote}
% \begin{verbatim}
% % filename: rubikstate.dat
% cubesize,three
% 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{\CheckState} command   triggers the same sequence of events except
% that no ``\texttt{rotation,....}'' line is written.
%
% 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 from \LaTeX\  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}'), and performing
% a syntax check---significant syntax errors at this stage 
%  will cause the program to  issue appropriate error messages and then terminate cleanly.
% Next, the Perl script  performs  some basic cube checks 
% (prompted by the key word `\texttt{checkstate}'), and then the program processes  
% the sequence of Rubik rotations (prompted by the keyword 
% `\texttt{rotation}').  If, instead, the second argument  of the `\texttt{rotation,...}' string 
% is the keyword `\texttt{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.
% The Perl script now closes all open files and terminates. 
%
% Control then passes back to  \LaTeX\ (still in \texttt{rubikrotation.sty} processing 
% the \cmd{\RubikRotation} command---see Section~\ref{sec:rubikrotationcode}, line~115); 
% its next action is to input the file
% \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands
% (in the \texttt{.tex} file) then this cycle  repeats accordingly.  
% Eventually a \cmd{\Draw...} command is  reached (in the \texttt{.tex} file) and 
% the final rubikstate is drawn in a TikZ picture  environment.
%
% If the TikZ picture environment is followed by a \cmd{\ShowErrors} 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{\ShowErrors} command can be removed or commented out. 
%
% Alternatively, when processing a long document, it can be useful to place 
% a \cmd{\ShowErrors} command at the end of the document, where it will list 
% all errors which occurred. Once any errors have been fixed, this 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{Change history}
%
% \begin{itemize}
%
% \item Version 5.0 (February 2018)
%
%  --- minor bugfixes and better syntax checking in the Perl program. 
%      The cube size  being processed (ie 3x3x3 or 2x2x2) is now detected by the program.
% 
%  --- the command \cmd{\CheckState} replaces the earlier 
%     \cmd{\CheckRubikState} command in order
%      to avoid confusion, now that we are able to process both the  3x3x3 cube (Rubik cube)
%     and also the 2x2x2 cube (Two cube) 
%     (see Sections~\ref{sec:checkstate} and \ref{sec:checkstatecode} (code)). 
%     The original command is retained (for now) for  backward compatibility.
%     \verb!\CheckRubikState! $\rightarrow$ \verb!\CheckState!
%
%  --- the command \cmd{\ShowErrors}  replaces the earlier 
%     \cmd{\ShowRubikErrors} command in order
%      to avoid confusion now, that we are able to process both the  3x3x3 cube (Rubik cube)
%     and also the 2x2x2 cube (Two cube) 
%    (see Sections~\ref{sec:showerrors} and \ref{sec:showerrorscode} (code)). 
%     The original command is retained (for now) for
%     backward compatibility. \verb!\ShowRubikErrors! $\rightarrow$ \verb!\ShowErrors!
% 
% 
% 
%
%
% \item Version 4.0 (March  2017)
%
% --- The \cmd{\RubikRotation} command has been enhanced to allow its argument to include
%  so-called repeat-blocks (rotation-sequences which can be repeated multiple times), and 
% info-blocks for holding sequence metadata (see Section~\ref{sec:rubikrotationcmd}).
% Syntax checking of the \cmd{\RubikRotation} argument is much improved 
% (see \texttt{rubikrotationPL.pdf} for details of the Perl script).
%
% --- Four new macros  which  hold derived data (see Section~\ref{sec:rubikrotationcmd}).
% \begin{quote}
%  \cmd{\SequenceName}
%  \newline\cmd{\SequenceInfo}
%  \newline\cmd{\SequenceShort}
%  \newline\cmd{\SequenceLong}
% \end{quote}
%
% --- Better syntax checking of the \cmd{\RubikRotation} argument by the Perl program \texttt{rubikrotation.pl}.
%
%
%
% \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{\RubikRotation} 
% 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 (manual 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 file-names
%  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}
%
%
%
%
%
%       \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 Kociemba  website (Kociemba H). \url{http://www.kociemba.org/cube.htm}
%
% \item Nickalls RWD and Syropoulos A (2015).  The \textsc{rubikcube} package, v3.0.
% \newline\url{http://www.ctan.org/pkg/rubik}, 
%
%
% \item Randelshofer website (Randelshofer W).  \url{http://www.randelshofer.ch/rubik/}
%  \ [\,re:~sequences  and  supersetENG notation\,]
%
%
% \item Reid website (Reid M). \  Patterns.  \url{http://www.cflmath.com/Rubik/patterns.html}
% \ [\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,]
%
%
% \item Tellechea C and Segletes SB (2016).  The  \textsf{listofitems} package, v1.2
% \newline\url{http://www.ctan.org/pkg/listofitems}
%
%\end{itemize}
% 
%
%
%
%
% ^^A ==================================================
% \StopEventually{\PrintIndex}
%
%  
%
%        \section[The code]{The code (\texttt{rubikrotation.sty})} 
%        \label{sec:thecode}
% 
% {\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}
%   \label{sec:CodePackageHeading}
%
%    \begin{macrocode}
%<*rubikrotation>
\def\RRfileversion{5.0}%
\def\RRfiledate{2018/02/25}%  25 February 2018
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)]
%    \end{macrocode}
%
%
% {\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.}%
   }%
%    \end{macrocode}
%
%
%
%  {\noindent}The \rubikrotation\  package requires access to the  \textsf{fancyvrb} package
%  for the \cmd{\VerbatimInput\{\}} command  which we use for inputting and displaying
%  the error file (see Section~\ref{sec:showerrors}).
%    \begin{macrocode}
\@ifpackageloaded{fancyvrb}{}{%
   \typeout{---rubikrotation requires the fancyvrb package%
       for VerbatimInput{} command.}%
   \RequirePackage{fancyvrb}}
%    \end{macrocode}
%
%
%   {\noindent}For the \cmd{\write18} syntax to work with
%   Lua\TeX\ (so we can access system commands) we require 
%   the recent \textsf{shellesc} package, which we load using the 
%   \textsf{ifluatex} conditional (see Section~\ref{sec:shellescape}).
%    \begin{macrocode}
\@ifpackageloaded{ifluatex}{}{%
   \typeout{---rubikrotation requires the ifluatex package.}%
   \RequirePackage{ifluatex}}
\ifluatex%
   \@ifpackageloaded{shellesc}{}{%
   \typeout{---rubikrotation requires the shellesc package
       to run using Lua\LaTeX.}%
   \RequirePackage{shellesc}}
\fi%
%    \end{macrocode}
%
%
%  \medskip
% 
%   \subsection{Some useful commands}
%   \label{sec:usefulcommands}
%
%    \begin{macro}{\rubikrotation}
% First we create a suitable logo
%    \begin{macrocode}
\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}
%
%
%
%    \begin{macro}{\@comment}
%    \begin{macro}{\@commentone}
%  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}%
\newcommand{\@commentone}{\rubikpercentchar}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%
%
%    \begin{macro}{\rubikperlname}
%  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}
%    \end{macrocode}
%    \end{macro}
% Note that here we are assuming that the script is an executable file.
%
%    \begin{macro}{\rubikperlcmd}
%  This holds the command-line  code for calling the Perl script 
%  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 we do actually specify 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 (i.e.,~data  generated  by  the Perl script)
%  from the file \texttt{rubikstateNEW.dat}.
%    \begin{macrocode}
\newcommand{\rubikperlcmd}{\rubikperlname\space%
                   -i rubikstate.dat   -o rubikstateNEW.dat}
%    \end{macrocode}
%  Remember to use the \cmd{\space} macro following the \cmd{\rubikperlname} macro 
%  in order to  generate the mandatory space before 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 configuration file exists (\texttt{rubikrotation.cfg}) then input it here,
% i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd} 
% macros and \textit{before} creating the \texttt{rubikstateERRORS.dat} file.
%    \begin{macrocode}
\typeout{---checking for config file (rubikrotation.cfg)...}
\IfFileExists{rubikrotation.cfg}{%
   \input{rubikrotation.cfg}%
   }{\typeout{---no config file available}%
}%
%    \end{macrocode}
%
%
%   \subsection{Clean file rubikstateNEW.dat}
%
% {\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}%
\immediate\closeout\outfile%
%    \end{macrocode}
%
%
%   \subsection{rubikstateERRORS.dat}
%
%  {\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{\ShowErrors}.
%
%  \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 here.
%    \begin{macrocode}
\typeout{---creating file rubikstateERRORS.dat}%
\newwrite\outfile%
\immediate\openout\outfile=rubikstateERRORS.dat%
\@print{\@comment ShowErrors (rubikstateERRORS.dat)}%
\@print{\@comment ---------------------------------}%
\immediate\closeout\outfile%
%    \end{macrocode}
%
%
%    \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 file openings (e.g.,~for \texttt{rubikstate.dat} and  saving 
% to arbitrary file-names by the \cmd{\SaveRubikState} command). Otherwise, we 
% 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.sty to use...}%
\newwrite\outfile%
%    \end{macrocode}
%
%
%    \begin{macro}{\@openstatefile}
%    \begin{macro}{\@closestatefile}
% 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. 
%    \begin{macrocode}
\newcommand{\@openstatefile}{\immediate\openout\outfile=rubikstate.dat}
\newcommand{\@closestatefile}{\immediate\closeout\outfile}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%
%    \subsection{Saving the Rubik state}
%
%    \begin{macro}{\@printrubikstate}
% 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 include the line \texttt{cubesize,three} to inform the Perl script
% that the cube is a 3x3x3 cube (this is used in the `random' subroutine).
%
% The actual state (colour state) is simply an ordered sequence of the  faces and the colours 
% associated with each facelet of a 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{cubesize,three}%
   \@print{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}%
   \@print{down,\Dlt,\Dmt,\Drt,\Dlm,\Dmm,\Drm,\Dlb,\Dmb,\Drb}%
   \@print{left,\Llt,\Lmt,\Lrt,\Llm,\Lmm,\Lrm,\Llb,\Lmb,\Lrb}%
   \@print{right,\Rlt,\Rmt,\Rrt,\Rlm,\Rmm,\Rrm,\Rlb,\Rmb,\Rrb}%
   \@print{front,\Flt,\Fmt,\Frt,\Flm,\Fmm,\Frm,\Flb,\Fmb,\Frb}%
   \@print{back,\Blt,\Bmt,\Brt,\Blm,\Bmm,\Brm,\Blb,\Bmb,\Brb}%
}
%    \end{macrocode}
%    \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 one of the lines 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}\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.
%
% The way we allow the user to (optionally) process the main argument multiple
%  times  is simply by writing the associated output command multiple
% times to the output data-file. Consequently, we require the \cmd{\RubikRotation} 
% command to allow a square-bracket optional
% argument (a non-negative integer) to specify the number of such repeats.
% In order to implement this 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}
%% 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{---TeX process---------------------------}% 
   \typeout{---script = rubikrotation.sty v\RRfileversion\space (\RRfiledate)}% 
   \typeout{---NEW rotation command}%
   \typeout{---command = RubikRotation[#1]{#2}}%
   \typeout{---writing current cube 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% 
%% countingloop code from Feuersaenger (2015)
   \newcount\ourRRcounter%
   \@countingloop{\ourRRcounter} in 1:{#1}{%
         \immediate\write\outfile{rotation,#2}}%
   \@closestatefile% close data file
   \typeout{---CALLing Perl script (rubikrotation.pl)}%
   \immediate\write18{\rubikperlcmd}%
   \typeout{---inputting NEW datafile (data written by Perl script)}%
   \input{rubikstateNEW.dat}%
   \typeout{-----------------------------------------}%
 }
%    \end{macrocode}
%    \end{macro}
% Note that the new \cmd{\ShellEscape} command implemented by the recent
% \textsf{shellesc} package is equivalent to \cmd{\immediate}\cmd{\write18} (see above),
%  and so we  probably ought to use \cmd{\ShellEscape} instead in future (and hence load
% \textsf{shellesc} automatically). At present, however, we leave the user to make 
% sure that the \textsf{shellesc} package is actually  available on their system.
% 
%
%
%   \subsection{ShowErrors command}
%   \label{sec:showerrorscode}
%
%    \begin{macro}{\ShowErrors}
% This command inputs the file \texttt{rubikstateERRORS.dat} 
% (output by the Perl program).
%    \begin{macrocode}
\newcommand{\ShowErrors}{%
   \typeout{---ShowErrors: inputting file rubikstateERRORS.dat}%
   \VerbatimInput{rubikstateERRORS.dat}%
 }
%    \end{macrocode}
% Since this command replaces the original command = \cmd{\ShowRubikErrors},  we will
% retain the original command for backward compatibility (for the moment at least).
%    \begin{macrocode}
\newcommand{\ShowRubikErrors}{\ShowErrors}
%    \end{macrocode}
%    \end{macro}
%
%
%   \subsection{CheckState command}
%   \label{sec:checkstatecode}
%
%    \begin{macro}{\CheckState}
% 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}, (b)~writes the keyword `checkstate' to the 
% same file, and then (c)~CALLs the Perl script.
% It also writes comments to the data file and also to the  log file.
%
% Note (1)~that the command \cmd{\@printrubikstate} actually writes the 
% current state  to the file \texttt{rubikstate.dat}, (2)~the keyword `checkstate'
% triggers the Perl program to do a simple numerical check on the number 
% of facelets with each colour.
%
% Note  also that the \cmd{\CheckState} command replaces the earlier 
% \cmd{\CheckRubikState}, but we retain the old command for backwards 
% compatibility (for the moment).
%    \begin{macrocode}
\newcommand{\CheckState}{%
   \typeout{---NEW check command------------------}%
   \typeout{---command = CheckState}%
   \typeout{---writing current cube state to file rubikstate.dat}%
   \@openstatefile% opens data file
   \@print{\@comment filename: rubikstate.dat}%
   \@printrubikstate% 
         \immediate\write\outfile{checkstate}%
   \@closestatefile% close data file
   \typeout{---running Perl script (rubikrotation.pl)}%
   \immediate\write18{\rubikperlcmd}%
   \typeout{---inputting NEW datafile (data written by Perl script)}%
   \input{rubikstateNEW.dat}%
   \typeout{-----------------------------------------}%
 }
\newcommand{\CheckRubikState}{\CheckState}
%    \end{macrocode}
%    \end{macro}
%
%
% --------------------------
%    End of this package
% --------------------------
%    \begin{macrocode}
%</rubikrotation>
%    \end{macrocode}
%
%
%
%
% \Finale
%
\endinput