summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-03-06 21:58:50 +0000
committerKarl Berry <karl@freefriends.org>2017-03-06 21:58:50 +0000
commitaba00871ee9f5f5ac8d46fe9d0b8e29cd8ce1e8b (patch)
tree98276bb92499bc5ceb7c72cda4393f028520fc4a /Master/texmf-dist/source
parent346afec669dbe142884f0794af09981c591e6afd (diff)
rubik (6mar17)
git-svn-id: svn://tug.org/texlive/trunk@43415 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rwxr-xr-xMaster/texmf-dist/source/latex/rubik/examples.bat4
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikcube.dtx6209
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikcube.ins19
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikexamples.bat3
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikpatterns.dtx540
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikpatterns.ins65
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikpatternsLIST.bat3
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikrotation.dtx715
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikrotation.ins22
9 files changed, 5758 insertions, 1822 deletions
diff --git a/Master/texmf-dist/source/latex/rubik/examples.bat b/Master/texmf-dist/source/latex/rubik/examples.bat
deleted file mode 100755
index 1a67e63e77e..00000000000
--- a/Master/texmf-dist/source/latex/rubik/examples.bat
+++ /dev/null
@@ -1,4 +0,0 @@
- latex --shell-escape examples.tex
-# latex --shell-escape examples.tex
-
-
diff --git a/Master/texmf-dist/source/latex/rubik/rubikcube.dtx b/Master/texmf-dist/source/latex/rubik/rubikcube.dtx
index c2f2411d015..4f57d98a0ee 100644
--- a/Master/texmf-dist/source/latex/rubik/rubikcube.dtx
+++ b/Master/texmf-dist/source/latex/rubik/rubikcube.dtx
@@ -1,10 +1,9 @@
% \iffalse meta-comment
-%
% rubikcube.dtx
%
-% version 3.0 25 September 2015
+% version v4.0 (03 March 2017)
%
-% Copyright 2015
+% Copyright 2017
% RWD Nickalls (dick@nickalls.org) and
% A Syropoulos (asyropoulos@yahoo.com)
%
@@ -63,7 +62,7 @@
%
%
%
-% \CheckSum{4105}
+%%% \CheckSum{5683}
%
%%% \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
@@ -82,7 +81,9 @@
%% Right brace \} Tilde \~}
%
%
-% \title{The \textsc{rubikcube} package}
+% \title{%
+% \ifpdf\pdfbookmark[1]{Title}{Title}\else\fi%
+% The \textsc{rubikcube} package}
%
% \author{
% RWD Nickalls (dick@nickalls.org) \\
@@ -96,7 +97,7 @@
% The \rubikcube\ package provides LaTeX commands and macros
% for typesetting Rubik cube (3x3x3) notation, configurations, and
% rotation sequences using the TikZ graphic language. It is part of the
-% rubik `bundle'.
+% Rubik `bundle'.
% \end{abstract}
%
% \medskip
@@ -104,7 +105,7 @@
% \begin{minipage}{11cm}
% \centering
% \ifpdf
-% \includegraphics[width=10cm]{Rubik-doc-figF.pdf}
+% \includegraphics[width=10cm]{rubik-doc-figF.pdf}
% \else
% \fi
% \end{minipage}
@@ -118,58 +119,109 @@
% The \rubikcube\ package (part of the \textsc{rubik} `bundle') provides a
% collection of \LaTeX\ commands
% and macros for typesetting Rubik cube configurations using the
-% PGF/TikZ graphic languages. Note that this package relates only to the
+% PGF/TikZ graphic languages, and relates only to the
% familiar 3x3x3 Rubik cube.
-% We have extended the layer-rotation hieroglyphic notation, originally
+% We have extended the rotation hieroglyph notation, originally
% developed by Garfath-Cox (1981), and improved by Duvoid (2010, 2011).
%
% The \rubikcube\ package is designed to be used in conjunction
-% with the \textsc{rubikrotation} package (see below); the former deals
-% primarily with typesetting, while the latter processes rotation sequences
-% and keeps track of the cube's configuration.
+% with both the \textsc{rubikrotation} package and the \textsc{rubikpatterns} package.
+% The \rubikcube\ package deals primarily with typesetting, while the \textsc{rubikrotation}
+% package processes rotation sequences and keeps track of the cube's configuration.
+% The \textsc{rubikpatterns} package is a small database of Rubik cube rotation sequences
+% which generate well-known named cube configurations (patterns).
+% For full functionality it is recommended that all three Rubik packages are used
+% together; for~example,
+%\begin{verbatim}
+% \usepackage{tikz,rubikcube,rubikrotation,rubikpatterns}
+%\end{verbatim}
+% Note that the \verb!TikZ! package must be loaded \textit{before} the \textsc{rubikcube}
+% package.
%
% The \rubikcube\ package has been road-tested on a Microsoft
-% platform (with \textsf{MiK}\TeX), a Linux platform (Mandriva and {\TeX}Live),
-% and on a Solaris platform (OpenIndiana).
+% platform (with \textsf{MiK}\TeX), a GNU-Linux platform (Debian 8.2.0
+% and {\TeX}Live 2016), and on a Solaris platform (OpenIndiana).
%
%
% For the mathematics and group theory associated with the Rubik cube see Chen~(2004),
-% Davis (2006), Golomb~(1981, 1982), Joyner~(2008), Hofstadter (1981), Hutchings~(2011),
-% Kociemba web site, Rokicki~\textit{et al.} (2013), Tran~(2005).
-% Useful web sites for solvers are the Speedsolving website, and those
-% maintained by Duvoid, by Fridrich, by Jelinek, by Reid, and by Vandenburgh
-% (see References).
+% Davis (2006), Golomb~(1981, 1982), Hofstadter (1981), Hutchings~(2011),
+% Heise website, Joyner~(2008), Kociemba website,
+% Rokicki~\textit{et al.} (2013), Scherphius website, Tran~(2005).
+% Other useful websites are the Speedsolving website, and those
+% maintained by Duvoid, by Fridrich, by Jelinek, by Reid, and by Vandenburgh.
+% A useful online solver utility (based on an algorithm by Kociemba) is
+% available at the RuWix website. Websites with good pages on patterns and symmetries are
+% those by Fridrich, Kociemba, Longridge, Reid, Randelshofer, Scherphius
+% (see References for details).
%
%
% \subsection{Requirements}
%
-% The \rubikcube\ package requires the TikZ package.
-% In particular, we make use the \cmd{\pgfmathsetmacro} command and
-% the TikZ picture environment.
+% The \rubikcube\ package requires the TikZ package, since it makes
+% use of the TikZ picture environment and the \cmd{\pgfmathsetmacro} command.
+% Consequently, the \verb!TikZ! package must be loaded \textit{before}
+% the \textsc{rubikcube} package.
+%
+% Both the \textsc{rubikrotation} and \textsc{rubikpatterns} packages (see below)
+% require Perl to be installed.
%
%
% \subsection[rubikrotation package]{Supporting tool---the
% \textsc{rubikrotation} package}
-% \label{sec:addons}
+% \label{sec:rubikrotation}
%
-% The \textsc{rubikrotation} package, is a dynamic extension to
-% the \rubikcube\ package, and is part of the `Rubk bundle'. It consists of the
+% The \textsc{rubikrotation} package (also part of the \textsc{rubik} `bundle'),
+% is a dynamic extension to the \rubikcube\ package. It consists of the
% Perl program \texttt{rubikrotation.pl} and the associated style option
% \texttt{rubikrotation.sty}.
-% The \textsc{rubikrotation} package implements rotation sequences and
-% random scrambling of the 3x3x3 Rubik cube on-the-fly using a
+% The \textsc{rubikrotation} package implements rotation sequences on-the-fly using a
% \cmd{\RubikRotation}\marg{rotation-sequence} command. It returns the
-% new state in a form which is then used by the \rubikcube\ package.
+% new state in a form which can then be used by the \rubikcube\ package.
+% It also returns some useful strings associated with the rotation sequence
+% which can be used by the \rubikcube\
+% package---see also Section~\ref{sec:showsequence}.
%
% Since the \cmd{\RubikRotation} command works by \textsc{call}ing the
% \texttt{rubikrotation.pl} program, it follows that the \textsc{rubikrotation}
% package requires (a)~Perl to be installed,
-% and (b)~\LaTeX\ needs to be run using the \texttt{--shell-escape} commandline option.
-% See the \textsc{rubikrotation} documentation for details.
+% and (b)~the \LaTeX\ engine needs to be run using the \texttt{--shell-escape}
+% command-line option. Those wishing to use Lua\LaTeX\ will also need to have access
+% to the recent \texttt{shellesc} package (in {\TeX}Live 2016).
+% The \texttt{shellesc} package can always be downloaded from CTAN directly.
+% See the \textsc{rubikrotation} documentation for further details.
+%
+%
+%
+% \subsection[rubikpatterns]{Supporting database---\textsc{rubikpatterns.sty} }
+% \label{sec:patterns}
+%
+%
+% The \textsc{rubikpatterns.sty} file (also part of the \textsc{rubik} `bundle')
+% is a small database of some well-known Rubik cube rotation sequences, stored as
+% named macros. For~example, the `fourspot' and `sixspot' sequences are encoded in
+% this package as follows:
+%\begin{verbatim}
+% \newcommand{\fourspot}{[fourspot],F2,B2,U,Dp,R2,L2,U,Dp,<(12q*, 8f*)>}
+% \newcommand{\sixspot}{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>}
+%\end{verbatim}
+% These sequences can be processed by name (using the \cmd{\RubikRotation} command
+% which also requires Perl to be installed---see Section~\ref{sec:rubikrotation}), and
+% then displayed (using the \cmd{\ShowCube} command in conjunction with various
+% \cmd{\DrawRubikCube...} commands). So, for~example, one could typeset the so-called
+% `fourspot' configuration using the following code:
+%\begin{verbatim}
+% \usepackage{tikz,rubikcube,rubikrotation,rubikpatterns}
+% ...
+% \RubikCubeSolved
+% \RubikRotation{\fourspot}
+% \ShowCube{2.4cm}{0.6}{\DrawRubikCubeRU}
+%\end{verbatim}
+% See also the \textsc{rubikrotation} documentation---especially
+% Section~5.1.1 \textit{Sequences as macros}.
%
%
% \subsection{Copyright}
-% Copyright 2014--2015 RWD Nickalls and A Syropoulos.
+% Copyright 2014--2017 RWD Nickalls and A Syropoulos.
%
% \medskip
% {\noindent}This work may be distributed and/or modified under the
@@ -181,31 +233,39 @@
%
% \section{Installation}
%
+% The Rubik bundle consists of the three package \rubikcube, \textsc{rubikrotation}
+% and \textsc{rubikpatterns}, each of which needs to be installed separately.
+% Here we describe the installation of the \rubikcube\ package.
%
-% \subsection{Generating the files}
+% \subsection{Generating the \rubikcube\ files}
%
% Place the file \texttt{rubikcube.zip} into a temporary directory, and unzip it.
% This will generate the following files:
%\begin{verbatim}
% rubikcube.ins
% rubikcube.dtx
-% rubikcube.pdf
-% Rubik-doc-figA.pdf
-% Rubik-doc-figB.pdf
-% Rubik-doc-figC.pdf
-% Rubik-doc-figD.pdf
-% Rubik-doc-figE.pdf
-% Rubik-doc-figF.pdf
+% rubikcube.pdf --documentation of the rubikcube package
+% rubik-doc-figA.pdf
+% rubik-doc-figB.pdf
+% rubik-doc-figC.pdf
+% rubik-doc-figD.pdf
+% rubik-doc-figE.pdf
+% rubik-doc-figF.pdf
+% rubikexamples.tex
+% rubikexamples.pdf
+% rubikexamples.sh
+% rubikexamples.bat
%\end{verbatim}
+%
% The style option \texttt{rubikcube.sty} is generated by running (pdf)\LaTeX\ on
% the file \texttt{rubikcube.ins} as follows:
%\begin{verbatim}
% pdflatex rubikcube.ins
%\end{verbatim}
% This documentation file (\texttt{rubikcube.pdf}) can then be generated using the following
-% 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 several pdflatex runs are required. Prior to the first run it is
+% steps\,\footnote{Several pdflatex runs are required, since the documentation includes
+% an index as well as hyperef links (the package \texttt{hypdoc}
+% is used). Prior to the first run it is
% a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}:
%\begin{verbatim}
% pdflatex rubikcube.dtx
@@ -216,6 +276,14 @@
% pdflatex rubikcube.dtx
%\end{verbatim}
%
+% Note that the package includes a `rubikexamples' file (\texttt{rubikexamples.tex})
+% as well as associated \texttt{.sh} (Linux) and \texttt{.bat} (Microsoft) batch
+% files which can be used to facilitate processing the file.
+% Note that many of the examples in this file use the \cmd{\RubikRotation} command
+% (associated with the \textsc{rubikrotation} package),
+% and hence this file needs to be run using the \verb!--shell-escape! command-line
+% option (see Section~\ref{sec:rubikrotation} for details).
+
%
% \subsection{Placing the files}
%
@@ -229,7 +297,7 @@
%
% \medskip
% {\noindent}Finally, (depending on your system) update the \TeX\ file database.
-% For example, on a Linux system one uses the \texttt{texhash} command.
+% For~example, on a Linux system one uses the \texttt{texhash} command.
%
%
% \subsection{Usage}
@@ -240,212 +308,123 @@
% \begin{quote}
%\begin{verbatim}
% \usepackage{tikz}
-% \usepackage{rubikcube,rubikrotation}
+% \usepackage{rubikcube,rubikrotation,rubikpatterns}
%\end{verbatim}
% \end{quote}
% However, the \rubikcube\ package does check for the presence of TikZ, and will
% load it if TikZ is not already loaded.
% While \rubikcube\ is a stand-alone package, it is best to also load the complementary
-% \textsc{rubikrotation} package.
-%
-%
-% \section{TikZ picture environment}
-% \label{sec:tikz}
-%
-% For a basic introduction to the use of TikZ see the following manuals
-% (from CTAN or from \texttt{http://altermundus.com/}).
-% \begin{itemize}
-% \item \texttt{pgfmanual.pdf}, version 3.0.1a (August 2015) (1161 pages)
-% \item \texttt{pgfplot.pdf}, version 1.12.1 (2015) (504 pages)
-% \item tkz-base-screen.pdf
-% \end{itemize}
-% An example of the TikZ picture environment for use with the \rubikcube\ package
-% is as follows:
-% \begin{quote}
-%\begin{verbatim}
-% \begin{tikzpicture}[scale=0.5]
-% ....
-% \end{tikzpicture}%
-%\end{verbatim}
-% \end{quote}
-% If no scale is used (default scale = 1), then each of the small
-% cubie sides will have a length of 1~cm.
-%
-% A very useful feature of TikZ is that it automatically
-% minimises the surrounding white-space, and consequently this is
-% mostly quite sufficient. However, it is good practice to place
-% a \% symbol after the \verb!\end{tikzpicture}! command *see above)
-% to avoid additional white space (see Section~\ref{sec:trailingpercent}).
-%
-%
-% \subsection[ShowCube command]{\cmd{\ShowCube} command}
-% \label{sec:showcube}
-%
-% \DescribeMacro{\ShowCube}
-% \DescribeMacro{\ShowCubeF}
-% When making side-by-side figures it can be very helpful
-% to place each sub-figure inside a minipage.
-% In this case, a useful approach is to first adjust
-% the tikzpicture `scale' parameter to obtain the appropriate size, and
-% then adjust the minipage width as necessary
-% (see Section~\ref{sec:sizeofminipage}).
-% The \cmd{\ShowCube} macro (See Section~\ref{sec:showcubecode}) places one
-% or more commands inside a tikzpicture environment and places all of
-% these inside a minipage. It takes three arguments: the first is the
-% minipage width (\verb!#1!), second is the tikzpicture scale
-% factor (\verb!#2!), and third is a \cmd{\Draw..} command (|#3|).
-%
-% \noindent\textsc{usage}:
-% The following command would display a Rubik cube in a
-% minipage of width 2cm using a tikzpicture scale factor of 0.5:
-%\begin{verbatim}
-% \ShowCube{2cm}{0.5}{\DrawRubikCubeRU}
-%\end{verbatim}
-% For example, the following two sets of commands are equivalent (see
-% Section~\ref{sec:showcubecode} for the code); i.e.,~any commands which are valid in
-% a \texttt{tikzpicture} environment may be used as the main argument for the
-% \cmd{\ShowCube} command.
-% $$
-% \left.
-% \begin{array}{l}
-% \verb!\RubikCubeSolved!\\
-% \verb!\begin{minipage}{2cm}!\\
-% \ \ \verb!\centering!\\
-% \ \ \verb!\begin{tikzpicture}[scale=0.5]!\\
-% \ \ \ \ \ \verb!\DrawRubikCubeRU!\\
-% \ \ \ \ \ \verb!\draw[->] (0.5,5) -- (0.5,4);!\\
-% \ \ \verb!\end{tikzpicture}!\\
-% \verb!\end{minipage}!\\
-% \end{array}
-% \right\}
-% \begin{array}{l}
-% \verb!\RubikCubeSolved!\\
-% \verb!\ShowCube{2cm}{0.5}{%!\\
-% \ \ \ \ \verb!\DrawRubikCubeRU!\\
-% \ \ \ \ \verb!\draw[->] (0.5,5) -- (0.5,4);!\\
-% \ \verb!}!\\
-% \end{array}
-% $$
-%
-% The \cmd{\ShowCubeF} command is similar in all respects except that it places
-% an fbox around the minipage in order to enable users to see the extent of any
-% associated white space.
-%
-% Unexpected spacing between two adjacent images, or between an
-% image and adjacent text, is usually related to
-% `hidden' white-space associated with the image itself or excessive width
-% of the associated \cmd{\minipage} (see also Section~\ref{sec:trailingpercent}).
-% Consequently, a temporary fbox around the minipage can be a
-% useful aid when trying to visualise the full extent of the minipage
-% (and its associated whitespace). Use the \cmd{\ShowCubeF} command for this, as follows:
-%
-% \medskip
-%
-% \RubikCubeSolved
-% \ShowCubeF{4cm}{0.3}{\DrawRubikCubeRU}
-%\begin{minipage}{5cm}
-%\begin{verbatim}
-% \ShowCubeF{4cm}{0.3}{\DrawRubikCubeRU}
-%\end{verbatim}
-%\end{minipage}
-%
-% \medskip
-% {\noindent}Clearly either the minipage is too wide (4cm) or the \texttt{tikzpicture}
-% scale factor is too small (0.3). Once the figure/code has been corrected, then the
-% \texttt{F} in the \cmd{\ShowCubeF} command can be removed. Note that while
-% the \cmd{\ShowCube} command centers the image inside the minipage, \LaTeX\ positions
-% the minipage in the \cmd{\textwidth}, and hence it is generally best to minimise
-% the white-space as revealed by the \cmd{\ShowCubeF} command. The relationship
-% between the required width of the minipage and the TikZ scale factor for the various
-% Rubik cube images is detailed in Section~\ref{sec:sizeofminipage}.
+% \textsc{rubikrotation} and \textsc{rubikpatterns} packages.
%
%
+% \DescribeMacro{\rubikcube}
+% This command generates the logo \rubikcube.
%
-% \subsection[Draw.. error message]{\cmd{\Draw} error message}
-% \label{sec:drawerrormessage}
%
-% If a \rubikcube\ \cmd{\Draw..} command is used \textit{outside} a
-% TikZ picture environment, then \LaTeX\ issues an
-% ``Undefined control sequence'' error message, indicating
-% that it is trying to draw something using an undefined
-% TikZ \cmd{\draw} command.
%
-% For example, if we use the \rubikcube\ command
-% \cmd{\DrawRubikFlat} without a surrounding TikZ picture environment
-% then something similar to the following error message will be generated.
-%\begin{verbatim}
-%! Undefined control sequence.
-%\DrawFlatUp ... }{#1}\pgfmathsetmacro {\uy }{#2}\draw
-% [line join=round,...
-%l.56 \DrawRubikFlat
-%\end{verbatim}
+% \section{Command conventions}
+% \label{sec:conventions}
%
%
+% All \rubikcube\ package commands assume a 3x3x3 cube by default.
+% There are three primary command categories: (a)~\cmd{\Draw..} commands
+% (which must always be used \textit{inside} a TikZ picture environment),
+% (b)~`parameter-allocation' commands---e.g.,~\cmd{\RubikCubeSolved}---which can
+% be used either inside or outside a TikZ environment),
+% and (c)~commands which can be used in ordinary text
+% (e.g.,~|\rr{}| rotation commands).
%
-% \section{Command conventions}
-% \label{sec:conventions}
%
-% \subsection{Commands and environments}
+% \subsection{Environments}
%
% Although the \rubikcube\ package has been designed with TikZ in mind,
-% it is important to appreciate that of all the various \rubikcube\
+% it is important to appreciate that of all the various \rubikcube\ package
% commands only the Rubik \cmd{\Draw...} commands and TikZ commands actually
% have to be used inside a TikZ picture environment.
%
-% Indeed, using \rubikcube\ commands which influence the Rubik colour state
+% Indeed, using \rubikcube\ package commands which influence the Rubik colour state
% (configuration) outside the \texttt{tikzpicture}, \texttt{minipage} or
% \texttt{figure} environments can make for useful
% flexibility when a document is generating more than one figure
% or image. This is because the scope of any colours specified by commands inside
% these environments is constrained to
% be `local' to that particular environment, and hence any change in the
-% Rubik colour state brought about by such commands is not accessable
+% Rubik colour state brought about by such commands is not accessible
% globally (i.e.,~outside the environment) ---see also Section~5 in the documentation
% of the \textsc{rubikrotation} package.
%
% Consequently users need to be mindful of the environments when
-% drawing long sequences of rotations across several figures; for example, keeping
-% \cmd{\RubikRotation} commands outside the environments keeps their effects global.
+% drawing sequences of rotations across several figures; for~example, keeping commands like
+% \cmd{\RubikRotation}, \cmd{\RubikFace..}, \cmd{\RubikSide..}, \cmd{\RubikCubeSolved},
+% outside the environments keeps their effects global.
+%
%
% \subsection{Capital letters}
%
-% Each `word' in a command (except the word `text') starts with a capital letter.
-% For example, \cmd{\DrawRubikCubeRU}, \cmd{\DrawCubieRU}.
-% However, as with \LaTeX, `text..' commands start with a lowercase `t';
-% for example \cmd{\textCubieRU}. Letters for colours (R, O, Y, G, B, W, X) are
-% always written in uppercase.
+% Virtually all Rubik bundle commands start with a capital letter, primarily to
+% avoid any confusion with TikZ commands (these generally start with lower-case letters). However,
+% each `word' in a Rubik bundle command (except the word `text') also starts
+% with a capital letter, primarily to facilitate readability.
+% For~example, \cmd{\DrawRubikCubeRU}, \cmd{\DrawCubieRU}.
+% However, as with \LaTeX, `text..' commands start with a lower-case `t';
+% for~example \cmd{\textCubieRU}. Letter arguments for colours (R, O, Y, G, B, W, X) are
+% always written in upper-case letters.
+%
%
%
% \subsection{XYZ argument ordering}
+% \label{sec:xyzarguments}
+%
+% Many commands have an appended two, three, or even six ordered arguments or letters
+% which form some feature of the structure of a command; perhaps
+% either face or colour code or a viewpoint direction.
%
-% Many commands have an appended two (XY) or three (XYZ) ordered letter code
-% which is used to for specifying some feature of the command; perhaps
-% either face or cubie colours or a viewpoint direction.
+% We adopt the convention that where ordering of arguments is critical, then the
+% arguments are ordered in the XYZ, $+$, $-$ order. An XYZ code implies that
+% the first letter in the code relates to an X-related parameter,
+% for~example, L (Left) or R (Right); the second letter relates to a Y-related
+% parameter, for~example, U (Up) or D (Down); the third (if required)
+% relates to a Z-related parameter, for~example, F (Front) or B (Back)
+% ---see Figure~\ref{fig:notation}.
%
-% The convention is that the letter codes are ordered in the XYZ order;
-% i.e.,~the first code relates to an X-related parameter;
-% for example L (Left) or R (Right); the second relates to a Y-related
-% parameter; for example U (Up) or D (Down); the third (if required)
-% relates to a Z-related parameter; for example F (Front) or B (Back).
+% Some commands have six arguments which adopt an (XYZ;$+$$-$) format. In this case,
+% for~example, the \cmd{\SolvedConfig} command, for which the six colour arguments
+% are ordered as X$+$, X$-$, Y$+$, Y$-$, Z$+$, Z$-$. Here the colour argument
+% associated with a face positioned on the $+$ve axis is ordered before
+% its $-$ve complement on the same axis.
%
+% Another example is the |\DrawCubieRU{G}{Y}{O}| command, which draws a cubie. Here
+% the RU letters are XY ordered; i.e.,~RightUp viewpoint. The sequence of colour codes
+% for the three visible faces are XYZ ordered, and hence result in the cube having a
+% Green Right face, Yellow Up face and Orange Front face.
%
-% \textsc{example}: |\DrawCubieRU{G}{Y}{O}| draws a cubie from
-% the RightUp viewpoint. The sequence of colour codes for the three visible
-% faces are XYZ ordered, and hence result in the cube having a Green Right face,
-% Yellow Up face and Orange Front face.
%
%
% \subsection{Trailing \% on the end of commands}
% \label{sec:trailingpercent}
%
-% It is important to include a trailing \% on the end of \rubikcube\
-% commands when used \textit{outside} a TikZ picture environment, and
-% also on the end of each \cmd{\end\{tikzpicture\}} environment command.
-% This is to prevent unwanted `space' characters appearing in
-% the graphics. In \TeX\ every newline character is automatically converted
+% Since the all the output of this package is drawn using graphic elements
+% using TikZ, it is important to include a trailing \% on the end
+% of \rubikcube\ package commands when used \textit{outside} a TikZ picture environment, and
+% also on the end of the \cmd{\end\{tikzpicture\}} environment command itself.
+% In particular it is important to use a trailing \% on
+% the end of lines which break before the terminal curly bracket of a \cmd{\newcommand}.
+%
+% This is to prevent accumulating spurious spaces which may otherwise appear in
+% figures and diagrams as a strange or unexpected horizontal shift or white-space.
+% That this can occur is because in \TeX\ every newline character is automatically converted
% to a white space---unless you have an empty line
-% (Feuers\"{a}nger 2015, \S\,3.2.3, page~20).
+% (Feuers\"{a}nger 2016).
+%
+% The \LaTeX\ fbox is a useful aid for visualising unwanted white space
+% which may have accumulated, and for identifying the cause.
+% See Section~\ref{sec:showcube} on the \cmd{\ShowCubeF} command for
+% more regarding this approach.
%
+% Although this effect is mostly small, and is generally only observed in situations
+% when centering a graphic is critical, it is, however, cumulative and can be surprisingly large.
+% In these situations, the cure is the addition of terminal \% characters to preceding
+% code guided by careful detective use of the fbox technique mentioned above.
%
%
% \subsection{Cubies, cubicles, faces and facelets}
@@ -457,38 +436,283 @@
%
% We distinguish three types of cubie:
% centre-cubies (single colour), edge-cubies (two colours) and corner-cubies
-% (three colours). For example, the red/white edge-cubie is called
+% (three colours). For~example, the red/white edge-cubie is called
% the RW cubie, and the red/white/green corner-cubie is called the
% RWG cubie etc. Note that the colour of a particular face of a 3x3x3 Rubik
% cube is determined by the colour of its centre-cubie.
%
% Similarly, the positions (known as `cubicles') occupied by cubies are
-% defined using either a two or three letter face code. For example the
+% defined using either a two or three letter face code. For~example, the
% right edge position in the Up-layer is termed the Up/Right position,
% or just the UR position, and the corner joining the \textsc{down}
% \textsc{front} and \textsc{right} faces is the DFR position.
%
%
%
-% \section{Colours}
+% \section{Rubik cube coordinates}
+% \label{sec:coordinates}
+%
+% The coordinate origin of all 2D Rubik cube images is located
+% at the bottom-left corner of the \textsc{front} face, as shown in
+% Figure~\ref{fig:cubesquaregraph}. Note also that the bottom left
+% extent of this particular 2D rendering of the cube is actually at $(-1,-1)$,
+% and hence the default height and width of all oblique-view cubes is 4~units
+% (i.e.,~equivalent to 4cm if the TikZ scale-factor = 1).
+%
+% \begin{figure}[hbt]
+% \centering
+% \ifpdf
+% \includegraphics[height=4cm]{rubik-doc-figB.pdf}
+% \else
+% \includegraphics[height=4cm]{rubik-doc-figB.eps}
+% \fi
+%
+% \parbox{9cm}{\caption{\label{fig:cubesquaregraph}Origin of coordinates
+% is at the bottom left corner of the grey \textsc{front} face.
+% Since $P$ is at $(-1,-1)$ then the default height and width of the
+% 2D~cube image is 4~units.}}
+% \end{figure}
+%
+% Arranging for $P$ to be at $(-1,-1)$, as well as using the bottom-left corner
+% of the \textsc{front} face as the origin, are useful design
+% features which make it easy to know the coordinates of any point, and hence
+% facilitate the use any of the TikZ commands
+% (e.g.,~\cmd{\draw} and \cmd{\node} commands) to superimpose lines,
+% arrows and text etc.,~onto the Rubik cube (see Section~\ref{sec:arrows}).
+
+%
+% \subsection[Size of cube minipage]{Size of cube \cmd{\minipage}}
+% \label{sec:sizeofminipage}
+%
+% Since the the default height and width of the oblique 2D~cube image is
+% 4~units (see Section~\ref{sec:coordinates} above),
+% it follows that the width of the \cmd{\minipage} required for a cube in a
+% \texttt{tikzpicture} environment can be easily calculated. For~example,
+% if the \texttt{tikzpicture} scale factor used is $0.5$, then the minimum
+% width of the required minipage for the \cmd{\DrawRubikCubeLD} view (shown above)
+% is therefore $0.5 \times 4\mbox{cm} = 2\mbox{cm}$.
+%
+% Note that the width of the semi-flat (SF) cube representation is therefore
+% 10~units ($=3+3+1+3$), and that of the flat (F) cube is 12~units ($=3+3+3+3$)
+% --- see Section~\ref{sec:flatcommands} for images of these forms.
+% If in doubt check the horizontal extent of an image using the \cmd{\ShowCubeF} command,
+% which places an fbox around the image.
+%
+%
+%
+% \section{TikZ picture environment}
+% \label{sec:tikz}
+%
+% All the Rubik bundle \cmd{\Draw..} commands are designed to be used
+% with the TikZ picture environment, and are compatible with standard TikZ.
+% For a basic introduction to the use of TikZ see the following manuals
+% (from CTAN or from \texttt{http://altermundus.com/}).
+% \begin{itemize}
+% \item \texttt{https://en.wikipedia.org/wiki/PGF/TikZ}
+% \item \texttt{pgfmanual.pdf}, version 3.0.1a (?\,2013) (1161 pages)
+% \item \texttt{pgfplot.pdf}, version 1.13 (2016) (544 pages)
+% \item \texttt{tkz-base-screen.pdf}, version 1.16c (2011) (91 pages)
+% \end{itemize}
+% An example of the TikZ picture environment for use with the Rubik bundle
+% is as follows:
+% \begin{quote}
+%\begin{verbatim}
+% \begin{tikzpicture}[scale=0.5]
+% ...
+% \end{tikzpicture}%
+%\end{verbatim}
+% \end{quote}
+% If no scale-factor is used (default scale-factor = 1), then each of the small
+% cubie sides will have a length of 1~cm.
+%
+% \textsc{useful commands}:\ Probably the most
+% useful TikZ commands for use with regard
+% to the Rubik bundle are the \cmd{\draw} command (for drawing lines, arrows, circles),
+% and the \cmd{\node} command (for writing text at specific coordinate locations).
+% The basic structure of these commands is as~follows, where
+% (x,y) represent grid coordinates of start or end points of lines or arrows,
+% or of a circle centre, or of text position (see Sections~\ref{sec:flatcommands}
+% and \ref{sec:arrows} for examples).
+% \begin{quote}
+% \begin{verbatim}
+% \draw[->,thick,color=blue] (4.5, 2.5) -- (3.5,2.5);
+% \draw[->,ultra thick,color=red] (4.5, 2.5) -- (3.5,2.5);
+% \draw [color=blue, thick] (0.3, 0.3) circle (1.3);
+% \node (B) at (7.5, 1.5) [black]{\small\textsf{B}};
+%\end{verbatim}
+%\end{quote}
+% Remember that all TikZ commands which are valid inside a \texttt{tikzpicture}
+% environment require a terminal semicolon (see Section~\ref{sec:arrows}
+% for examples).
+%
+% \textsc{colours}: \
+% The following colors are predefined by TikZ: red, green, blue, cyan, magenta,
+% yellow, black, gray, darkgray, lightgray, brown, lime, olive, orange, pink,
+% purple, teal, violet and white (see \texttt{https://en.wikipedia.org/wiki/PGF/TikZ}).
+%
+% \textsc{line width}: \
+% TikZ allows line width to be specified directly
+% (e.g.,~\texttt{[line width=<dimension>]}), or by using the following abbreviations:
+% `ultra thin' for 0.1pt, `very thin' for 0.2pt, `thin' for 0.4pt (the default width),
+% `semi thick' for 0.6pt, `thick' for 0.8pt, `very thick' for 1.2pt,
+% `ultra thick' for 1.6pt (see \texttt{https://en.wikipedia.org/wiki/PGF/TikZ}).
+%
+%% \textsc{white space}: \
+% A particularly useful feature of TikZ is that it automatically
+% minimises any horizontal white-space. However, it is good practice to place
+% a \% symbol after the \verb!\end{tikzpicture}! command *see above)
+% to avoid additional white space inadvertently being added by \LaTeX\
+% (see Section~\ref{sec:trailingpercent}).
+%
+% When making images it can be helpful to place them inside a minipage
+% (e.g.,~using the \cmd{\ShowCube} command / environment below).
+% A~convenient approach is to first adjust the value of the tikzpicture scale-factor
+% (to obtain the appropriate size), and then adjust the minipage-width as necessary, using
+% the fbox associated with the \cmd{\ShowCubeF} command
+% (see Section~\ref{sec:sizeofminipage} for a useful guide on this).
+%
+% The main `display' tool for drawing cubes is the \cmd{\ShowCube} command
+% (see below), and this incorporates a
+% TikZ picture environment inside a minipage. The equivalent tool for
+% displaying rotation sequences is the \cmd{\ShowSequence} command.
+%
+%
+%
+%
+%
+% \section[ShowCube command]{\cmd{\ShowCube} command}
+% \label{sec:showcube}
+%
+%
+% \DescribeMacro{\ShowCube}
+% This command \cmd{\ShowCube}\marg{width}\marg{scale-factor}\marg{commands}
+% is a convenient tool which places one or more commands inside a
+% tikzpicture environment and places all of these inside a minipage
+% (see Section~\ref{sec:showcubecode} for the code).
+% This command takes three arguments: the first (\verb!#1!) is the minipage width,
+% the second (\verb!#2!) is the tikzpicture scale factor, and the third (\verb!#3!)
+% is a series of any \rubikcube\ package \cmd{\Draw..} and other commands, as well as
+% any TikZ commands which are valid in a \texttt{tikzpicture} environment
+% (e.g.,~\cmd{\draw} or \cmd{\node} etc.).
+%
+% \medskip
+%
+% \noindent\textsc{usage}:
+% The following \cmd{\ShowCube} command displays a Rubik cube
+% (the `SixT's configuration\footnote{The \cmd{\sixts} macro is from the \textsc{rubikpatterns}
+% package.}) and a blue arrow in a minipage of width~3cm, using a tikzpicture scale
+% factor of~0.5.
+% Note that the TikZ \cmd{\draw} command requires a terminal
+% semicolon---see Section~\ref{sec:tikz}.
+%
+% \medskip
+%
+% {\noindent}%
+% \begin{minipage}{6.6cm}
+%\begin{verbatim}
+% \RubikCubeSolved
+% \RubikRotation{\sixts}
+% \ShowCube{3cm}{0.5}{%
+% \DrawRubikCubeLU
+% \draw[->,thick,color=blue] (4.5, 2.5) -- (3.5,2.5);
+% }
+%\end{verbatim}
+% \end{minipage}
+% \hspace{2.5cm}%
+%\RubikFaceUp{Y}{Y}{W}{W}{W}{W}{Y}{Y}{W}%
+%\RubikFaceDown{Y}{W}{W}{Y}{Y}{Y}{Y}{W}{W}%
+%\RubikFaceLeft{B}{G}{G}{B}{B}{B}{B}{G}{G}%
+%\RubikFaceRight{G}{B}{B}{G}{G}{G}{G}{B}{B}%
+%\RubikFaceFront{O}{O}{O}{R}{O}{R}{R}{O}{R}%
+%\RubikFaceBack{O}{R}{O}{O}{R}{O}{R}{R}{R}%
+% \ShowCube{3cm}{0.5}{%
+% \DrawRubikCubeLU
+% \draw[->,thick,color=blue] (4.5, 2.5) -- (3.5,2.5);
+% }
+%
+% \medskip
+%
+% {\noindent}The convenience of the \cmd{\ShowCube} command is illustrated below; the
+% \cmd{\ShowCube} command on the left is equivalent to the bunch of commands
+% on the right (see Section~\ref{sec:showcubecode} for the complete code).
+% $$
+% \left.
+% \begin{array}{l}
+% {\ }\\
+% {\ }\\
+% \verb!\ShowCube{3cm}{0.5}{...}!\\
+% {\ }\\
+% {\ }\\
+% \end{array}
+% \right\{
+% \begin{array}{l}
+% \verb!\begin{minipage}{3cm}%!\\
+% \verb!\centering%!\\
+% \verb!\begin{tikzpicture}[scale=0.5]!\\
+% ...\\
+% \verb!\end{tikzpicture}%!\\
+% \verb!\end{minipage}%!\\
+% \end{array}
+% $$
+%
+% \DescribeMacro{\ShowCubeF}
+% The \cmd{\ShowCubeF} command is similar in all respects except that it places
+% an fbox around the minipage in order to enable users to see the extent of any
+% associated white space. For~example, unexpected spacing between two adjacent images,
+% or between an image and adjacent text, is usually related to
+% `hidden' white-space associated with the image itself or excessive width
+% of the associated \cmd{\minipage} (see also Section~\ref{sec:trailingpercent}).
+% Consequently, a temporary fbox around the minipage can be a
+% useful aid when trying to visualise the full extent of the minipage
+% (and its associated white-space). Use the \cmd{\ShowCubeF} command for this.
+
+% For~example, the following use of the \cmd{\ShowCubeF} command reveals a significant
+% white-space problem:
+%
+% \medskip
+%{\noindent}%
+%\begin{minipage}{6.6cm}
+%\begin{verbatim}
+% \ShowCubeF{4cm}{0.3}{\DrawRubikCubeRU}
+%\end{verbatim}
+%\end{minipage}
+% \RubikCubeSolved
+% \ShowCubeF{4cm}{0.3}{\DrawRubikCubeRU}
+%
+% \medskip
+% {\noindent}In this example, clearly either the minipage is too wide (4cm) or the \texttt{tikzpicture}
+% scale factor is too small (0.3). Once the figure/code has been corrected, then the
+% \texttt{F} in the \cmd{\ShowCubeF} command can be removed.
+%
+% Note that while the \cmd{\ShowCube} command centres the image
+% inside the minipage, \LaTeX\ positions
+% the minipage in the \cmd{\textwidth}, and hence it is generally best to minimise
+% the white-space as revealed by the \cmd{\ShowCubeF} command. The~relationship
+% between the required width of the minipage and the TikZ scale factor for the various
+% Rubik cube images is detailed in Section~\ref{sec:sizeofminipage}.
+%
+%
+%
+% \section{Colour commands}
+% \label{sec:colours}
%
% The \rubikcube\ package uses seven colours which are defined as follows:
-% red~(R), orange~(O), yellow~(Y), green~(G), blue~(B), white~(W),
-% and grey~(X). Now according to the following webpage\,\footnote{We thank Peter Bartal
-% for bringing this to our attention.}
+% R~(red), O~(orange), Y~(yellow), G~(green), B~(blue), W~(white),
+% and X~(grey). Now according to the following webpage\,\footnote{We thank Peter Bartal
+% for bringing this webpage to our attention.}
%
% \medskip
% \noindent\texttt{http://The-Rubiks-Cube.deviantart.com/journal/Using-Official-Rubik}
-% \newline\texttt{-s-Cube-Colors-268760351}
+% \newline\texttt{-s-Cube-Colors-268760351} (Nov 2011)
%
% \medskip
% {\noindent}the official Rubik cube colours are defined as
% \begin{quote}
%\begin{verbatim}
-% .... colours which are red (PMS 200C*), green (PMS 347C*),
+% ... colours which are red (PMS 200C*), green (PMS 347C*),
% blue (PMS 293C*), orange (PMS 021C*), yellow (PMS 012C*)
% and white.
-% .....
+% ...
% Pantone colors can not be accurately converted to RGB colors,
% the colors the web runs on. But they can be approximated.
% Through some research, I have found some estimations which
@@ -512,10 +736,13 @@
%\end{verbatim}
% \end{quote}
% However, we have optimised these prescribed colours very slightly
-% for screen \& print use (for example, the yellow was made very
+% for screen \& print use (for~example, the yellow was made very
% slightly brighter), and so the actual colours implemented by
-% the \rubikcube\ package are as follows
-% (see Section~\ref{sec:codecolours}):
+% the \rubikcube\ package are as follows:\,\footnote{Although the Pantone
+% colours cannot be converted to RGB, there is a subset of of Pantone colours
+% which can be be converted using CMYK
+% (see \texttt{https://en.wikipedia.org/wiki/Pantone})}.
+% (see Section~\ref{sec:codecolours}):
%
% \begin{quote}
%\begin{verbatim}
@@ -529,8 +756,8 @@
%\end{verbatim}
% \end{quote}
% Different colours can be allocated to the ROYGBWX letters (using the
-% \cmd{\colorlet} command) as required. For example, the standard `red'
-% colour could be allocated to the letter R using the command
+% standard \LaTeX\ \cmd{\colorlet} command) as required. For~example, the
+% standard `red' colour could be allocated to the letter R using the command
% \begin{quote}
% \cmd{\colorlet\{R\}\{red\}}
% \end{quote}
@@ -543,140 +770,495 @@
% \subsection{Colour state of the cube}
% \label{sec:colourstate}
%
+%
+% \DescribeMacro{\RubikFace..}
+% \DescribeMacro{\RubikSlice..}
+% \DescribeMacro{\RubikSide..}
+% \DescribeMacro{\RubikCubeSolved}
+% \DescribeMacro{\RubikCubeGrey}
+% \DescribeMacro{\RubikCubeGreyAll}
% Initially, when \LaTeX\ reads the file \texttt{rubikcube.sty} all facelets
-% are allocated the code X, which can be regarded as a zero-colour state.
-% Until a facelet is allocated one of the six Rubik colours it will be rendered as
-% grey by a command which just draws the current colour state of the cube or a face
-% (e.g.,~\cmd{\DrawFlatUpSide}).
+% are allocated the colour-code X, which can be regarded as a zero-colour state.
+% Until a facelet is allocated one of the six Rubik colours (using a suitable command)
+% it will be rendered as grey by a Rubik \cmd{\Draw...} command, since these commands
+% simply implement the current colour state of the cube (e.g.,~\cmd{\DrawRubikCubeRU}).
%
% It is important to appreciate that the various commands which typeset faces
% or facelets with colours differ in whether they derive the colours
% from the current internal colour `state' (configuration) of the Rubik cube, or not.
+%
+% The colour state of cubies in faces and slices can be allocated using \cmd{\RubikFace...},
+% \cmd{\RubikSlice...} and \cmd{\RubikSide...} commands (see Sections~\ref{sec:facecommands},
+% \ref{sec:slicecommands} and \ref{sec:rubikside}).
+% In addition. the command \cmd{\RubikCubeSolved}, allocates a prescribed colour state
+% for the whole `solved' cube, and is a very useful starting
+% point (configuration) for subsequent rotations.
+% The commands \cmd{\RubikCubeGrey} and \cmd{\RubikCubeGreyAll} allocate different colour
+% states for the whole cube, and are designed to be useful starting points when illustrating
+% aspects of how to solve the cube. These two commands accept both `grey' and `gray'
+% (to be consistent with TikZ).
+% Cubies retain their colour allocation even if the cubies are moved using
+% the \cmd{\RubikRotation} command (\textsc{rubikrotation} package), unless they are
+% overwritten by a subsequent colour allocation command.
+%
+% To visualise the current state of the cube one has to use a Rubik \cmd{\Draw...} command.
+% Although some \cmd{\Draw...} commands (e.g.,~\cmd{\DrawRubikLayerFace...}) allow
+% you to specify colours as arguments, \cmd{\Draw...} commands really only
+% `paint' colours onto cubie positions (on the page, so to speak).
+% \cmd{\Draw..} commands never influence the internal Rubik colour state.
+%
+% The current colour state / configuration of the Rubik cube can be saved and
+% written to a named file (using the \cmd{\SaveRubikState} command) in a form
+% which can then be easily \cmd{\input} and processed when required.
+
+%
+% \subsection{RubikFace commands}
+% \label{sec:facecommands}
+%
+% \DescribeMacro{\RubikFaceUp}
+% \DescribeMacro{\RubikFaceDown}
+% \DescribeMacro{\RubikFaceLeft}
+% \DescribeMacro{\RubikFaceRight}
+% \DescribeMacro{\RubikFaceFront}
+% \DescribeMacro{\RubikFaceBack}
+% These commands take nine colour arguments and allocate colours to the
+% individual cubies of a Rubik cube face.
+% The ordering is isomorphic to the sequence 1--9, i.e.,~numbering the small
+% squares 1-3~(top row, left to right), 4-6~(middle row, left to right),
+% 7-9~(bottom row, left to right), as follows:
+% \begin{quote}
+% \fbox{
+% \begin{minipage}{1.6cm}
+% \#1 \#2 \#3
+%
+% \#4 \#5 \#6
+%
+% \#7 \#8 \#9
+% \end{minipage}
+% }
+% \end{quote}
+% Conveniently, \LaTeX\ allows the colour arguments to be separated by spaces
+% (e.g.,~separated in groups of three), or even spread across several
+% lines (e.g.,~in a square block to resemble a 9-face). This is fortunate, as it
+% allows the command to be formulated in a visually intuitive way, as in the
+% following examples.
+%
+% \begin{quote}
+% \begin{minipage}{8cm}
+%\begin{verbatim}
+% \RubikFaceUp{G}{B}{G} {G}{W}{O} {G}{O}{G}
+%
+% \RubikFaceFront{O}{W}{R}
+% {W}{W}{W}
+% {G}{W}{G}
%
-% The colour state of cubies in faces and slices can be allocated using \cmd{\RubikFace...}
-% and \cmd{\RubikSlice...} (see Sections~\ref{sec:facecommands} and \ref{sec:slicecommands}).
-% The commands \cmd{\RubikCubeSolved} and \cmd{RubikCubeGrey} allocate the colour state
-% for the whole cube, and are useful starting points for subsequent rotations.
-% Note that cubies will retain their colour allocation even if the cubies are are moved by
-% rotation commands, unless they are overwritten by a subsequent colour allocation command.
-% To then visualise the cube one has to use a \cmd{\Draw...} command.
-%
-% The \textsc{rubikrotation} package keeps track of the Rubik state following
-% rotations and sequences of rotations processed by its \cmd{\RubikRotation} command.
-% The current colour state of the Rubik cube can be saved and written to a named file
-% using its \cmd{\SaveRubikState} command; this file can then be \cmd{\input} when required.
-%
-% Note that although some \cmd{\Draw...} commands (e.g.,~\cmd{\DrawRubikLayerFace...}) use
-% colours as arguments, these commands really only `paint' colours onto cubie positions
-% (on the page, so to speak); i.e.,~these commands do not update the internal Rubik
-% colour state, and hence these colours do not exist outside the particular
-% \texttt{tikzpicture} environment the \cmd{\Draw..} command was used in.
+%\end{verbatim}
+% \end{minipage}
+% \end{quote}
%
+% \DescribeMacro{\RubikFaceUpAll}
+% \DescribeMacro{\RubikFaceDownAll}
+% \DescribeMacro{\RubikFaceLeftAll}
+% \DescribeMacro{\RubikFaceRightAll}
+% \DescribeMacro{\RubikFaceFrontAll}
+% \DescribeMacro{\RubikFaceBackAll}
+% Each of the above commands has an associated
+% `\texttt{All}' version which allocates the same colour to all the cubies
+% on a 9-face (i.e.,~only a single colour argument is required).
%
-% \section{Rubik cube coordinates}
-% \label{sec:coordinates}
+% If you want a particular face to be all grey, then
+% use the colour-code~X; for~example, \cmd{\RubikFaceUpAll\{X\}}.
+% Failure to include a valid colour argument will generate a
+% `missing parameter' error, and no colour will be
+% allocated (i.e.,~you will see a black-hole).
+% Use of these commands is shown in the following figure.
%
-% The coordinate origin of each view of the Rubik cube is located
-% at the bottom-left corner of the \textsc{front} face, as shown in
-% Figure~\ref{fig:cubesquaregraph}. Note also that the bottom left
-% corner of the cube itself is at $(-1,-1)$,
-% and hence the default height and width of the cube is 4cm.
+% \bigskip
+%
+% \begin{minipage}{2.8cm}
+% \RubikFaceUpAll{X}
+% \RubikFaceRightAll{R}
+% \RubikFaceFront{W}{Y}{G}
+% {W}{Y}{G}
+% {W}{Y}{G}
+% \begin{tikzpicture}[scale=0.7]
+% \DrawRubikCubeRU
+% \end{tikzpicture}%
+% \end{minipage}
+% \hspace{5mm}
+% \begin{minipage}{0.6\textwidth}
+%\begin{verbatim}
+% \RubikFaceUpAll{X}
+% \RubikFaceRightAll{R}
+% \RubikFaceFront{W}{Y}{G}
+% {W}{Y}{G}
+% {W}{Y}{G}
+% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU}
+% \end{verbatim}
+% \end{minipage}
+%
%
-% Using the \textsc{front} bottom-left corner as the origin
-% is an important feature since knowing the location of the
-% origin enables one to easily use any of the TikZ commands
-% (e.g.,~\cmd{\draw} and \cmd{\node} commands) to superimpose lines,
-% arrows and text etc.\ onto the Rubik cube (see Section~\ref{sec:arrows}).
+% \subsection{Solved Configuration}
+% \label{sec:solvedconfig}
%
-% \begin{figure}[hbt]
+% \DescribeMacro{\SolvedConfig}
+% This command allocates the six face colours according to the following ordered
+% XYZ$+-$ argument rule, namely X$+$, X$-$, Y$+$, Y$-$, Z$+$, Z$-$; i.e.,~the order
+% of the six colour arguments follows the face order
+% \textsc{right, left, up, down, front, back} (for notation see
+% Section~\ref{sec:xyzarguments} and Figure~\ref{fig:notation}).
+% {\newline}\textsc{usage}:\ \verb!\SolvedConfig{G}{B}{W}{Y}{O}{R}!
+% {\newline}Examples of its use are shown in the next section.
+%
+%
+% \subsection{RubikCubeSolved command}
+% \label{sec:rubikcubesolved}
+%
+% \DescribeMacro{\RubikCubeSolved}
+% \DescribeMacro{\RubikCubeSolvedWY}
+% The action of both of these commands is identical:
+% they both set all the face colours to the following standard `solved' cube
+% configuration, namely Up=white, Down=yellow, Right=green, Left=blue, Front=orange, Back=red,
+% by invoking the above \cmd{\SolvedConfig} command, as follows:
+%\begin{verbatim}
+%\newcommand{\RubikCubeSolved}{\SolvedConfig{G}{B}{W}{Y}{O}{R}}
+%\end{verbatim}
+% Note that this is in fact just a convenient short-hand for the following:
+%\begin{verbatim}
+%\newcommand{\RubikCubeSolved}{%
+% \RubikFaceRightAll{G}%
+% \RubikFaceLeftAll{B}%
+% \RubikFaceUpAll{W}%
+% \RubikFaceDownAll{Y}%
+% \RubikFaceFrontAll{O}%
+% \RubikFaceBackAll{R}%
+%}
+%\end{verbatim}
+% Note that for convenience, this configuration is also available using the command
+% \verb!\RubikCubeSolvedWY! (WY denoting White opposite Yellow).
+% This solved configuration is shown in the following
+% semi-flat (SF) image.
+%
+%
+% \bigskip
+%
+% \begin{minipage}{5cm}
% \centering
-% \ifpdf
-% \includegraphics[height=3cm]{Rubik-doc-figB.pdf}
-% \else
-% \includegraphics[height=3cm]{Rubik-doc-figB.eps}
-% \fi
+% \begin{tikzpicture}[scale=0.5]
+% \RubikCubeSolvedWY
+% \DrawRubikCubeSF
+% \end{tikzpicture}%
+% \end{minipage}
+% \begin{minipage}{0.5\textwidth}
+%\begin{verbatim}
+% \RubikCubeSolvedWY
+% \ShowCube{5cm}{0.5}{\DrawRubikCubeSF}
+%\end{verbatim}
+% \end{minipage}
%
-% \parbox{9cm}{\caption{\label{fig:cubesquaregraph}Origin of coordinates
-% is at the bottom left corner of the grey \textsc{front} face.
-% The bottom left corner of the cube itself is at $(-1,-1)$,
-% and hence the default height and width of the 3D-cube is 4cm.}}
-% \end{figure}
+% \bigskip
%
+% Note that the width of the minipage used in \cmd{\ShowCube} command above
+% is set to 5cm. This value is derived from the fact
+% that the \textit{unscaled} width of the semi-flat image is 10cm (9 + 1 squares), and hence if
+% the TikZ scale factor is set to 0.5 then the minimum minipage width = $10 \times 0.5 = 5$cm
+% (see Section~\ref{sec:coordinates} for details).
%
%
-% \subsection[Size of cube minipage]{Size of cube \cmd{\minipage}}
-% \label{sec:sizeofminipage}
+% \textbf{Other orientations:} If other orientations of the solved cube are required,
+% this can be easily achieved using the \cmd{\RubikRotation} command
+% (from the \texttt{RubikRotation} package) to rotate the cube as required.
+% For~example, we could make a command to show the above solved cube upsidedown
+% and rotated slightly, as follows:
+%\begin{verbatim}
+%\newcommand{\CubeUpSideDown}{\RubikCubeSolved\RubikRotation{x2,y}}
+%\end{verbatim}
+% ---this uses the rotations \rrx, \rrx, to invert, and then \rry\ to turn
+% the cube 90~$\deg$:
%
-% Since the the default height and width of the 3D-cube is 4cm (see above),
-% it follows that the width of the \cmd{\minipage} required for a cube in a
-% \texttt{tikzpicture} environment can be easily calculated. For example,
-% if the \texttt{tikzpicture} scale factor used is $0.5$, then the minimum
-% width of the required minipage for the \cmd{\DrawRubikCubeLD} view (shown above)
-% is therefore $0.5 \times 4\mbox{cm} = 2\mbox{cm}$.
+% \bigskip
+%
+% \begin{minipage}{2.6cm}
+% \centering
+% \begin{tikzpicture}[scale=0.5]
+% \DrawNCubeAll{3}{O}{Y}{G}
+% \end{tikzpicture}%
+% \end{minipage}
+% \hspace{5mm}
+% \begin{minipage}{0.6\textwidth}
+%\begin{verbatim}
+% \CubeUpSideDown
+% \ShowCube{2cm}{0.5}\DrawRubikCubeRU}
+%\end{verbatim}
+% \end{minipage}
+%
+% \bigskip
+%
+%% \DescribeMacro{\RubikCubeSolvedWB}
+% \textbf{Other configurations:} While the `solved' WY colour configuration
+% described above (White face opposite Yellow)
+% is that of the most commonly occurring Rubik cube, another `solved' colour configuration
+% which is also commercially available has the White opposite Blue configuration, which
+% is available using the command \verb!\RubikCubeSolvedWB!.
+% Its colour configuration is as follows:
+%
+%\begin{center}
+% \RubikCubeSolvedWB
+% \ShowCube{4cm}{0.4}{\DrawRubikCubeSF}%
+%\end{center}
+%
+% \bigskip
+%
+% Note that users can easily create their own alternative `solved'
+% face/colour versions.
+% For~example, the above mentioned white opposite
+% blue~(WB) solved configuration command \verb!\RubikCubeSolvedWB!
+% (white opposite blue, red opposite orange,
+% and green opposite yellow), was created using \verb!\SolvedConfig{R}{O}{W}{B}{G}{Y}!
+% (for the code see \ref{sec:codesolvedconfig}).
+%
+%
+% \subsection{RubikCubeGrey command}
+% \label{sec:rubikcubegrey}
+%
+% \DescribeMacro{\RubikCubeGrey}
+% \DescribeMacro{\RubikCubeGreyAll}
+% The command \cmd{\RubikCubeGrey} generates a 3x3x3 cube with no colours allocated
+% \textit{except} for the central cubie of each face, which takes the same colour
+% configuration as defined for the \cmd{\RubikCubeSolved} command.
+% The command \cmd{\RubikCubeGreyAll} generates a cube with \textit{all} the faces
+% completely grey.
+% Both these commands will accept either `grey' or `gray' (to be consistent with TikZ).
+%
+% These two commands, are designed to be useful starting points when wanting to
+% describe the movement of particular cubies. We can see the effect of
+% the \cmd{\RubikCubeGrey} command by viewing the cube in a semi-flat (SF) format,
+% as follows:
+%
+% \bigskip
+%
+% \RubikCubeGrey
+% \ShowCube{4.5cm}{0.45}{\DrawRubikCubeSF}
+% \hspace{3mm}
+% \begin{minipage}{0.6\textwidth}
+%\begin{verbatim}
+% \RubikCubeGrey
+% \ShowCube{4.5cm}{0.45}{\DrawRubikCubeSF}
+%\end{verbatim}
+% \end{minipage}
+%
+% \bigskip
+% Users can easily set their own alternative face/colour configuration either by `renewing'
+% the \cmd{\RubikCubeGrey} command along the lines shown above (the code is
+% in Section~\ref{sec:codegrey}), or simply creating a new `variant' command
+% altogether.
+%
+%
+%
+% \subsection{RubikSlice commands}
+% \label{sec:slicecommands}
+%
+% \DescribeMacro{\RubikSliceTopX}
+% \DescribeMacro{\RubikSliceMiddleX}
+% \DescribeMacro{\RubikSliceBottomX}
+% These three commands allocate the six visible cubie colours associated with a
+% \textit{horizontal} slice of a Rubik cube.
+% There are three pairs of Slice commands; one pair
+% (Left view \& Right view) for each of the horizontal slices Top, Middle, Bottom.
+% The six colour arguments associated with a given slice run in sequence
+% from left to right irrespective of the viewpoint, e.g.,~\#1 \#2 \#3 \#4 \#5 \#6.
%
-% The default width of the semi-flat cube representation is 10cm ($=3+3+1+3$),
-% and that of the flat cube is 12cm ($=3+3+3+3$). If in doubt check the extent of
-% any horizontal white-space using an fbox, or the \cmd{\ShowCubeF} command.
+% Since the viewpoint of the Rubik cube (from the Right or from the Left)
+% influences which face the colours are associated with, it is necessary
+% to have the view (R or L) specified in the command name.
%
+% The format of the `slice' command is shown in the following example.
+% The Rubik cube is shown from the LeftDown (LD) view
+% and consequently each of the `slice' commands in this
+% particular example ends in L, consistent with
+% the final \cmd{\DrawRubikCubeLD} command.
+%
+% Note that the two legacy `Equator' versions (now replaced by `Middle')
+% are retained to allow backward compatibility.
+%
+% \bigskip
+%
+% \begin{minipage}{2.8cm}
+% \centering
+% \RubikFaceDownAll{Y}
+% \RubikSliceTopL {G}{G}{G} {R}{R}{R}
+% \RubikSliceMiddleL {R}{R}{R} {B}{B}{B}
+% \RubikSliceBottomL {O}{O}{O} {G}{G}{G}
+% \begin{tikzpicture}[scale=0.7]
+% \DrawRubikCubeLD
+% \end{tikzpicture}%
+% \end{minipage}
+% \hspace{5mm}
+% \begin{minipage}{0.6\textwidth}
+%\begin{verbatim}
+% \RubikFaceDownAll{Y}
+% \RubikSliceTopL {G}{G}{G} {R}{R}{R}
+% \RubikSliceMiddleL {R}{R}{R} {B}{B}{B}
+% \RubikSliceBottomL {O}{O}{O} {G}{G}{G}
+% \ShowCube{3cm}{0.7}{\DrawRubikCubeLD}
+%\end{verbatim}
+% \end{minipage}
+%
+%
+%
+% \subsection{RubikSide commands}
+% \label{sec:rubikside}
+%
+% \DescribeMacro{\RubikSideLeft}
+% \DescribeMacro{\RubikSideRight}
+% \DescribeMacro{\RubikSideFront}
+% \DescribeMacro{\RubikSideBack}
+% These RubikSide commands allocate colours to the side facelets of
+% the UP~face, and each takes three ordered colour arguments, running from
+% top-left to top-right when looking directly at the side faces---see Section~\ref{sec:rubiksidecode}.
+% These facelets are the top three facelets of each side Front, Back, Left, Right.
+%
+% {\noindent}\textsc{usage}: \verb!\RubikSideBack{B}{G}{G}!
+%
+% \medskip
+%
+% \DescribeMacro{\RubikSideLeftAll}
+% \DescribeMacro{\RubikSideRightAll}
+% \DescribeMacro{\RubikSideFrontAll}
+% \DescribeMacro{\RubikSideBackAll}
+% These commands allocate the same colour to all three side cubies, and hence
+% take only a single colour argument.
+%
+% {\noindent}\textsc{usage}: \verb!\RubikSideBackAll{R}!
+%
+% \medskip
+%
+% The \cmd{\RubikSide..} and \cmd{\RubikFace..} commands are useful for setting up the colours
+% for just part of the cube. For~example, the following commands set-up the UP-face and sides,
+% and then draws the face and sidebars using \verb!\DrawFlatUpSide!.
+%
+% \bigskip
+%
+% \begin{minipage}{4cm}
+% \centering
+%\RubikFaceUp {R}{Y}{R}%
+% {Y}{Y}{Y}%
+% {G}{Y}{B}%
+%\RubikSideBack{B}{G}{G}%
+%\RubikSideFront{Y}{R}{Y}%
+%\RubikSideRight{O}{B}{Y}%
+%\RubikSideLeft{Y}{O}{O}%
+%\ShowCube{2cm}{0.5}{\DrawFlatUpSide}
+% \end{minipage}
+% \hspace{1cm}
+% \begin{minipage}{0.6\textwidth}
+%\begin{verbatim}
+%%set up the UP face
+%\RubikFaceUp {R}{Y}{R}%
+% {Y}{Y}{Y}%
+% {G}{Y}{B}%
+%\RubikSideBack{B}{G}{G}%
+%\RubikSideFront{Y}{R}{Y}%
+%\RubikSideRight{O}{B}{Y}%
+%\RubikSideLeft{Y}{O}{O}%
+%%draw the UP face and sides
+%\ShowCube{2cm}{0.5}{\DrawFlatUpSide}
+%\end{verbatim}
+% \end{minipage}
+%
+% \bigskip
+%
+% Note that we could instead have drawn the above image using \cmd{\DrawRubikLayer..}
+% commands. However, using the \cmd{\RubikSide..} and \cmd{\RubikFace..} commands
+% makes for a much more flexible and dynamic system, since the colours allocated using
+% these commands (provided they are external to an environment) will be global,
+% and hence will follow subsequent \cmd{\RubikRotation} commands.
+%
+%
+%
+% \pagebreak
%
%
% \section{Rotation commands}
% \label{sec:RubikCommands}
%
-% We use the standard Rubik cube notation of WCA~(2012)---see article~12---and
-% also the `s' (Slice) and `a' (anti-Slice) notation described in the
-% `Notation and terminology' section
-% in the `Pretty patterns' page on the website of
-% Fridrich (see References).
-%
-% It is recommended that commas are used to separate sequential
-% Rubik moves or commands to avoid ambiguity, especially when using just
-% lettercodes on their own.
-% For example, in the following sequence the commas remove any ambiguity:
-% \rr{U},\rr{Lw}2,\rr{Usp},\rr{Da} \ \ (|\rr{U},\rr{Lw}2,\rr{Usp},\rr{Da}|).
+% The Rubik bundle implements not only the standard Rubik cube notation of the
+% World Cube Association (see WCA website), but also the main variant notations
+% used by the Rubik interest groups and websites.
+%
+% \begin{figure}[hbt]
+% \centering
+% \ifpdf
+% \includegraphics[height=5cm]{rubik-doc-figA.pdf}
+% \fi
+% \caption{\label{fig:notation}Face rotations}
+% \end{figure}
+%
+% To avoid confusion the Rubik bundle uses a trailing `p' (lower-case) in rotation-codes to denote
+% a `prime' (reversed direction); we also recommend that commas are used to separate
+% sequential Rubik rotations (moves).
+% While these are mainly to avoid ambiguity, they also greatly facilitate computer
+% searching and copy-and-pasting of rotation sequences.
+%
+% Unfortunately, obtaining a good balance between an intuitive notation for defining
+% rotations and the need for flexibility is difficult,
+% and consequently some notation is more intuitive than others. A good compromise
+% seems to be the World Cube Association's FADN structure; i.e.,~Face (L,R,U,D,F,B),
+% Action (m,w,s,a,c), Direction (p),
+% N (n); for example, codes like \texttt{R, R2, Rc, Rm, Rwp, Rwp2} etc.
+%
+%
+% The \rubikcube\ package includes commands for typesetting a wide range of
+% rotation-codes (e.g.,~\rr{R}, \rr{y}, \rr{Bw}) and
+% equivalent hieroglyphs (e.g.,~\rrh{R}, \rrh{y}, \rrh{Bw}), as well as commands
+% for typesetting 3x3x3 cubes and single cubies. All the rotation-codes and
+% hieroglyphs are typeset using one particular font \& size which we call the `rubikfont'
+% for convenience (see Section~\ref{sec:rubikfont} for details).
+% All of the rotation-codes described
+% here are recognised by the \textsc{rubikrotation} package
+% (see Section~\ref{sec:rubikrotation}).
+%
+% Note that there are some rotation codes which are not represented by arrow
+% hieroglyphs, since their rotation is not visible from the \textsc{front} face,
+% and hence cannot easily be rendered as an arrow hieroglyph. Consequently these
+% rotations have a simple `letter' hieroglyph
+% in the form of the rotation-code in a square; for~example, \rrhBw, \rrhFm.
%
-%
+%
+% \pagebreak
%
% \subsection{Overview}
% \label{sec:overview}
%
-% The \rubikcube\ notation comprises a range of
-% commands for moves or rotations (e.g.,~\rr{R}, \rr{y}, \rr{Bw}) and their equivalent hieroglyphs
-% (e.g.,~\rrh{R}, \rrh{y}, \rrh{Bw}), as well as commands for drawing 3x3x3 cubes and single cubies.
-%
-% Note that there are a few rotation commands which do not have arrow
-% hieroglyphs---their their rotation is not visible from the \textsc{front} face
-% and hence cannot easily be rendered as an arrow hieroglyph. Consequently these
-% rotations have a simple `letter' hieroglyph
-% in the form of the rotation-code in a square; for example \rrhBw, \rrhSb.
+% We now describe the four commands used for typesetting the various rotation-codes.
%
% \DescribeMacro{\rr}
-% The rotation-code of a rotation is typeset (as in text) using the rubik-rotation
-% \cmd{\rr\marg{rotation-code}} command: i.e.,~\rr{R}\ is typeset using the command \cmd{\rr\{R\}}.
-% The hieroglyph of a rotation command is generated (in text) by
-% \DescribeMacro{\rrh}
-% using instead the command \cmd{\rrh\marg{rotation-code}}. Thus the command \cmd{\rrh\{R\}} generates
-% \rrh{R}\ which is the hieroglyph associated with \rr{R}.
+% The text version of a rotation-code is typeset using the rubik-rotation
+% command \cmd{\rr\marg{rotation-code}}, i.e.,~\rr{R}\ is typeset using the command \cmd{\rr\{R\}}.
+% The hieroglyph of a rotation is generated (in text) by \DescribeMacro{\rrh}
+% using instead the command \cmd{\rrh\marg{rotation-code}}. For~example, the command
+% \cmd{\rrh\{R\}} generates \rrh{R}\ which is the hieroglyph associated with
+% the rotation \rr{R}.
%
% \DescribeMacro{\Rubik}
% A vertically combined rotation-code and its hieroglyph is generated using the command
-% \cmd{\Rubik\marg{rotation-code}}. For example, \Rubik{R}\ is generated by the command \cmd{\Rubik\{R\}},
+% \cmd{\Rubik\marg{rotation-code}}. For~example, \Rubik{R}\ is generated by the command \cmd{\Rubik\{R\}},
% with the square hieroglyph sitting on the baseline.
-% For some hieroglyphs (e.g.,~\rrh{x}, \rrh{y}, \rrh{z}\ denoting 90~degree axis rotations)
-% the only difference between the \cmd{\rrh\{\}} and \cmd{\Rubik\{\}} forms is that
+% For some hieroglyphs (e.g.,~\rrh{x}, \rrh{y}, \rrh{z}\ denoting 90~degree cube-axis rotations)
+% the only difference between the \cmd{\rrh\{\}} and \cmd{\Rubik\{\}} form is that
% the \cmd{\Rubik\{\}} form is elevated to sit on the baseline just like the other
% \cmd{\Rubik\{\}} hieroglyphs.
-% For example \cmd{\rrh\{yp\}} generates \rrh{yp}, while
+% For~example, \cmd{\rrh\{yp\}} generates \rrh{yp}, while
% \cmd{\Rubik\{yp\}} generates \Rubik{yp}.
%
% \DescribeMacro{\textRubik}
% A horizontally combined rotation-code and its hieroglyph (in sequence as in text)
-% is generated using the command stem \cmd{\textRubik\marg{rotation-code}}.
-% For example, \textRubik{R}\ is typeset using the command \cmd{\textRubik\{R\}}.
-% A list of all commands and their associated hieroglyphs is given in
+% is generated using the command \cmd{\textRubik\marg{rotation-code}}.
+% For~example, \textRubik{R}\ is typeset using the command \cmd{\textRubik\{R\}}.
+% A list of all rotation-code commands and their associated hieroglyphs is given in
% Section~\ref{sec:listofcommands}.
%
-% \pagebreak
+%
%
% \subsection{Face rotations}
%
@@ -688,10 +1270,10 @@
% \DescribeMacro{B}
% The six main faces of the cube are denoted as \textsc{front} (towards the observer),
% \textsc{back}, \textsc{left}, \textsc{right}, \textsc{up}, \textsc{down}.
-% The uppercase initial letter of each face-name (\rr{F}, \rr{B}, \rr{L}, \rr{R}, \rr{U}, \rr{D})
+% The upper-case initial letter of each face-name (\rr{F}, \rr{B}, \rr{L}, \rr{R}, \rr{U}, \rr{D})
% denotes a clockwise 90-degree rotation of the face as shown in
% Figure~\ref{fig:notation}.
-% For example, \rr{D}\ is generated by the `rubik rotation' command \cmd{\rr\{D\}}.
+% For~example, \rr{D}\ is generated by the `rubik rotation' command \cmd{\rr\{D\}}.
%
% \DescribeMacro{Up}
% \DescribeMacro{Dp}
@@ -701,57 +1283,69 @@
% \DescribeMacro{Bp}
% An appended prime~$^\prime$ indicates an anticlockwise rotation; e.g.,~\rr{Fp}.
% This is sometimes written as \rr{F}$\boldmath{^{-1}}$. The `prime' notation is
-% achieved by appending a lowercase `p' to the face rotation command. For example, \rr{Rp}\
-% is generated by \cmd{\rr\{Rp\}}.
+% achieved by appending a lower-case `p' to the face rotation command. For~example, \rr{Rp}\
+% is generated by \cmd{\rr\{Rp\}}. More formally, \rr{Rp} is the `inverse' of \rr{R}.
%
-% \vspace{-0.2cm}
-% \begin{figure}[hbt]
-% \centering
-% \ifpdf
-% \includegraphics[height=5cm]{Rubik-doc-figA.pdf}
-% \fi
-% \caption{\label{fig:notation}}
-% \end{figure}
+% The superscript~$^2$, or sometimes just an ordinary~2, indicates that the rotation
+% is applied twice. For~example, \rr{R}\textbf{$^2$} or \rr{R}\textbf{2}
+% denote \textit{two} successive 90~degree clockwise rotations of the \textsc{right} face;
+% \rr{R}\textbf{$^3$} is equivalent to \rr{Rp} etc.
%
%
-% \subsection{Slice rotations}
+% \subsection{Inner-slice rotations}
% \label{sec:slicerotations}
%
-% \DescribeMacro{Su}
-% \DescribeMacro{Sd}
-% \DescribeMacro{Sl}
-% \DescribeMacro{Sr}
-% \DescribeMacro{Sf}
-% \DescribeMacro{Sb}
-% The Rubik cube (3x3x3) has three orthogonal so-called `inner' slices, whose +ve
-% rotation direction follows that of a named face. For example the inner slice
+% The Rubik cube (3x3x3) has three orthogonal so-called
+% `inner' slices (middle layers, middle slices), whose +ve
+% rotation direction follows that of a named face. For~example, the inner-slice
% rotation between the \textsc{right} and \textsc{left} faces whose rotation
-% direction follows the rotation \rr{R}\ (rotation is isomorphic to \rr{R}) is denoted
-% as \rr{Sr}, which is typeset using the command \cmd{\rr\{Sr\}}. Note that in these cases
-% the trailing \texttt{r} in the command is lowercase.
-%
-% \bigskip\bigskip\bigskip
-%
-% \DescribeMacro{Sup}
-% \DescribeMacro{Sdp}
-% \DescribeMacro{Slp}
-% \DescribeMacro{Srp}
-% \DescribeMacro{Sfp}
-% \DescribeMacro{Sbp}
-% Each of these slice rotations (S rotations) has a reversed (primed) p-form,
-% the command for which is generated by appending the suffix `p'.
-% For example the inner slice rotations \rr{Slp}\ (\cmd{\rr\{Slp\}}) and
-% \rr{Sr}\ (\cmd{\rr\{Sr\}}) are identical.
-% The equivalence is more obvious when we see their respective hieroglyphs.
-% For example, in this case \linebreak \rr{Slp}\ (\cmd{\rr\{Slp\}})
-% $\equiv$ \rrh{Slp}\ (\cmd{\rrh\{Slp\}}),
-% and \rr{Sr}\ (\cmd{\rr\{Sr\}}) $\equiv$ \rrh{Sr}\ (\cmd{\rrh\{Sr\}}).
-%
-% \bigskip
-%
-% \pagebreak
-%
-% \subsubsection*{MES slice notation}
+% direction follows the rotation \rr{R}\ (i.e.,~its rotation is isomorphic to \rr{R}).
+% The inner-slice rotations form a group (the Slice group), originally
+% described by John Conway (Frey and Singmaster, 1982, p~105).
+%
+%
+% \subsubsection*{The `m' notation}
+% \label{sec:mnotation}
+%
+% \DescribeMacro{Um}
+% \DescribeMacro{Dm}
+% \DescribeMacro{Lm}
+% \DescribeMacro{Rm}
+% \DescribeMacro{Fm}
+% \DescribeMacro{Bm}
+% Here `m' stands for the `middle' slice, namely that parallel to the designated
+% \textsc{face}; its rotation mirrors that of the
+% \textsc{face}. The \texttt{m} must be in lower-case.
+% Each of these rotation-codes has a complementary `prime' version, formed
+% by appending a `p'; for~example, \rr{Rm} (\verb!\rr{Rm}!) is a middle layer rotation
+% \rrh{Rm} between the \textsc{right} and \textsc{left} faces, and is in the same
+% direction as \rr{R}. The code \rr{Rmp} (\verb!\rr{Rmp}!) refers to the same
+% middle slice, but rotated in the opposite direction \rrh{Rmp}.
+%
+% This notation, which was probably invented by Singmaster, was originally used on the
+% Cube Lovers usenet group (1981--1997). It is now much used on the
+% Jaap Puzzles website (see Scherphius J) ---see also Section~\ref{sec:codeJaap}.
+%
+%
+% \subsubsection*{The `M' notation}
+% \label{sec:Mnotation}
+%
+% \DescribeMacro{MU}
+% \DescribeMacro{MD}
+% \DescribeMacro{ML}
+% \DescribeMacro{MR}
+% \DescribeMacro{MF}
+% \DescribeMacro{MB}
+% This variant of the above `middle' slice notation (e.g.,~\texttt{MR} $\equiv$ \texttt{Rm})
+% is part of the `superset' notation of Randelshofer. As before, the rotation
+% direction follows that of the designated \textsc{face}.
+% Each has a complementary `prime' version
+% formed by appending a `p'. The \texttt{M} must be in upper-case.
+%
+%
+% \bigskip\bigskip
+%
+% \subsubsection*{The MES notation}
%
% \DescribeMacro{M}
% \DescribeMacro{E}
@@ -759,8 +1353,8 @@
% \DescribeMacro{Mp}
% \DescribeMacro{Ep}
% \DescribeMacro{Sp}
-% An alternative and somewhat confusing (and hence is non-standard) slice notation
-% which is sometimes used is the following
+% An alternative but very confusing
+% inner-slice notation (e.g.,~\texttt{Ep} $\equiv$ \texttt{Um}) which is occasionally used is the
% so-called MES notation, as used in the Waterman algorithm
% (Treep and Waterman 1987).
% \begin{itemize}
@@ -771,16 +1365,28 @@
% \item[\rr{S}] \ (\textsc{standing} \rrh{S}, between the \textsc{front} and
% \textsc{back} faces; direction follows \rr{F}).
% \end{itemize}
-% Each of these also has a reversed (prime) version, and a hieroglyph
-% (see Section~\ref{sec:listofcommands}).
-% The equivalent S notation (see above) is therefore
-% as follows: \rr{E}\ $\equiv$ \rr{Sd}, \rr{Ep}\ $\equiv$ \rr{Su},
-% \rr{M}\ $\equiv$ \rr{Sl}, \rr{Mp}\ $\equiv$ \rr{Sr}, \rr{S}\ $\equiv$ \rr{Sf},
-% \rr{Sp}\ $\equiv$ \rr{Sb}.
+% Each of these also has an inverse (prime) version.
+%
+%
+% \subsubsection*{The `S' notation}
+%
+% \DescribeMacro{Su}
+% \DescribeMacro{Sd}
+% \DescribeMacro{Sl}
+% \DescribeMacro{Sr}
+% \DescribeMacro{Sf}
+% \DescribeMacro{Sb}
+% In this equally confusing inner-slice notation, `S' stands for `inner-slice';
+% the face letter must be in lower-case (e.g.,~\texttt{Sr} $\equiv$ \texttt{Rm}). For~example, the inner-slice
+% rotation between the \textsc{right} and \textsc{left} faces whose rotation
+% direction follows the rotation \rr{R}\ is denoted
+% as \rr{Sr}, which is typeset using the command \cmd{\rr\{Sr\}}.
+% Each has an inverse (prime) p-form.
%
-%
%
-% \subsubsection*{Singmaster slice notation}
+% \subsection{Outer-slice rotations}
+%
+% \subsubsection*{Slice notation}
%
% \DescribeMacro{Us}
% \DescribeMacro{Ds}
@@ -788,20 +1394,38 @@
% \DescribeMacro{Rs}
% \DescribeMacro{Fs}
% \DescribeMacro{Bs}
-% These are an alternative (but somewhat less intuitive) form of
-% slice notation which can be thought of as complementing the
-% inner slice rotations. These were originally described by
-% Singmaster (Frey and Singmaster, 1982).
-% See the link to `notation' on the `Pretty patterns' page of the
-% Fridrich website.
+% This is a `paired' form of
+% notation (two rotations at once), which can be thought of as complementing the
+% inner-slice (middle layer) rotations.
+% Each of these `slice' commands denotes a rotation of two opposite faces
+% in the \textit{same} direction.
+% {\linebreak}For~example, \textRubik{Us}\ $\equiv$ \textRubik{U}\ + \textRubik{Dp};
+% i.e.,~both face-rotations are in the \textit{same} direction
+% as \rr{U}. Each of these rotation-codes has a complementary `anti-slice' version (see below).
%
-% Each of these commands denotes a rotation of two opposite faces
-% in the same direction. For example, \textRubik{Us}\ $\equiv$ \textRubik{U}\ + \textRubik{Dp},
-% which is typeset as:
-% \newline |\textRubik{Us}\ $\equiv$ \textRubik{U}\ + \textRubik{Dp}|,
-% i.e.,~for \rr{Us}\ both face-rotations are in the \textit{same} direction
-% as \rr{U}.
+% This notation was originally described by
+% Singmaster (Frey and Singmaster, 1982), and is much used
+% on the `Pretty patterns' page of the Fridrich website (this
+% page also has a useful link to `notation').
+%
+%
+% \bigskip
%
+% \DescribeMacro{SU}
+% \DescribeMacro{SD}
+% \DescribeMacro{SL}
+% \DescribeMacro{SR}
+% \DescribeMacro{SF}
+% \DescribeMacro{SB}
+% This variant of the above `slice' notation (e.g.,~\texttt{SU} $\equiv$ \texttt{Us})
+% is part of the `superset' notation of Randelshofer. As before, the rotation
+% direction follows that of the designated
+% \textsc{face}. Each has a complementary `prime' version formed by appending a `p'.
+%
+%
+% \bigskip\bigskip
+%
+
%
% \subsubsection*{Anti-slice notation}
%
@@ -813,11 +1437,9 @@
% \DescribeMacro{Ba}
% Each of these commands denotes a rotation of two opposite faces
% in \textit{opposite} directions.
-% For example, \textRubik{Ua}\ $\equiv$ \textRubik{U}\ + \textRubik{D},
-% which is typeset as:
-% \newline |\textRubik{Ua}\ $\equiv$ \textRubik{U}\ + \textRubik{D}|.
-% See the link to `notation' on the `Pretty patterns' page of the
-% Fridrich website.
+% For~example, \textRubik{Ua}\ $\equiv$ \textRubik{U}\ + \textRubik{D}.
+% This notation is much used on the `Pretty patterns' page of the
+% Fridrich website (see the note above re: `slice notation').
%
% \bigskip\bigskip
%
@@ -829,19 +1451,32 @@
% \DescribeMacro{Rw}
% \DescribeMacro{Fw}
% \DescribeMacro{Bw}
-% The clockwise \textit{combined} rotation of an outer face AND its inner slice
-% (officially known as a `double outer slice' rotation) is denoted by appending a
-% lowercase \textbf{\textsf{\footnotesize{w}}} (denoting `wide') to a face rotation command.
-% For example, a \textsc{right} double outer slice rotation is denoted as \rr{Rw}.
-% Similarly, the prime $^\prime$ version \rr{Lwp}\ is generated by \cmd{\rr\{Lwp\}}.
+% The clockwise \textit{combined} rotation of an outer face AND its inner-slice
+% (officially known as a `double outer slice' rotation, or a `double block' move)
+% is denoted by appending a lower-case \textbf{\textsf{\footnotesize{w}}}
+% (denoting `wide') to a rotation-code (endorsed by the WCA).
+% For~example, a \textsc{right} double outer slice rotation \rrh{Rw} (\verb!\rrh{Rw}!)
+% is denoted as \rr{Rw} (\verb!\rr{Rw}!). The `prime' version is formed by
+% appending a `p' to the rotation-code. For~example, \rr{Rwp}\ is generated by \verb!\rr{Rwp}!.
%
-% The superscript~$^2$, or sometimes just an ordinary 2, indicates that the rotation
-% is applied twice. For example \rr{R}\textbf{$^2$} or \rr{R}\textbf{2}
-% denote \textit{two} successive 90~degree clockwise rotations of the \textsc{right} face.
-% Clearly \rr{R}\textbf{$^3$} is equivalent to \rr{Rp} etc.
%
+% \bigskip
%
+% \subsubsection*{The `T' notation}
+% \label{sec:Tnotation}
%
+% \DescribeMacro{TU}
+% \DescribeMacro{TD}
+% \DescribeMacro{TL}
+% \DescribeMacro{TR}
+% \DescribeMacro{TF}
+% \DescribeMacro{TB}
+% This confusing variant of the above `w' notation (e.g.,~\texttt{TR} $\equiv$ \texttt{Rw}) is part of
+% the `superset' notation of Randelshofer. As before, the rotation direction
+% follows that of the designated \textsc{face}. Each has a complementary `prime' version
+% formed by appending a `p'.
+%
+% \bigskip\bigskip
%
% \subsection{Axis rotations}
%
@@ -854,17 +1489,17 @@
% with their hieroglyphs (the \cmd{\rrh\{\}} forms) being denoted
% as \rrh{x}, \rrh{y}, \rrh{z}\ in order to distinguish them from square layer-rotation
% hieroglyphs.
-% Note that since \rr{x}, \rr{y}, \rr{z}\ rotations are always expressed in lowercase,
-% this practice is extended also to the commands.
+% Note that since \rr{x}, \rr{y}, \rr{z}\ rotations are always expressed in lower-case;
+% this practice is also extended to the commands.
%
-% An \rr{x}\textbf{2} rotation (two \rr{x}\ rotations one after
+% For example, an \rr{x}\textbf{2} rotation (two \rr{x}\ rotations one after
% the other, i.e.,~\rrh{x}\ \rrh{x}) denotes rotating
% the cube 180~degrees about its x axis so as to bring the \textsc{down} face
% into the \textsc{up} position.
%
% An appended prime~$^\prime$ indicates an anticlockwise rotation;
-% for example, \rr{xp}\ (which is generated by appending a `p' to the end of
-% the command, i.e.,~\cmd{\rr\{xp\}}).
+% for~example, \rr{xp}\ (which is generated by appending a `p' to the
+% rotation-code, i.e.,~\cmd{\rr\{xp\}}).
%
% The \cmd{\Rubik\{\}} forms (and their prime `p' versions) generate the same
% hieroglyphs as their \cmd{\rrh\{\}} versions, except that their spacing is
@@ -886,7 +1521,7 @@
% \DescribeMacro{b}
% A commonly used alternative for the \rr{x}, \rr{y}, \rr{z}\ notation
% (and endorsed by the WCA) uses these
-% lowercase face letter to denote a 90~degree whole-cube rotation in the same
+% lower-case face letter to denote a 90~degree whole-cube rotation in the same
% directional sense as that of the standard face rotations.
%
% {\noindent}Thus
@@ -894,24 +1529,62 @@
% \rr{l}\ $\equiv$ \rr{xp}, \ \rr{r}\ $\equiv$ \rr{x}, \
% \rr{f}\ $\equiv$ \rr{z}, \ \rr{b}\ $\equiv$ \rr{zp},
%
-% {\noindent}For example, \rr{d}\ is generated by the command \cmd{\rr\{d\}}.
+% {\noindent}For~example, \rr{d}\ is generated by the command \cmd{\rr\{d\}}.
%
% {\noindent}Note that these rotations do not have prime $^\prime$ versions
% since \rr{u}~is the opposite of \rr{d}, \rr{l}~is the opposite of \rr{r}, and
% \rr{f}~is the opposite of \rr{b}.
%
-% As with the \rrh{x}, \rrh{y}, \rrh{z}\ forms (described above) there also
-% equivalent \cmd{\rrh\{\}} and \cmd{\Rubik\{\}} forms. For example,
+% As with the \rrh{x}, \rrh{y}, \rrh{z}\ forms (described above) there are also
+% equivalent \cmd{\rrh\{\}} and \cmd{\Rubik\{\}} forms. For~example,
% \rrh{d}\ is generated by the command \cmd{\rrh\{d\}}.
%
%
+% \subsubsection*{The `c' notation}
+% \label{sec:cnotation}
+%
+% \DescribeMacro{Uc}
+% \DescribeMacro{Dc}
+% \DescribeMacro{Lc}
+% \DescribeMacro{Rc}
+% \DescribeMacro{Fc}
+% \DescribeMacro{Bc}
+% This slightly more intuitive notation (the `c' stands for `cube') also associates the rotation
+% direction with that of the designated \textsc{face} (e.g.,~\texttt{Rc} $\equiv$ \texttt{x}).
+% Each has a complementary `prime' version formed by appending a `p'.
+% For~example, \rr{Rc} (\verb!\rr{Rc}!) is equivalent to \rr{x};
+% \rr{Rcp} (\verb!\rr{Rcp}!) is equivalent to \rr{xp}.
+%
+% This notation, which was probably invented by Singmaster, was originally used on the
+% Cube Lovers usenet group (1981--1997). It is now much used on the
+% Jaap Puzzles website (see Scherphius J) ---see also Section~\ref{sec:codeJaap}.
+%
+% \bigskip\bigskip
+%
+% \subsubsection*{The `C' notation}
+% \label{sec:Cnotation}
+%
+% \DescribeMacro{CU}
+% \DescribeMacro{CD}
+% \DescribeMacro{CL}
+% \DescribeMacro{CR}
+% \DescribeMacro{CF}
+% \DescribeMacro{CB}
+% This variant of the whole cube rotation notation
+% (e.g.,~\texttt{CR} $\equiv$ \texttt{Rc} $\equiv$ \texttt{x})
+% is part of the `superset' notation of Randelshofer. As before, the rotation
+% direction follows that of the designated \textsc{face}. Each has a complementary
+% `prime' version formed by appending a `p'.
+%
+%
+% \bigskip% \bigskip
%
% \subsection{Examples}
% \label{sec:examples}
%
-% {\noindent}\rr{R}\ is generated by the `rubik rotation' command \cmd{\rr\{R\}}
+% {\noindent}\rr{R}\ is generated by the command \cmd{\rr\{R\}}
%
-% {\noindent}\rr{Fw}\ is generated by the `rubik rotation' command \cmd{\rr\{Fw\}}
+% {\noindent}\rr{Fw}\ is generated by the command \cmd{\rr\{Fw\}}
%
% {\noindent}\rr{L}$^2$ is generated by \cmd{\rr\{L\}}\verb!$^2$!
%
@@ -924,7 +1597,7 @@
% {\noindent}\rr{x}\ and \rrh{y}\ and \Rubik{zp}\ are generated by
% \cmd{\rr\{x\}} and \cmd{\rrh\{y\}} and \cmd{\Rubik\{zp\}}
%
-% {\noindent}\rr{f}\ and \rrh{b}\ are generated by \cmd{\rr\{f\}} and \cmd{\rrh\{b\}}
+% {\noindent}\rr{Fc}\ and \rrh{Bc}\ are generated by \cmd{\rr\{Fc\}} and \cmd{\rrh\{Bc\}}
%
% {\noindent}\rr{U}\rr{U}\rr{R}\rr{R}\ is generated by
% \cmd{\rr\{U\}}\cmd{\rr\{U\}}\cmd{\rr\{R\}}\cmd{\rr\{R\}}
@@ -941,7 +1614,7 @@
%
% \bigskip
%
-% {\noindent}Commas can be important in avoiding ambiguity; for example
+% {\noindent}Commas can be important in avoiding ambiguity; for~example,
%
% \bigskip
%
@@ -956,35 +1629,48 @@
% {\noindent}\rrh{F}\rrh{U}\rrh{y}\rrh{Rp}\rrh{Lwp} \ \ \ \
% \verb!\rrh{F}\rrh{U}\rrh{y}\rrh{Rp}\rrh{Lwp}!
%
+% \bigskip
+%
+% Note that if each rotation element uses the \textit{same} font or encoding, then
+% typesetting a rotation sequence can be achieved more easily using the
+% \verb!\ShowSequence! command (see Section~\ref{sec:showsequence}). For example, we can
+% typeset the last sequence much more conveniently, as follows:
+%
+% \medskip
+%
+% \verb!\ShowSequence{}{\rrh}{F,U,y,Rp,Lwp}! \ \ $\rightarrow$ \ \ \ShowSequence{}{\rrh}{F,U,y,Rp,Lwp}
%
%
-% \bigskip
%
% \subsection{Backwards compatibility}
% \label{sec:backwardscompat}
%
% Note that in keeping with `backwards compatibility' all rotation commands (see below)
-% can still be written without the usual curley braces \verb!{}!.
-% For example, the hieroglyph \rrhD\ (\cmd{\rrh\{D\}}) can also be generated using the command
+% can still be written without the usual curly braces \verb!{}!.
+% For~example, the hieroglyph \rrhD\ (\cmd{\rrh\{D\}}) can also be generated using the command
% \cmd{\rrhD}.
%
% \bigskip
%
+% \pagebreak
+%
% \subsection{Listing of all rotation commands}
% \label{sec:listofcommands}
%
%
% Note that all the commands presented here also have a \cmd{\Rubik\{\}} equivalent form which
% typesets both the hieroglyph and its lettercode in a vertical format,
-% as shown in the `Examples' section above. These have been ommitted here
+% as shown in the `Examples' section above. These have been omitted here
% owing to the difficulty of including this form easily in the following table.
%
-% Note also that some \cmd{\rrh\{\}} commands (eg~the \cmd{\rrh\{B\}} command)
+%
+% Note also that some \cmd{\rrh\{\}} commands (e.g.,~the \cmd{\rrh\{B\}} command)
% show only the lettercode in a square box, e.g.,~\rrh{B}. This is because these rotations
% do not have a `true' visual representation as seen from the \textsc{front} face,
% and hence can be somewhat ambiguous unless typeset with their associated
% lettercode.
%
+%
% \newcommand{\dnstrut}{\rule{0pt}{17pt}}
% \newcommand{\dns}{\hspace{2mm}}
% \newcommand{\dnsp}{\hspace{2mm}}
@@ -1016,6 +1702,18 @@
% \dnstrut\rr{Uap}\dns\cmd{\rr\{Uap\}}
% & \rrh{Uap}\dns\cmd{\rrh\{Uap\}}
% & \textRubik{Uap}\dns\cmd{\textRubik\{Uap\}} \nonumber\\
+% \dnstrut\rr{Um}\dns\cmd{\rr\{Um\}}
+% & \rrh{Um}\dns\cmd{\rrh\{Um\}}
+% & \textRubik{Um}\dns\cmd{\textRubik\{Um\}} \nonumber\\
+% \dnstrut\rr{Ump}\dns\cmd{\rr\{Ump\}}
+% & \rrh{Ump}\dns\cmd{\rrh\{Ump\}}
+% & \textRubik{Ump}\dns\cmd{\textRubik\{Ump\}} \nonumber\\
+% \dnstrut\rr{Uc}\dns\cmd{\rr\{Uc\}}
+% & \rrh{Uc}\dns\cmd{\rrh\{Uc\}}
+% & \Rubik{Uc}\dns\cmd{\Rubik\{Uc\}} \nonumber\\
+% \dnstrut\rr{Ucp}\dns\cmd{\rr\{Ucp\}}
+% & \rrh{Ucp}\dns\cmd{\rrh\{Ucp\}}
+% & \Rubik{Ucp}\dns\cmd{\Rubik\{Ucp\}} \nonumber\\
% \end{supertabular}
%
%
@@ -1044,6 +1742,18 @@
% \dnstrut\rr{Dap}\dns\cmd{\rr\{Dap\}}
% & \rrh{Dap}\dns\cmd{\rrh\{Dap\}}
% & \textRubik{Dap}\dns\cmd{\textRubik\{Dap\}} \nonumber\\
+% \dnstrut\rr{Dm}\dns\cmd{\rr\{Dm\}}
+% & \rrh{Dm}\dns\cmd{\rrh\{Dm\}}
+% & \textRubik{Dm}\dns\cmd{\textRubik\{Dm\}} \nonumber\\
+% \dnstrut\rr{Dmp}\dns\cmd{\rr\{Dmp\}}
+% & \rrh{Dmp}\dns\cmd{\rrh\{Dmp\}}
+% & \textRubik{Dmp}\dns\cmd{\textRubik\{Dmp\}} \nonumber\\
+% \dnstrut\rr{Dc}\dns\cmd{\rr\{Dc\}}
+% & \rrh{Dc}\dns\cmd{\rrh\{Dc\}}
+% & \Rubik{Dc}\dns\cmd{\Rubik\{Dc\}} \nonumber\\
+% \dnstrut\rr{Dcp}\dns\cmd{\rr\{Dcp\}}
+% & \rrh{Dcp}\dns\cmd{\rrh\{Dcp\}}
+% & \Rubik{Dcp}\dns\cmd{\Rubik\{Dcp\}} \nonumber\\
% \end{supertabular}
%
%
@@ -1072,9 +1782,20 @@
% \dnstrut\rr{Lap}\dns\cmd{\rr\{Lap\}}
% & \rrh{Lap}\dns\cmd{\rrh\{Lap\}}
% & \textRubik{Lap}\dns\cmd{\textRubik\{Lap\}} \nonumber\\
+% \dnstrut\rr{Lm}\dns\cmd{\rr\{Lm\}}
+% & \rrh{Lm}\dns\cmd{\rrh\{Lm\}}
+% & \textRubik{Lm}\dns\cmd{\textRubik\{Lm\}} \nonumber\\
+% \dnstrut\rr{Lmp}\dns\cmd{\rr\{Lmp\}}
+% & \rrh{Lmp}\dns\cmd{\rrh\{Lmp\}}
+% & \textRubik{Lmp}\dns\cmd{\textRubik\{Lmp\}} \nonumber\\
+% \dnstrut\rr{Lc}\dns\cmd{\rr\{Lc\}}
+% & \rrh{Lc}\dns\cmd{\rrh\{Lc\}}
+% & \Rubik{Lc}\dns\cmd{\Rubik\{Lc\}} \nonumber\\
+% \dnstrut\rr{Lcp}\dns\cmd{\rr\{Lcp\}}
+% & \rrh{Lcp}\dns\cmd{\rrh\{Lcp\}}
+% & \Rubik{Lcp}\dns\cmd{\Rubik\{Lcp\}} \nonumber\\
% \end{supertabular}
%
-%
% \begin{supertabular}[lll]{p{3cm} p{3cm} p{4.5cm}}
% \dnstrut\rr{R}\dns\cmd{\rr\{R\}}
% & \rrh{R}\dns\cmd{\rrh\{R\}}
@@ -1100,6 +1821,18 @@
% \dnstrut\rr{Rap}\dns\cmd{\rr\{Rap\}}
% & \rrh{Rap}\dns\cmd{\rrh\{Rap\}}
% & \textRubik{Rap}\dns\cmd{\textRubik\{Rap\}} \nonumber\\
+% \dnstrut\rr{Rm}\dns\cmd{\rr\{Rm\}}
+% & \rrh{Rm}\dns\cmd{\rrh\{Rm\}}
+% & \textRubik{Rm}\dns\cmd{\textRubik\{Rm\}} \nonumber\\
+% \dnstrut\rr{Rmp}\dns\cmd{\rr\{Rmp\}}
+% & \rrh{Rmp}\dns\cmd{\rrh\{Rmp\}}
+% & \textRubik{Rmp}\dns\cmd{\textRubik\{Rmp\}} \nonumber\\
+% \dnstrut\rr{Rc}\dns\cmd{\rr\{Rc\}}
+% & \rrh{Rc}\dns\cmd{\rrh\{Rc\}}
+% & \Rubik{Rc}\dns\cmd{\Rubik\{Rc\}} \nonumber\\
+% \dnstrut\rr{Rcp}\dns\cmd{\rr\{Rcp\}}
+% & \rrh{Rcp}\dns\cmd{\rrh\{Rcp\}}
+% & \Rubik{Rcp}\dns\cmd{\Rubik\{Rcp\}} \nonumber\\
% \end{supertabular}
%
%
@@ -1128,6 +1861,18 @@
% \dnstrut\rr{Fap}\dns\cmd{\rr\{Fap\}}
% & \rrh{Fap}\dns\cmd{\rrh\{Fap\}}
% & \textRubik{Fap}\dns\cmd{\textRubik\{Fap\}} \nonumber\\
+% \dnstrut\rr{Fm}\dns\cmd{\rr\{Fm\}}
+% & \rrh{Fm}\dns\cmd{\rrh\{Fm\}}
+% & \textRubik{Fm}\dns\cmd{\textRubik\{Fm\}} \nonumber\\
+% \dnstrut\rr{Fmp}\dns\cmd{\rr\{Fmp\}}
+% & \rrh{Fmp}\dns\cmd{\rrh\{Fmp\}}
+% & \textRubik{Fmp}\dns\cmd{\textRubik\{Fmp\}} \nonumber\\
+% \dnstrut\rr{Fc}\dns\cmd{\rr\{Fc\}}
+% & \rrh{Fc}\dns\cmd{\rrh\{Fc\}}
+% & \Rubik{Fc}\dns\cmd{\Rubik\{Fc\}} \nonumber\\
+% \dnstrut\rr{Fcp}\dns\cmd{\rr\{Fcp\}}
+% & \rrh{Fcp}\dns\cmd{\rrh\{Fcp\}}
+% & \Rubik{Fcp}\dns\cmd{\Rubik\{Fcp\}} \nonumber\\
% \end{supertabular}
%
%
@@ -1156,6 +1901,18 @@
% \dnstrut\rr{Bap}\dns\cmd{\rr\{Bap\}}
% & \rrh{Bap}\dns\cmd{\rrh\{Bap\}}
% & \textRubik{Bap}\dns\cmd{\textRubik\{Bap\}} \nonumber\\
+% \dnstrut\rr{Bm}\dns\cmd{\rr\{Bm\}}
+% & \rrh{Bm}\dns\cmd{\rrh\{Bm\}}
+% & \textRubik{Bm}\dns\cmd{\textRubik\{Bm\}} \nonumber\\
+% \dnstrut\rr{Bmp}\dns\cmd{\rr\{Bmp\}}
+% & \rrh{Bmp}\dns\cmd{\rrh\{Bmp\}}
+% & \textRubik{Bmp}\dns\cmd{\textRubik\{Bmp\}} \nonumber\\
+% \dnstrut\rr{Bc}\dns\cmd{\rr\{Bc\}}
+% & \rrh{Bc}\dns\cmd{\rrh\{Bc\}}
+% & \Rubik{Bc}\dns\cmd{\Rubik\{Bc\}} \nonumber\\
+% \dnstrut\rr{Bcp}\dns\cmd{\rr\{Bcp\}}
+% & \rrh{Bcp}\dns\cmd{\rrh\{Bcp\}}
+% & \Rubik{Bcp}\dns\cmd{\Rubik\{Bcp\}} \nonumber\\
% \end{supertabular}
%
%
@@ -1265,43 +2022,171 @@
% \end{supertabular}
%
%
-% \pagebreak
+% \subsubsection{Randelshofer notation}
+% \label{sec:listofRandelshofercommands}
%
-% \section{Other commands}
+% \newcommand{\dnRubik}[1]{%
+% \dnstrut\rr{#1}\dns\cmd{\rr\{#1\}}%
+% & \rrh{#1}\dns\cmd{\rrh\{#1\}}%
+% & \Rubik{#1}\dns\cmd{\Rubik\{#1\}} \nonumber\\%
+% }%
%
+% \newcommand{\dntextRubik}[1]{%
+% \dnstrut\rr{#1}\dns\cmd{\rr\{#1\}}%
+% & \rrh{#1}\dns\cmd{\rrh\{#1\}}%
+% & \textRubik{#1}\dns\cmd{\textRubik\{#1\}} \nonumber\\%
+% }%
%
-% \DescribeMacro{\rubikcube}
-% This command generates the logo \rubikcube.
%
+% \begin{supertabular}[lll]{p{3cm} p{3cm} p{4.5cm}}
+% \dnRubik{CR}
+% \dnRubik{CRp}
+% \dnRubik{CL}
+% \dnRubik{CLp}
+% \dnRubik{CU}
+% \dnRubik{CUp}
+% \dnRubik{CD}
+% \dnRubik{CDp}
+% \dnRubik{CF}
+% \dnRubik{CFp}
+% \dnRubik{CB}
+% \dnRubik{CBp}
+% \end{supertabular}
%
-% All \rubikcube\ commands assume a 3x3x3 cube by default.
-% There are three primary command categories: (a)~\cmd{\Draw..} commands
-% (which must always be used \textit{inside} a TikZ picture environment),
-% (b)~parameter-allocation' commands---e.g.,~\cmd{\RubikCubeSolved}---which can
-% be used either inside or outside a TikZ environment),
-% and (c)~commands which can be used in ordinary text
-% (e.g.,~|\rr{}| rotation commands).
+% \begin{supertabular}[lll]{p{3cm} p{3cm} p{4.5cm}}
+% \dntextRubik{MR}
+% \dntextRubik{MRp}
+% \dntextRubik{ML}
+% \dntextRubik{MLp}
+% \dntextRubik{MU}
+% \dntextRubik{MUp}
+% \dntextRubik{MD}
+% \dntextRubik{MDp}
+% \dntextRubik{MF}
+% \dntextRubik{MFp}
+% \dntextRubik{MB}
+% \dntextRubik{MBp}
+% \end{supertabular}
%
-% Since \LaTeX\ commands have a maximum limit of only 9 parameters,
-% it is necessary to use separate `Face' and `Slice' commands (see below)
-% in order to accommodate all 27 visible colours of a 3D~Rubik cube.
+% \begin{supertabular}[lll]{p{3cm} p{3cm} p{4.5cm}}
+% \dntextRubik{SR}
+% \dntextRubik{SRp}
+% \dntextRubik{SL}
+% \dntextRubik{SLp}
+% \dntextRubik{SU}
+% \dntextRubik{SUp}
+% \dntextRubik{SD}
+% \dntextRubik{SDp}
+% \dntextRubik{SF}
+% \dntextRubik{SFp}
+% \dntextRubik{SB}
+% \dntextRubik{SBp}
+% \end{supertabular}
+%
+% \begin{supertabular}[lll]{p{3cm} p{3cm} p{4.5cm}}
+% \dntextRubik{TR}
+% \dntextRubik{TRp}
+% \dntextRubik{TL}
+% \dntextRubik{TLp}
+% \dntextRubik{TU}
+% \dntextRubik{TUp}
+% \dntextRubik{TD}
+% \dntextRubik{TDp}
+% \dntextRubik{TF}
+% \dntextRubik{TFp}
+% \dntextRubik{TB}
+% \dntextRubik{TBp}
+% \end{supertabular}
%
%
+% \subsection{The rubikfont}
+% \label{sec:rubikfont}
+%
+% For hieroglyph-related text we use the standard Computer Modern Sans (cmss)
+% bold extended (bx) 10pt font for upper-case letters, and the 8pt footnote size for lower-case
+% (see Section~\ref{sec:coderubikfont} for details). This font (rubikfont)
+% and the `prime' symbol (rubikprime) can be easily changed by `renewing' the three commands there.
+%
+% For example, to change to the somewhat `lighter' semi-bold extended (sbx) CM Sans (cmss) form
+% one can simply include the following in the preamble (the FNS suffix stands for `footnotesize'):
+%\begin{verbatim}
+% \makeatletter
+% \renewcommand{\@rubikfont}{\fontsize{10}{12pt}\usefont{T1}{cmss}{sbx}{n}}
+% \renewcommand{\@rubikfontFNS}{\fontsize{8}{12pt}\usefont{T1}{cmss}{sbx}{n}}
+% \makeatother
+%\end{verbatim}
+%
+%
+% \subsubsection*{The `rubikprime' symbol}
+% \label{sec:rubikprime}
+%
+% We currently use the apostrophe for the prime symbol (see Section~\ref{sec:coderubikfont}),
+% since the maths \cmd{\prime} seems to be a bit too faint (especially since we need to use
+% the `scriptstyle' size in this setting). However, users can
+% easily make the Rubik bundle use the maths prime instead, by loading the following
+% in the preamble.
+%\begin{verbatim}
+% \makeatletter
+% \renewcommand{\@rubikprime}{\raisebox{1.2pt}{\ensuremath{\scriptstyle{^\prime}}}}
+% \makeatother
+%\end{verbatim}
+%
+%
+%
+% \section{Draw commands}
+%
+% A \cmd{\Draw..} command typesets either a Rubik cube, cubie or a face
+% or layer using parameters set or defined via
+% previous parameter-allocation commands (e.g.,~face colours, dimensions etc).
+% Note that those \cmd{\Draw..} commands which do take colours as arguments do not
+% update the cube's internal `colour state', but simply `paint' these colours.
+%
+% It is important to distinguish between the \rubikcube\ package \cmd{\Draw..} commands
+% and TikZ \cmd{\draw..} commands. \cmd{\Draw..} commands are implemented by the
+% TikZ \cmd{\draw..} commands, and consequently \cmd{\Draw..} commands can only be
+% used \textit{inside} a TikZ picture environment---and hence they can also be used safely in
+% conjunction with the \cmd{\ShowCube} command, which itself uses a TikZ picture environment.
+% See also Section~\ref{sec:drawerrormessage} below..
+%
+%
+%
+% \subsection[Error message]{\cmd{\Draw} error message}
+% \label{sec:drawerrormessage}
+%
+% If a \cmd{\Draw..} command is used \textit{outside} a
+% TikZ picture environment, then \LaTeX\ issues an
+% ``Undefined control sequence'' error message, indicating
+% that it is trying to draw something using an undefined
+% TikZ \cmd{\draw} command\,\footnote{Note that the TikZ \cmd{\draw} command
+% uses a lower-case `d', while all \rubikcube\ commands start with an upper-case letter.}.
+%
+% This is because all Rubik \cmd{\Draw..} commands achieve their effects by
+% implementing a series of TikZ \cmd{\draw..} and other commands, all of which
+% need to be inside a \texttt{tikzpicture} environment.
+%
+% For~example, if the command \cmd{\DrawRubikCubeF} is used
+% without a surrounding TikZ picture environment,
+% then something similar to the following error message will be generated.
+%\begin{verbatim}
+%! Undefined control sequence.
+%\DrawFlatUp ... }{#1}\pgfmathsetmacro {\uy }{#2}\draw
+% [line join=round,...
+%l.56 \DrawRubikCubeF
+%\end{verbatim}
+%
%
-% \subsection{Draw commands}
%
-% A \cmd{\Draw..} command typesets
-% either a Rubik cube, cubie or a layer using parameters set or defined via
-% previous parameter-allocation commands (eg~face colours, dimensions etc).
-% Furthermore, \cmd{\Draw..} commands can only be used \textit{inside} a TikZ
-% picture environment (see section~\ref{sec:drawerrormessage}).
%
+% \subsection{DrawRubikCube commands}
%
% \DescribeMacro{\DrawRubikCubeXY}
-% This command draws Rubik cubes in one of four
-% orientations as denoted by the following terminal XY viewing-direction
-% codes: RU (RightUp), RD (RightDown), LU (LeftUp), LD (LeftDown).
-% For example, the command
+% \DescribeMacro{\DrawRubikCubeF}
+% \DescribeMacro{\DrawRubikCubeSF}
+% This command draws Rubik cubes in one of four oblique
+% orientations or configurations as denoted by the following terminal
+% XY viewing-direction codes: RU~(RightUp), RD~(RightDown), LU~(LeftUp),
+% LD~(LeftDown); two additional terminal codes are F~(Flat) and SF~(Semi-Flat).
+% For~example, the command
% \begin{quote}
% \cmd{\DrawRubikCubeRU}
% \end{quote}
@@ -1323,7 +2208,7 @@
% \DrawRubikCubeRU
% \end{tikzpicture}%
%\end{verbatim}
-% Note that these commands are equivalent to:
+% Note that the above commands are equivalent to:
%\begin{verbatim}
% \RubikCubeSolved
% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU}
@@ -1347,42 +2232,32 @@
% the xyz parameters denote the face colours associated with each of
% the three axes.
%
-% For example, the command \cmd{\DrawCubieRU\{O\}\{Y\}\{G\}} draws a
+% For~example, the command \cmd{\DrawCubieRU\{O\}\{Y\}\{G\}} draws a
% single cubie as viewed from the RightUp direction,
% with face colours Orange (x-axis), Yellow (y-axis), Green (z-axis), as follows.
%
% \medskip
%
-% \begin{minipage}{1.35cm}
-% \begin{tikzpicture}[scale=1]
-% \DrawCubieRU{O}{Y}{G}
-% \end{tikzpicture}%
-% \end{minipage}
+% \ShowCube{1.33cm}{1}{\DrawCubieRU{O}{Y}{G}}
% \hspace{1cm}
% \begin{minipage}{0.6\textwidth}
%\begin{verbatim}
-% \begin{tikzpicture}[scale=1]
-% \DrawCubieRU{O}{Y}{G}
-% \end{tikzpicture}%
+% \ShowCube{1.33cm}{1}{\DrawCubieRU{O}{Y}{G}}
%\end{verbatim}
% \end{minipage}
%
% \medskip
%
-% {\noindent}Since the front face is a unit 1cm and the width of the side approx 1/3cm,
-% and the scale factor =1, then the the minimum minipage width required for the cubie
-% $=(1.33 \times 1) = 1.33$cm, and hence the above commands are equivalent to
-% \begin{verbatim}
-% \ShowCube{1.33cm}{1}{\DrawCubieRU{O}{Y}{G}}
-% \end{verbatim}
-%
+% {\noindent}Since the front face is 1~unit wide and the 2D width of the side approx 1/3~unit,
+% and the scale-factor =~1, then the minipage width required for the cubie image
+% $=(1.33 \times 1) = 1.33$cm.
%
% \begin{figure}[hbt]
% \centering
% \ifpdf
-% \includegraphics[height=4cm]{Rubik-doc-figC.pdf}
+% \includegraphics[height=4cm]{rubik-doc-figC.pdf}
% \else
-% \includegraphics[height=4cm]{Rubik-doc-figC.eps}
+% \includegraphics[height=4cm]{rubik-doc-figC.eps}
% \fi
% \vspace{-5mm}\caption{\label{fig:cubiedydx}Cubie dy dx parameters}
% \end{figure}
@@ -1396,25 +2271,23 @@
% \cmd{\Cubiedy\{\}} \\
% \cmd{\Cubiedx\{\}}
% \end{quote}
-% as shown in the folowing example.
+% as shown in the following example.
%
% \bigskip
%
-% \begin{minipage}{1.7cm}
-% \begin{tikzpicture}[scale=1]
-% \Cubiedy{0.4}
-% \Cubiedx{0.8}
-% \DrawCubieRU{O}{Y}{G}
-% \end{tikzpicture}%
-% \end{minipage}
+% \ShowCube{1.7cm}{1}{%
+% \Cubiedy{0.4}%
+% \Cubiedx{0.8}%
+% \DrawCubieRU{O}{Y}{G}%
+% }
% \hspace{2cm}
% \begin{minipage}{0.6\textwidth}
%\begin{verbatim}
-% \begin{tikzpicture}[scale=1]
+% \ShowCube{1.7cm}{1}{%
% \Cubiedy{0.4}
% \Cubiedx{0.8}
% \DrawCubieRU{O}{Y}{G}
-% \end{tikzpicture}%
+% }
%\end{verbatim}
% \end{minipage}
%
@@ -1449,288 +2322,267 @@
% \textCubieLD{O}{Y}{G} \ \ |\textCubieLD{O}{Y}{G}|
% \end{quote}
% Note that these \cmd{\textCubieXY} commands are not influenced by the
-% \cmd{\Cubiedy}, \cmd{\Cubiedx} commands as their size is preset for text use.
-%
-%
-% \subsubsection[Draw.. error message]{\cmd{\draw} error message}
-%
-% See also section~\ref{sec:drawerrormessage} regarding the error message associated with
-% using a \cmd{\Draw...} command \textit{outside} a TikZ picture environment.
-%
+% \cmd{\Cubiedy}, \cmd{\Cubiedx} commands as their size is pre-set for text use.
%
-% \subsection{Face commands}
-% \label{sec:facecommands}
-%
-% \DescribeMacro{\RubikFaceUp}
-% \DescribeMacro{\RubikFaceDown}
-% \DescribeMacro{\RubikFaceLeft}
-% \DescribeMacro{\RubikFaceRight}
-% \DescribeMacro{\RubikFaceFront}
-% \DescribeMacro{\RubikFaceBack}
-% These commands take nine colour arguments and allocate colours to the
-% individual cubies of a Rubik cube face.
-% The ordering is isomorphic to the sequence 1--9, i.e.,~numbering the small
-% squares 1-3~(top row, left to right), 4-6~(middle row, left to right),
-% 7-9~(bottom row, left to right), as follows:
-% \begin{quote}
-% \fbox{
-% \begin{minipage}{1.6cm}
-% \#1 \#2 \#3
%
-% \#4 \#5 \#6
-%
-% \#7 \#8 \#9
-% \end{minipage}
-% }
-% \end{quote}
-% Conveniently, \LaTeX\ allows the colour arguments to be separated by spaces
-% (e.g.,~separated in groups of three), or even spread across several
-% lines (e.g.,~in a square block to resemble a 9-face) in order to
-% make the command more visually intuitive, as in the following examples.
-% \begin{quote}
-%\begin{verbatim}
-% \RubikFaceUp{G}{B}{G} {G}{W}{O} {G}{O}{G}
-%
-% \RubikFaceFront{O}{W}{R}
-% {W}{W}{W}
-% {G}{W}{G}
%
-%\end{verbatim}
-% \end{quote}
-%
-% \DescribeMacro{\RubikFaceUpAll}
-% \DescribeMacro{\RubikFaceDownAll}
-% \DescribeMacro{\RubikFaceLeftAll}
-% \DescribeMacro{\RubikFaceRightAll}
-% \DescribeMacro{\RubikFaceFrontAll}
-% \DescribeMacro{\RubikFaceBackAll}
-% For convenience, each of these commands has an associated
-% `\texttt{All}' command which allocates the same colour to all the cubies
-% on a 9-face (i.e.,~only a single colour argument is required).
-%
-% If you want a particular face to be all grey, then one can
-% either omit the particular `Face' command (since the
-% default colour is grey), or use a `Face' command specifying the
-% colour-code~X; for example, \cmd{\RubikFaceUpAll\{X\}}.
-% However, if you do use a Face command, then all of the command's
-% colour arguments must be allocated, as otherwise you will generate a
-% `missing parameter' error, and no colour will be
-% allocated (i.e.,~you will see a black-hole).
-% Use of these commands is shown in the following figure.
+% \subsection{Flat commands}
+% \label{sec:flatcommands}
%
-% \bigskip
-%
-% \begin{minipage}{2.8cm}
-% \RubikFaceUpAll{X}
-% \RubikFaceRightAll{R}
-% \RubikFaceFront{W}{Y}{G}
-% {W}{Y}{G}
-% {W}{Y}{G}
-% \begin{tikzpicture}[scale=0.7]
-% \DrawRubikCubeRU
-% \end{tikzpicture}%
-% \end{minipage}
-% \hspace{5mm}
-% \begin{minipage}{0.6\textwidth}
-%\begin{verbatim}
-% \RubikFaceUpAll{X}
-% \RubikFaceRightAll{R}
-% \RubikFaceFront{W}{Y}{G}
-% {W}{Y}{G}
-% {W}{Y}{G}
-% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU}
-% \end{verbatim}
-% \end{minipage}
-%
+% \DescribeMacro{\DrawFlatUp}
+% \DescribeMacro{\DrawFlatDown}
+% \DescribeMacro{\DrawFlatLeft}
+% \DescribeMacro{\DrawFlatRight}
+% \DescribeMacro{\DrawFlatFront}
+% \DescribeMacro{\DrawFlatBack}
+% These commands \cmd{\DrawFlat..}\marg{x}\marg{y} draw a `flat' (square)
+% representation of the current state of a specified face such that its
+% bottom left corner is positioned at ($x$, $y$).
+% They are designed to supplement the \cmd{\DrawRubikCube...} commands and
+% allow hidden faces to be represented.
+% Each command (except \cmd{\DrawFlatFront}) takes two arguments,
+% namely the X-coordinate and Y-coordinate of the bottom left
+% corner of the face. This ($x$,$y$) pair allows the user to position
+% the face.
%
-% \subsection{RubikCubeSolved command}
-% \label{sec:rubikcubesolved}
+% Note that the Y-argument set for the \cmd{\DrawFlatLeft}
+% and \cmd{\DrawFlatRight} commands is not currently actioned
+% (see Section~\ref{sec:drawflatxcommands}).
+% This is because both the \textsc{left} and \textsc{right} faces, as used by the
+% \cmd{\DrawRubikCubeSF} (Semi-Flat) command which incorporates the RU
+% view, require only Y=0. It is anticipated that this (x,y) facility
+% will be fully extended to the left and right forms in a later version.
+%
+% Note also that the \cmd{\DrawFlatFront} command currently takes \textit{no}
+% arguments, since by definition the bottom left corner of this face is
+% always at (0,0), and there seems to be no reason (just now) for
+% this face to have the (x,y) facility.
+%
+% \textsc{usage}:\ In the following example we use the command \verb!\DrawFlatBack{4}{1}! to
+% append the \textsc{back} face to the side of a 3D cube. Note that since
+% the coordinates of the bottom/back/right corner of the cube rendered by the
+% command \cmd{\DrawRubikCubeRU} is (4,1)
+% (see Section~\ref{sec:coordinates}), we can position the
+% lower/left corner of the \textsc{back} face at this point using the command
+% \verb!\DrawFlatBack{4}{1}! as follows:
%
-% \DescribeMacro{\RubikCubeSolved}
-% This command sets all the face colours to that of a standard `solved' cube
-% and is equivalent to the following set of face commands
+% \bigskip
+%
+% \begin{minipage}{0.4\textwidth}
+% \centering
+% \RubikCubeSolved
+% \begin{tikzpicture}[scale=0.4]
+% \DrawRubikCubeRU
+% \DrawFlatBack{4}{1}
+% \end{tikzpicture}%
+% \end{minipage}
+% \begin{minipage}{5cm}
%\begin{verbatim}
-% \RubikFaceUpAll{W}%
-% \RubikFaceDownAll{Y}%
-% \RubikFaceLeftAll{B}%
-% \RubikFaceRightAll{G}%
-% \RubikFaceFrontAll{O}%
-% \RubikFaceBackAll{R}%
+% \RubikCubeSolved
+% \ShowCube{3cm}{0.4}{%
+% \DrawRubikCubeRU
+% \DrawFlatBack{4}{1}
+% }
%\end{verbatim}
-% as shown in the following semi-flat image.
-%
-% \bigskip
+% \end{minipage}
+%
+% \bigskip
%
-% \begin{minipage}{5cm}
-% \centering
-% \begin{tikzpicture}[scale=0.5]
-% \RubikCubeSolved
-% \DrawRubikCubeFlat
-% \end{tikzpicture}%
-% \end{minipage}
-% \begin{minipage}{0.5\textwidth}
+% \DescribeMacro{\DrawRubikCubeF}
+% This command draws the completely flat (F) format of the cube, as shown in the following example.
+%
+% \bigskip
+%
+% \begin{minipage}{0.4\textwidth}
+% \centering
+% \begin{tikzpicture}[scale=0.4]
+% \RubikCubeSolved
+% \DrawRubikCubeF
+% \node (U) at (1.5, 4.5) [black]{\small\textsf{U}};
+% \node (D) at (1.5, -1.5) [black]{\small\textsf{D}};
+% \node (L) at (-1.5, 1.5) [black]{\small\textsf{L}};
+% \node (R) at (4.5, 1.5) [black]{\small\textsf{R}};
+% \node (F) at (1.5, 1.5) [black]{\small\textsf{F}};
+% \node (B) at (7.5, 1.5) [black]{\small\textsf{B}};
+% \end{tikzpicture}%
+% \end{minipage}
+% \begin{minipage}{5cm}
%\begin{verbatim}
% \RubikCubeSolved
-% \showcube{5cm}{0.5}{\DrawRubikCubeFlat}
+% \ShowCube{5cm}{0.4}{\DrawRubikCubeF}
%\end{verbatim}
-% \end{minipage}
-%
-% \bigskip
-%
-% Note that the width of the minipage above is set to 5cm. This is derived from the fact
-% that the unscaled width of the semi-flat image is 10cm, and hence if
-% the TikZ scale factor is to be 0.5 then the minimum minipage width = $10 \times 0.5 = 5$cm
-% (see Section~\ref{sec:coordinates} for details).
-%
-% If other orientations of the solved cube are required, this can be easily achieved
-% using the \cmd{\RubikRotation} command (from the \texttt{RubikRotation} package).
-% For example, if one wants to show the solved cube upsidedown, then this format
-% could be defined as follows (here we have used the rotations \rrx, \rrx, \rry, to
-% invert the cube):
+% \end{minipage}
+%
+% \bigskip
+%
+% The addition of text (numbers or letters) in the faces is
+% straightforward---the origin of the 1-unit grid is located at the
+% bottom left corner of the \textsc{front} face (orange here).
+% The letters were placed using the following TikZ code inside the
+% TikZ picture environment.
+%
%\begin{verbatim}
-%\newcommand{\CubeUpSideDown}{\RubikCubeSolved\RubikRotation{x2,y}}
+% \RubikCubeSolved
+% \ShowCube{5cm}{0.4}{%
+% \DrawRubikCubeF
+% \node (U) at (1.5, 4.5) [black]{\small\textsf{U}};
+% \node (D) at (1.5, -1.5) [black]{\small\textsf{D}};
+% \node (L) at (-1.5, 1.5) [black]{\small\textsf{L}};
+% \node (R) at (4.5, 1.5) [black]{\small\textsf{R}};
+% \node (F) at (1.5, 1.5) [black]{\small\textsf{F}};
+% \node (B) at (7.5, 1.5) [black]{\small\textsf{B}};
+% }
%\end{verbatim}
-% This command would then generate the following:
-%
-% \bigskip
+%
+% \DescribeMacro{\DrawRubikCubeSF}
+% {\noindent}A useful `semi-flat' (SF) alternative format, which uses
+% the standard RU view of the cube and appends the three hidden
+% sides (cf.,~Rokicki \textit{et~al.}, 2013), is generated by the
+% command \cmd{\DrawRubikCubeSF} as follows.
+%
+% \bigskip
%
-% \begin{minipage}{2.8cm}
-% \centering
-% \begin{tikzpicture}[scale=0.6]
-% \DrawNCubeAll{3}{O}{Y}{G}
-% \end{tikzpicture}%
-% \end{minipage}
-% \hspace{5mm}
-% \begin{minipage}{0.6\textwidth}
+% \begin{minipage}{5cm}
+% \begin{tikzpicture}[scale=0.5]
+% \RubikCubeSolved
+% \DrawRubikCubeSF
+% \node (B) at (5.5, 2.5) [white]{\small\textsf{B}};
+% \end{tikzpicture}%
+% \end{minipage}
+% \begin{minipage}{5cm}
%\begin{verbatim}
-% \CubeUpSideDown
-% \ShowCube{2.4cm}{0.6}\DrawRubikCubeRU}
+% \RubikCubeSolved
+% \ShowCube{5cm}{0.5}{%
+% \DrawRubikCubeSF
+% \node (B) at (5.5, 2.5)
+% [white]{\small\textsf{B}};
+% }
%\end{verbatim}
-% \end{minipage}
-%
+% \end{minipage}
+%
% \bigskip
%
-% Users can easily set their own alternative `solved' face/colour configuration by `renewing'
-% the \cmd{\RubikCubeSolved} command as follows---remember to include the trailing \% (note also
-% that the colours ROYGBWX are currently hardwired so do not use a different set
-% of uppercase letters).
-%\begin{verbatim}
-% \renewcommand{\RubikCubeSolved}{%
-% \RubikFaceUpAll{..}%
-% \RubikFaceDownAll{..}%
-% \RubikFaceLeftAll{..}%
-% \RubikFaceRightAll{..}%
-% \RubikFaceFrontAll{..}%
-% \RubikFaceBackAll{..}%
-% }
-%\end{verbatim}
-%
-%
-%
-% \subsection{RubikCubeGrey command}
-% \label{sec:rubikcubegrey}
+% Note that even in this configuration it is straight-forward to
+% write text on the graphic, since the 2D width (on the page) of
+% the green \textsc{right} face is exactly 1-unit, and the
+% bottom right-hand corner of the green face is raised exactly 1-unit
+% (see Figure~\ref{fig:cubesquaregraph}).
+% Consequently, since the origin of the coordinate-grid is at the bottom left
+% corner of the \textsc{front} face (the orange face here), the coordinates
+% of the centre of the red \textsc{back} face are easily determined to be (5.5, 2.5).
+%
%
-% \DescribeMacro{\RubikCubeGrey}
-% This command generates a 3x3x3 cube with no colours allocated except for the central
-% cubie of each face, which takes the same colour configuration as defined for the
-% \cmd{\RubikCubeSolved} command.
-% This command, which is useful starting point when wanting to describe the movement of
-% particular cubies, generates the following cube:
+% \subsection{Face commands}
+% \label{sec:facecommands}
+%
+%
+% \DescribeMacro{\DrawFaceUp}
+% \DescribeMacro{\DrawFaceDown}
+% \DescribeMacro{\DrawFaceLeft}
+% \DescribeMacro{\DrawFaceRight}
+% \DescribeMacro{\DrawFaceFront}
+% \DescribeMacro{\DrawFaceBack}
+% \DescribeMacro{\DrawFaceUpSide}
+% \DescribeMacro{\DrawFaceDownSide}
+% \DescribeMacro{\DrawFaceLeftSide}
+% \DescribeMacro{\DrawFaceRightSide}
+% \DescribeMacro{\DrawFaceFrontSide}
+% \DescribeMacro{\DrawFaceBackSide}
+% These commands draw the current state of a specified face
+% (e.g.,~\cmd{\DrawFaceUp}), or the face and all the associated side-bars
+% (e.g.,~\cmd{\DrawFaceUpSide}).
+% \textsc{Note}: these commands do \textsc{not} take any
+% arguments---for code see Section~\ref{sec:drawfacecode}.
%
-% \bigskip
+% In the following example we use the \cmd{\DrawFlatUpSide} command to
+% draw the \textsc{up} face and all its side-bars of a cube having
+% a `solved' configuration.
%
-% \RubikCubeGrey
-% \ShowCube{3cm}{0.5}{\DrawRubikCubeRU}
-% \hspace{5mm}
-% \begin{minipage}{0.6\textwidth}
+% \bigskip
+%
+% \begin{minipage}{0.4\textwidth}
+% \centering
+% \RubikCubeSolved
+% \begin{tikzpicture}[scale=0.4]
+% \DrawFaceUpSide
+% \end{tikzpicture}%
+% \end{minipage}
+% \begin{minipage}{5cm}
%\begin{verbatim}
-% \RubikCubeGrey
-% \ShowCube{3cm}{0.5}{\DrawRubikCubeRU}
+% \RubikCubeSolved
+% \ShowCube{1.6cm}{0.4}{%
+% \DrawFaceUpSide
+% }
%\end{verbatim}
-% \end{minipage}
-%
-% \bigskip
-% Users can easily set their own alternative face/colour configuration by `renewing'
-% the \cmd{\RubikCubeGrey} command along the lines shown above (the code is in Section~\ref{sec:codegrey}).
+% \end{minipage}
%
+% \vspace{1cm}
%
%
-% \subsection{Slice commands}
-% \label{sec:slicecommands}
-%
-% \DescribeMacro{\RubikSliceTopX}
-% \DescribeMacro{\RubikSliceMiddleX}
-% \DescribeMacro{\RubikSliceBottomX}
-% These three commands allocate the six visible cubie colours associated with a
-% \textit{horizontal} slice of a Rubik cube.
-% There are three pairs of Slice commands; one pair
-% (Left view \& Right view) for each of the horizontal slices Top, Middle, Bottom.
-% The six colour arguments associated with a given slice run in sequence
-% from left to right irrespective of the viewpoint, e.g.,~\#1 \#2 \#3 \#4 \#5 \#6.
-%
-% Since the viewpoint of the Rubik cube (from the Right or from the Left)
-% influences which face the colours are associated with, it is necessary
-% to have the view (R or L) specified in the command name.
+% \subsection[NCube]{NCube (NxNxN)}
+% \label{sec:NCube}
+%
+% \DescribeMacro{\DrawNCubeAll}
+% An `NCube' is a solved NxNxN cube drawn from the RU direction;
+% (i.e.,~only shows faces \textsc{up}, \textsc{front}, \textsc{right}).
+% The cubie colours of each face are All the same.
+% \begin{quote}
+% \cmd{\DrawNCubeAll\{N\}\{Xcolour\}\{Ycolour\}\{Zcolour\}}.
+% \end{quote}
+% This command takes four ordered parameters (N, X, Y, Z)---the number
+% (integer; $N>0$) of cubies along an edge, followed by three face
+% colours in XYZ order.
+% Since the viewpoint is only from the RU direction, the three colour
+% parameters are: X(Right), Y(Up), Z(Front).
+%
+% \bigskip
+%
+% \begin{minipage}{0.3\textwidth}
+% \begin{tikzpicture}[scale=0.5]
+% \DrawNCubeAll{5}{O}{Y}{G}
+% \end{tikzpicture}%
+% \end{minipage}
+% \begin{minipage}{0.5\textwidth}
+%\begin{verbatim}
+% \ShowCube{3.5cm}{0.5}{\DrawNCubeAll{5}{O}{Y}{G}}
+%\end{verbatim}
+% \end{minipage}
%
-% The format of the `slice' command is shown in the following example.
-% The Rubik cube is shown from the LeftDown (LD) view
-% and consequently each of the `slice' commands in this
-% particular example ends in L, consistent with
-% the final \cmd{\DrawRubikCubeLD} command.
%
-% Note that the two legacy `Equator' versions (now replaced by `Middle')
-% are retained to allow backward compatibility.
%
-% \bigskip
%
-% \begin{minipage}{2.8cm}
-% \centering
-% \RubikFaceDownAll{Y}
-% \RubikSliceTopL {G}{G}{G} {R}{R}{R}
-% \RubikSliceMiddleL {R}{R}{R} {B}{B}{B}
-% \RubikSliceBottomL {O}{O}{O} {G}{G}{G}
-% \begin{tikzpicture}[scale=0.7]
-% \DrawRubikCubeLD
-% \end{tikzpicture}%
-% \end{minipage}
-% \hspace{5mm}
-% \begin{minipage}{0.6\textwidth}
-%\begin{verbatim}
-% \RubikFaceDownAll{Y}
-% \RubikSliceTopL {G}{G}{G} {R}{R}{R}
-% \RubikSliceMiddleL {R}{R}{R} {B}{B}{B}
-% \RubikSliceBottomL {O}{O}{O} {G}{G}{G}
-% \ShowCube{3cm}{0.7}{\DrawRubikCubeLD}
-%\end{verbatim}
-% \end{minipage}
%
+% \subsection{LayerFace}
+% \label{sec:layerface}
%
-% \subsection{LayerFace \& LayerSide commands}
-% \label{sec:layerface}
+% While a cube has faces and layers, a layer has a face (the face you are looking
+% at or drawing) and four sides (consisting of the nine side facelets of the
+% associated cubies).
+% The two `Layer' commands described here are intended for drawing final layer
+% configurations from `scratch' without any prior configuration information.
%
-% These commands are intended for drawing final layer
-% configurations (i.e.,~typically using the yellow face in the \textsc{up} position)
-% with or without the associated side faces of the cubies of the top layer
-% (see also the \cmd{\DrawFlatUpSide} command in Section~\ref{sec:flatcommands})
+% Typically, we might wish to show the yellow face in
+% the \textsc{up} position, with or without the associated side faces of the
+% cubies of this layer.
+% Of course, if we already know the rotation history from some initial configuration,
+% it would be much simpler just to invoke the \cmd{\RubikRotation} command and then use the
+% \cmd{\DrawFlatUpSide} command (see Section~\ref{sec:flatcommands}).
%
-% \subsubsection{LayerFace}
%
% \DescribeMacro{\DrawRubikLayerFace}
-% This LayerFace command draws a simple Rubik cube 3x3 face and allocates colours
-% to the 9~cubies.
-% The command takes nine ordered colour arguments.
-% Their use is illustrated in the following example, which shows a yellow cross configuration.
+% \DescribeMacro{\DrawRubikLayerFaceAll}
+% These two LayerFace commands draw a simple 3x3 face and allocate colours
+% to the 9~facelets.
+% The \cmd{\DrawRubikLayerFace} command takes nine ordered colour arguments.
+% The command is illustrated in the following example, which shows a yellow cross configuration.
%
% \bigskip
%
-% \begin{minipage}{2.5cm}
-% \centering
-% \begin{tikzpicture}[scale=0.7]
-% \DrawRubikLayerFace{X}{Y}{X}
-% {Y}{Y}{Y}
-% {X}{Y}{X}
-% \end{tikzpicture}%
-% \end{minipage}
+% \ShowCube{2.1cm}{0.7}{%
+% \DrawRubikLayerFace{X}{Y}{X}
+% {Y}{Y}{Y}
+% {X}{Y}{X}
+% }%
% \hspace{1cm}
% \begin{minipage}{0.6\textwidth}
%\begin{verbatim}
@@ -1738,35 +2590,34 @@
% \DrawRubikLayerFace{X}{Y}{X}
% {Y}{Y}{Y}
% {X}{Y}{X}
-% }
+% }
%\end{verbatim}
% \end{minipage}
%
-% \medskip
-%
-% \subsubsection[Draw.. error message]{\cmd{\draw} error message}
+% \bigskip
%
-% See also section~\ref{sec:drawerrormessage} regarding the error message associated with
-% using a \cmd{\Draw...} command \textit{outside} a TikZ picture environment.
+% {\noindent}The \cmd{\DrawRubikLayerFaceAll} command takes a single colour argument, and paints
+% the whole face the same colour.
%
% \medskip
%
-% \subsubsection{LayerSide}
-% \label{sec:layerside}
+% \subsection{LayerSide (sidebars)}
+% \label{sec:layerside} \label{sec:sidebars}
%
% \DescribeMacro{\DrawRubikLayerSideXYp}
% LayerSide commands draw the associated side colours of
-% the top layer as small rectangular sidebars.
-% The LayerSide commands adopt a three-letter XYp \textbf{position} notation
+% the layer as small rectangular sidebars.
+% The LayerSide command adopts a three-letter XYp \textbf{position} notation
% where the XY pair define the location (X:[Left \verb!|! Middle \verb!|! Right];
-% Y:[Top \verb!|! Middle \verb!|! Bottom]) of a particular cubie in the layer face.
+% Y:[Top \verb!|! Middle \verb!|! Bottom]) of a particular cubie in the layer face,
+% as depicted in Figure~\ref{fig:facenotation}.
%
% \begin{figure}[hbt]
% \centering
% \ifpdf
-% \includegraphics[height=3cm]{Rubik-doc-figD.pdf}
+% \includegraphics[height=3cm]{rubik-doc-figD.pdf}
% \else
-% \includegraphics[height=3cm]{Rubik-doc-figD.eps}
+% \includegraphics[height=3cm]{rubik-doc-figD.eps}
% \fi
% \vspace{-5mm}\caption{\label{fig:facenotation}LayerSide rotation-codes }
% \end{figure}
@@ -1782,7 +2633,7 @@
% Various different LayerSide commands are available: those for
% drawing a single colour side bar, and others for facilitating
% drawing all 12 side bars.
-% For example, \textit{either} of the following commands
+% For~example, \textit{either} of the following commands
%
% \begin{quote}
%\begin{verbatim}
@@ -1805,9 +2656,9 @@
%\end{verbatim}
% \end{quote}
% where the T and B forms require the colour parameters to be in left-right
-% horizontal order (eg, left, middle, right),
+% horizontal order (e.g.,~left, middle, right),
% while the L and R forms require the colour parameters to be in top-down
-% vertical order (eg, top, middle, bottom).
+% vertical order (e.g.,~top, middle, bottom).
% Note that this means that the colour parameters of the L and R commands
% can (if required) then be positioned intuitively (vertically) as follows:
% \begin{quote}
@@ -1864,11 +2715,9 @@
% \DrawRubikLayerSideR{O}{B}{R}
% \DrawRubikLayerSideB{R}{G}{O}
%
-% \node (LT) at (0.5, 2.5)
-% [red]{\small\textsf{LT}};
-% \node (LM) at (0.5, 1.5)
-% [red]{\small\textsf{LM}};
-% }
+% \node (LT) at (0.5, 2.5) [red]{\small\textsf{LT}};
+% \node (LM) at (0.5, 1.5) [red]{\small\textsf{LM}};
+% }
%\end{verbatim}
% \end{minipage}
%
@@ -1903,21 +2752,19 @@
% {R} {O}
% {Y} {O}
% \DrawRubikLayerSideB {O}{G}{G}
-% }
+% }
%\end{verbatim}
% \end{minipage}
%
% \bigskip
%
-% \DescribeMacro{\DrawFlatUpSide}
-% \textsc{important note}: If the colour configuration of the \textit{whole}
-% cube is already known to the system (i.e.,~it has been specified before,
-% and (possibly) been manipulated using the \cmd{\RubikRotation..} command
+% \DescribeMacro{\DrawFaceUpSide}
+% \textsc{important note}: If the colour configuration of the layer shown above
+% is already known to the system (i.e.,~it has been specified before,
+% and (possibly) been manipulated using the \cmd{\RubikRotation} command
% from \textsc{rubikrotation} package), then the above figure could be
-% drawn much more simply using just the single \cmd{\DrawFlatUpSide} command,
-% as described in Section~\ref{sec:flatcommands}. In short, using the
-% \texttt{rubikrotation} package to keep track of the Rubik cube configuration makes
-% drawing these images considerably simpler.
+% drawn much more simply using just the single \cmd{\DrawFaceUpSide} command,
+% as described in Section~\ref{sec:facecommands}.
%
% \bigskip
%
@@ -1930,14 +2777,15 @@
% These sidebar values (decimal values $\geq 0$; no units) can be
% changed from their default values using the three commands.
% \begin{quote}
-% \cmd{\RubikSideBarWidth\{\}}\\
-% \cmd{\RubikSideBarLength\{\}}\\
-% \cmd{\RubikSideBarSep\{\}}
+% \cmd{\RubikSideBarWidth\{\}}\hspace{35.751pt}(default = 0.3)\\
+% \cmd{\RubikSideBarLength\{\}}\hspace{30pt}(default = 1.0)\\
+% \cmd{\RubikSideBarSep\{\}}\hspace{46.251pt}(default = 0.3)
% \end{quote}
% Values set in the document preamble will apply globally, while values
% set within a TikZ picture environment will apply only locally to that
% particular environment, as shown in the following example where we have
-% set both the sidebar width and length to 0.7.
+% set both the sidebar width and length to 0.7 in position MTy using the command
+% \verb!\DrawRubikLayerSideMTy{G}! (for the MTy code see Figure~\ref{fig:facenotation}).
%
% \bigskip
%
@@ -1965,7 +2813,7 @@
% \RubikSideBarWidth{0.7}
% \RubikSideBarLength{0.7}
% \DrawRubikLayerSideMTy{G}
-% }
+% }
%\end{verbatim}
% \end{minipage}
%
@@ -1979,12 +2827,11 @@
% Since the \textsc{front} face drawn using the \cmd{\DrawRubikCube} command is
% identical with that drawn using the \cmd{\DrawLayerFace} command it
% follows that LayerSide commands can also be used in conjunction with
-% the \textsc{front} face drawn using \cmd{\DrawRubikCube} command, as
-% shown in the following example. Note that in this example we have used the
-% \cmd{\ShowCubeF} command as an exercise to implement the fbox and reveal
-% the extent of the surrounding white space associated with a minipage width of
-% 3.5cm ($=5 \times 0.7$) ---showing that a sidebar increases the image width by about
-% 0.5 the width of a cubie.
+% the \textsc{front} face drawn using \cmd{\DrawRubikCube} command. This
+% shown in the following example, where we have used the
+% \cmd{\ShowCubeF} command as an exercise (to implement the fbox) and reveal
+% the extent of the surrounding white space associated with the minipage width of
+% 3.5cm ($=5 \times 0.7$).
%
% \bigskip
%
@@ -2025,233 +2872,219 @@
% \DrawRubikCubeRU
% \DrawRubikLayerSideL{G}{B}{R}
% \DrawRubikLayerSideB{R}{G}{O}
-% }
+% }
%\end{verbatim}
% \end{minipage}
%
% \bigskip
%
-% {\noindent}Note that since using a left or a right \cmd{\DrawRubikLayerSide}
-% command in conjunction with a \cmd{\DrawRubikCube} command will necessarily
-% increase the width of the image, one may also have to adjust the width of
-% the associated minipage.
-%
-% \pagebreak
+% Since using left and/or right sidebars (e.g.,~\cmd{\DrawRubikLayerSide})
+% in conjunction with a \cmd{\DrawRubikCube} command, will increase
+% the width of the image, one may also have to adjust the width of
+% the associated minipage. Note that the width of a 2D oblique view of the cube
+% is 4~units (= width of 4~cubies). With the default sidebar width and sep settings
+% (see above) one sidebar increases the 2D cube image width by 0.6\,units (= 0.3 + 0.3).
+% Sidebars on both sides increase the width by 1.2\,units. Note also that setting
+% both the sidebar width and separation to 0.25\,units has the convenience that
+% the 2D width of a cube face $+$ left and right sidebars (e.g.,~using \cmd{\DrawFaceUpSide})
+% is then exactly 5\,units.
+%
+%
+%
+%
+% \section[ShowSequence command]{\cmd{\ShowSequence} command}
+% \label{sec:showsequence}
+%
+% \DescribeMacro{\ShowSequence}
+% \DescribeMacro{\ShowSequenceF}
+% \DescribeMacro{\ShowSequencef}
+% The \cmd{\ShowSequence}\marg{separator}\marg{font-code}\marg{sequence} command
+% typesets a comma-separated sequence of rotation
+% codes---for code see Section~\ref{sec:codeshowsequence}.
+% Appending an `F' to the command-name (\cmd{\ShowSequenceF}) results in an fbox about
+% the whole output (cf.~the \cmd{\ShowCubeF} command).
+% Appending an `f' to the command-name (\cmd{\ShowSequencef}) results in an fbox about
+% each element in the output (these two forms can be helpful when checking white space).
+%
+% The \cmd{\ShowSequence} command takes three mandatory arguments:
+% the first is the separator (\verb!#1!),
+% the second is the font or style code (\verb!#2!),
+% and third is a comma-separated sequence of Rubik rotation codes (|#3|).
+%
+% The separator (e.g.,~comma) used for typesetting the sequence can be specified
+% (or just omitted---i.e.,~an empty bracket);
+% the sequence can be either a named sequence (i.e.,~encoded as a macro) or just a
+% comma separated sequence of rotation codes.
%
-% \subsection{Flat commands}
-% \label{sec:flatcommands}
+% \noindent\textsc{usage}:
+% The following command displays the rotation sequence F, R, U, Rp, Up, using
+% the \verb!\rr! encoding and comma \& space separated.
%
-% \DescribeMacro{\DrawFlatUp}
-% \DescribeMacro{\DrawFlatDown}
-% \DescribeMacro{\DrawFlatLeft}
-% \DescribeMacro{\DrawFlatRight}
-% \DescribeMacro{\DrawFlatFront}
-% \DescribeMacro{\DrawFlatBack}
-% These commands \cmd{\DrawFlat..}\marg{x}\marg{y} draw a `flat' (square)
-% representation of a specified face such that its bottom left corner
-% is positioned at ($x$, $y$).
-% They are designed to supplement the \cmd{\DrawRubikCube...} commands and
-% allow hidden faces to be represented.
-% Each command (except \cmd{\DrawFlatFront}) takes two arguments,
-% namely the X-coordinate and Y-coordinate of the bottom left
-% corner of the face. This ($x$,$y$) pair allows the user to position
-% the face.
+% \medskip
%
-% Note that the Y-argument set for the \cmd{\DrawFlatLeft}
-% and \cmd{\DrawFlatRight} commands is not currently actioned
-% (see Section~\ref{sec:drawflatxcommands}),
-% since both the \textsc{left} and \textsc{right} faces as used by the
-% \cmd{\DrawRubikCubeFlat} command---since this shows the RU view---requires only Y=0
-% (this (x,y) facility will be fully extended to the left and right forms in a
-% later version).
-% Note also that the \cmd{\DrawFlatFront} command currently takes no arguments,
-% since by definition the bottom left corner of this face is always at (0,0),
-% and there seems to be no reason (just now) for this face to have the
-% (x,y) facility.
+% \verb!\ShowSequence{,\ }{\rr}{F,R,U,Rp,Up}! \ \ $\rightarrow$ \ \ \ShowSequence{,\ }{\rr}{F,R,U,Rp,Up}
%
-% In the following example we use the command \verb!\DrawFlatBack{4}{1}! to
-% append the \textsc{back} face to the side of a 3D cube. Note that since
-% the coordinates of the bottom/back/right corner of the cube rendered by the
-% command \cmd{\DrawRubikCubeRU} is (4,1)
-% (see Section~\ref{sec:coordinates}), we can position the
-% lower/left corner of the \textsc{back} face at this point using the command
-% \verb!\DrawFlatBack{4}{1}! as follows:
+% \medskip
%
-% \bigskip
-%
-% \begin{minipage}{0.4\textwidth}
-% \centering
-% \RubikCubeSolved
-% \begin{tikzpicture}[scale=0.4]
-% \DrawRubikCubeRU
-% \DrawFlatBack{4}{1}
-% \end{tikzpicture}%
-% \end{minipage}
-% \begin{minipage}{5cm}
-%\begin{verbatim}
-% \RubikCubeSolved
-% \ShowCube{3cm}{0.4}{%
-% \DrawRubikCubeRU
-% \DrawFlatBack{4}{1}
-% }
-%\end{verbatim}
-% \end{minipage}
-%
-% \bigskip
+% Remember that if you want a very long sequence to break automatically
+% at the line-ends, then you need to include at least one space between
+% the sequence elements, either with or without a comma; for this the
+% separator argument needs to include a space, i.e.,~something like
+% \verb!{,\ }! or \verb!{\ }! or just \verb!{ }! perhaps.
%
%
-% \DescribeMacro{\DrawFlatUpSide}
-% \DescribeMacro{\DrawFlatDownSide}
-% \DescribeMacro{\DrawFlatLeftSide}
-% \DescribeMacro{\DrawFlatRightSide}
-% \DescribeMacro{\DrawFlatFrontSide}
-% \DescribeMacro{\DrawFlatBackSide}
-% These commands draw a face and all the associated side facelets.
-% In the following example we use the \cmd{\DrawFlatUpSide} command to
-% draw the \textsc{up} face and all its side-bars of a cube having
-% a `solved' configuration.
+% For~example, the following commands typeset the comma-separated
+% rotation sequence U,D,Lp,R using different separators and fonts.
+% For convenience, we start by encoding the sequence as the macro \verb!\myseq!.
%
%
-% \bigskip
-%
-% \begin{minipage}{0.4\textwidth}
-% \centering
-% \RubikCubeSolved
-% \begin{tikzpicture}[scale=0.4]
-% \DrawFlatUpSide
-% \end{tikzpicture}%
-% \end{minipage}
-% \begin{minipage}{5cm}
-%\begin{verbatim}
-% \RubikCubeSolved
-% \ShowCube{1.6cm}{0.4}{%
-% \DrawFlatUpSide
-% }
-%\end{verbatim}
-% \end{minipage}
-%
-% \bigskip
+% \newcommand{\myseq}{U,D,Lp,R}
%
-% \DescribeMacro{\DrawRubikFlat}
-% This command draws the completely flat format of the cube, as shown in the following example.
-%
-% \bigskip
-%
-% \begin{minipage}{0.4\textwidth}
-% \centering
-% \begin{tikzpicture}[scale=0.4]
-% \RubikCubeSolved
-% \DrawRubikFlat
-% \node (U) at (1.5, 4.5) [black]{\small\textsf{U}};
-% \node (D) at (1.5, -1.5) [black]{\small\textsf{D}};
-% \node (L) at (-1.5, 1.5) [black]{\small\textsf{L}};
-% \node (R) at (4.5, 1.5) [black]{\small\textsf{R}};
-% \node (F) at (1.5, 1.5) [black]{\small\textsf{F}};
-% \node (B) at (7.5, 1.5) [black]{\small\textsf{B}};
-% \end{tikzpicture}%
-% \noindent\strut\hspace{5mm}\texttt{$\backslash$DrawRubikFlat}
-% \end{minipage}
-% \begin{minipage}{5cm}
-%\begin{verbatim}
-% \RubikCubeSolved
-% \ShowCube{5cm}{0.4}{\DrawRubikFlat}
-%\end{verbatim}
-% \end{minipage}
-%
-% \bigskip
-%
-% The addition of text (numbers or letters) in the faces is
-% straightforward---the origin of the 1-unit grid is located at the
-% bottom left corner of the front face (orange here).
-% The letters were placed using the following TikZ code inside the
-% TikZ picture environment.
-%
-%\begin{verbatim}
-% \RubikCubeSolved
-% \ShowCube{5cm}{0.4}{%
-% \DrawRubikFlat
-% \node (U) at (1.5, 4.5) [black]{\small\textsf{U}};
-% \node (D) at (1.5, -1.5) [black]{\small\textsf{D}};
-% \node (L) at (-1.5, 1.5) [black]{\small\textsf{L}};
-% \node (R) at (4.5, 1.5) [black]{\small\textsf{R}};
-% \node (F) at (1.5, 1.5) [black]{\small\textsf{F}};
-% \node (B) at (7.5, 1.5) [black]{\small\textsf{B}};
-% }
-%\end{verbatim}
-%
-% \DescribeMacro{\DrawRubikCubeFlat}
-% {\noindent}A useful `semi-flat' alternative format, which uses
-% the standard RU view of the cube and appends the three hidden
-% sides (see Rokicki \textit{etal.}, 2013), is generated by the
-% command \cmd{\DrawRubikCubeFlat} as follows.
-%
-% \bigskip
+% \medskip\noindent\verb!\newcommand{\myseq}{U,D,Lp,R}!
%
-% \begin{minipage}{5cm}
-% \begin{tikzpicture}[scale=0.5]
-% \RubikCubeSolved
-% \DrawRubikCubeFlat
-% \node (B) at (5.5, 2.5) [white]{\small\textsf{B}};
-% \end{tikzpicture}%
-% \end{minipage}
-% \begin{minipage}{5cm}
-%\begin{verbatim}
-% \RubikCubeSolved
-% \ShowCube{5cm}{0.5}{%
-% \DrawRubikCubeFlat
-% \node (B) at (5.5, 2.5)
-% [white]{\small\textsf{B}};
-% }
-%\end{verbatim}
-% \end{minipage}
-%
-% \bigskip
+% \medskip\noindent\verb!\ShowSequence{,}{\texttt}{\myseq}! \ $\longrightarrow$ \ \ShowSequence{,}{\texttt}{\myseq}
%
-% Note that even in this configuration it is straight-forward to
-% write text on the graphic, since the width (on the page) of
-% the green \textsc{right} face is exactly 1-unit, and the
-% bottom right-hand corner of the green face is raised exactly 1-unit
-% (see Figure~\ref{fig:cubesquaregraph}).
-% Consequently, since the origin of the grid is at the bottom left
-% corner of the front face, the coordinates of the center of the
-% red \textsc{back} face is (5.5, 2.5).
-%
-% \section[NCube]{NCube (NxNxN)}
-% \label{sec:NCube}
+% \medskip\noindent\verb!\ShowSequence{,}{\rr}{\myseq}! \ $\longrightarrow$ \ \rr{U},\rr{D},\rr{Lp},\rr{R}
+%
+% \medskip\noindent\verb!\ShowSequence{}{\rrh}{\myseq}! \ $\longrightarrow$ \ \rrh{U}\rrh{D}\rrh{Lp}\rrh{R}
+%
+% \medskip\noindent\verb!\ShowSequence{\ }{\rrh}{\myseq}! \ $\longrightarrow$ \ \rrh{U}\ \rrh{D}\ \rrh{Lp}\ \rrh{R}
%
-% \DescribeMacro{\DrawNCubeAll}
-% An `NCube' is a solved NxNxN cube drawn from the RU direction;
-% (i.e.,~only shows faces \textsc{up}, \textsc{front}, \textsc{right}).
-% The cubie colours of each face are All the same.
-% \begin{quote}
-% \cmd{\DrawNCubeAll\{N\}\{Xcolour\}\{Ycolour\}\{Zcolour\}}.
-% \end{quote}
-% This command takes four ordered parameters (N, X, Y, Z)---the number
-% (integer; $N>0$) of cubies along an edge, followed by three face
-% colours in XYZ order.
-% Since the viewpoint is only from the RU direction, the three colour
-% parameters are: X(Right), Y(Up), Z(Front).
-%
-% \bigskip
-%
-% \begin{minipage}{0.3\textwidth}
-% \begin{tikzpicture}[scale=0.5]
-% \DrawNCubeAll{5}{O}{Y}{G}
-% \end{tikzpicture}%
-% \end{minipage}
-% \begin{minipage}{0.5\textwidth}
+% \medskip\noindent\verb!\ShowSequence{,\ }{\textRubik}{\myseq}! \ $\longrightarrow$ \ \textRubik{U},\ \textRubik{D},\
+% \textRubik{Lp},\ \textRubik{R}
+%
+%
+% \subsection*{Trailing digits}
+%
+% Note that the fonts denoted by \verb!\rr!, \verb!\rrh!, \verb!\Rubik!
+% and \verb!\textRubik! will fail for rotation codes which
+% have a trailing digit, e.g.,~R2, Dp3 (so-called `short' codes), since the
+% \verb!\ShowSequence! macro currently only reads the whole string between pairs of
+% commas (i.e.,~it does not interpret each string). However, the typewriter font \verb!\texttt!
+% does work correctly in this case, as you would expect.
+%
+% An effective `work-around' for this limitation is provided by the \verb!\RubikRotation{}!
+% command\,\footnote{Using the \texttt{--shell-escape} command-line option
+% with the \LaTeX\ engine---see Section~\ref{sec:rubikrotation}.}
+% (part of the \textsc{rubikrotation} package), since this returns (via the Perl program
+% \texttt{rubikrotation.pl}) an extended (`long') form of a given sequence in which
+% any `short' rotation codes are converted into their separate (atomic) long-form rotation codes;
+% the associated string is \verb!\SequenceLong!.
+% In fact three different forms of the sequence are returned, as shown below.
+%
+% For~example, consider the following short-form sequence L,R,D2,L3, and denote
+% it as `seqA' as follows: \verb!\newcommand{\seqA}{[seqA],L,R,D2,L3,<test>}!.
+% In this case D2,L3, and the name `seqA' fail to be typeset when using
+% the \verb!\rr! font with the \verb!\ShowSequence! command as follows:
+%
+% \newcommand{\seqA}{[seqA],L,R,D2,L3,<test>}
+%
+% \medskip\noindent\verb!\newcommand{\seqA}{[seqA],L,R,D2,L3,<test>}!
+%
+% \medskip\noindent\verb!\ShowSequence{,}{\texttt}{\seqA}! \ $\longrightarrow$ \ \ShowSequence{,}{\texttt}{\seqA}
+%
+% \medskip\noindent\verb!\ShowSequence{,}{\rr}{\seqA}! \ $\longrightarrow$ \ \ShowSequence{,}{\rr}{\seqA}
+%
+% \medskip
+%
+% However, if we now run the command \verb!\RubikRotation{\seqA}! we shall then have
+% at our disposal the following four strings:
+%
+% \medskip
+%
+% \verb!\SequenceInfo = ! test
+%
+% \verb!\SequenceName = ! seqA
+%
+% \verb!\SequenceShort = ! L,R,D2,L3
+%
+% \verb!\SequenceLong = ! L,R,D,D,L,L,L
+%
+% \medskip
+%
+% {\noindent}and therefore have full control over typesetting rotation sequences.
+% This approach therefore offers sufficient flexibility for most purposes.
+% For~example, if we now write the command \verb!\ShowSequence{,}{\rr}{\SequenceLong}!
+% we obtain
+%
+% \medskip\noindent\verb!\ShowSequence{,}{\rr}{\SequenceLong}! \ $\longrightarrow$ \
+% \ShowSequence{,}{\rr}{L,R,D,D,L,L,L}
+%
+% \medskip
+%
+% In practice, any trailing digit is converted (modulo~4) and expanded accordingly, the details being
+% copied to the log-file. For~example, if one writes the command
+% \cmd{\RubikRotation\{[test],R,D28978\}}, then since $28978 \equiv 2$\,(modulo~4) then \cmd{\SequenceLong}
+% will be returned containing the string |R,D,D|. The associated entries in the log-file are
+% as follows:
%\begin{verbatim}
-% \ShowCube{3.5cm}{0.5}{\DrawNCubeAll{5}{O}{Y}{G}}
+%...rotation R OK
+%...Expanding D28978 (28978 = 2 mod 4) ...
+%...rotation D OK (= Dp3)
+%...rotation D OK (= Dp3)
+%...writing new Rubik state to file rubikstateNEW.dat
+%...SequenceName = test
+%...SequenceShort = R,D28978
+%...SequenceLong = R,D,D
%\end{verbatim}
-% \end{minipage}
%
-% \medskip
%
-% \subsubsection[Draw.. error message]{\cmd{\draw} error message}
%
-% See also section~\ref{sec:drawerrormessage} regarding the error message associated with
-% using a \cmd{\Draw...} command \textit{outside} a TikZ picture environment.
-%
+% \section{SequenceBrace commands}
+% \label{sec:sequencebrace}
+%
+% \DescribeMacro{\SequenceBraceA}
+% \DescribeMacro{\SequenceBraceB}
+% \DescribeMacro{\SequenceBraceAF}
+% \DescribeMacro{\SequenceBraceBF}
+% The \cmd{\SequenceBraceX}\marg{name}\marg{sequence} command
+% is a tool for displaying a named sequence using a brace. The trailing~A
+% denotes that the brace is placed Above the sequence; the trailing~B denotes
+% the brace is Below the sequence.
+% Appending an `F' to the command-name (e.g.,~\cmd{\SequenceBraceAF}) results
+% in a surrounding fbox (cf.~the \cmd{\ShowCubeF} command).
+% For the code see Section~\ref{sec:sequencebracecode}.
+%
+% {\noindent}Thus \verb!\SequenceBraceB{myseq}{U,D,L,R}! generates
+% \ \SequenceBraceB{myseq}{U,D,L,R}.
+%
+% {\noindent}A typical example of its use might be:
+%
+% \bigskip
+%
+%\noindent%
+%\RubikCubeSolved%
+%\ShowCube{1.6cm}{0.4}{\DrawRubikCubeRU}%
+%\quad\SequenceBraceA{fourspot}{\ShowSequence{}{\Rubik}{F,F,B,B,U,Dp,R,R,L,L,U,Dp}}%
+%\quad$\longrightarrow$\quad%
+%\RubikFaceFront{R}{R}{R}%
+% {R}{O}{R}%
+% {R}{R}{R}%
+%\RubikFaceRight{B}{B}{B}%
+% {B}{G}{B}%
+% {B}{B}{B}%
+%\ShowCube{1.6cm}{0.4}{\DrawRubikCubeRU}%
+%
+%
+% \bigskip
+%
+% {\noindent}which was generated by the following code, showing that the \cmd{\ShowSequence}
+% command can be used as an argument for the \cmd{\SequenceBraceA} command:
+%\begin{verbatim}
+%\newcommand{\fourspot}{[fourspot],F2,B2,U,Dp,R2,L2,U,Dp}%
+%\noindent%
+%\RubikCubeSolved%
+%\ShowCube{1.6cm}{0.4}{\DrawRubikCubeRU}%
+%\RubikRotation{\fourspot}%
+%\quad\SequenceBraceA{\SequenceName}{%
+% \ShowSequence{}{\Rubik}{\SequenceLong}}%
+%\quad$\longrightarrow$\quad%
+%\ShowCube{1.6cm}{0.4}{\DrawRubikCubeRU}%
+%\end{verbatim}
+% Note (1)~that the `fourspot' listing is included in the \textsc{rubikpatterns} package, and
+% (2)~the \cmd{\RubikRotation} command requires using the \texttt{--shell-escape} command-line
+% option with the \LaTeX\ engine---see Section~\ref{sec:rubikrotation} for details.
+%
%
%
% \section{Arrows}
@@ -2259,31 +3092,40 @@
%
% The \rubikcube\ package does not offer any special commands for drawing
% arrows since it is straightforward just to include the appropriate TikZ
-% `draw' commands in the \texttt{tikzpicture} environment.
+% `draw' commands in the \texttt{tikzpicture} environment (i.e.,~in our
+% own \cmd{\ShowCube} environment).
%
-% In order to facilitate using the standard TikZ `draw' commands both
-% the RubikCubeFaceFront and LayerFace commands have the coordinate origin
-% at the bottom left corner, and draw `faces' consisting of 9~unit-squares
-% in a 3x3 grid, as shown in Figure~\ref{fig:facegraph}.
+% In order to facilitate using the standard TikZ `draw' commands
+% the graphic grid origin of Rubik cube images is located at the bottom left corner
+% of the \textsc{front} face (see also Section~\ref{sec:coordinates} for details of the
+% cube's coordinate system). Similarly, single face images (e.g.,~drawn using the
+% \cmd{\DrawFlatUp} or \cmd{\DrawFlatUpSide} and LayerFace commands etc.) have
+% their grid origin at the bottom left corner of the face.
% Consequently the start and finish coordinates for any arrow or line are
-% easy to determine.
+% easy to determine.
%
% \begin{figure}[hbt]
% \centering
% \ifpdf
-% \includegraphics[height=3cm]{Rubik-doc-figE.pdf}
+% \includegraphics[height=3cm]{rubik-doc-figE.pdf}
% \else
-% \includegraphics[height=3cm]{Rubik-doc-figE.eps}
+% \includegraphics[height=3cm]{rubik-doc-figE.eps}
% \fi
-% \vspace{-5mm}\caption{\label{fig:facegraph}RubikCubeFaceFront and RubikLayerFace coordinates}
+%
+% \parbox{9cm}{%
+% \caption{\label{fig:facegraph}Grid showing the positive coordinates
+% associated with \textsc{front} face of a cube image, or of a face-only image.}
+% }%
% \end{figure}
%
-% For example, in Figure~\ref{fig:facegraph} we have drawn a green
-% arrow from the centre of cubie LB $(0.5, 0.5)$ to the centre of
+% \medskip
+%
+% For~example, Figure~\ref{fig:facegraph} shows a green
+% arrow drawn from the centre of cubie LB $(0.5, 0.5)$ to the centre of
% cubie MM\,\footnote{The code MM stands for x=Middle, y=Middle;
% see also Figure~\ref{fig:facenotation} on Rubik face-notation} $(1.5, 1.5)$.
-% To do this we just include the following TikZ command in the
-% \texttt{tikzpicture} environment.
+% To do this we just include the following TikZ command, remembering that TikZ
+% commands require a terminal semicolon.
% \begin{quote}
%\begin{verbatim}
% \draw[->,color=green] (0.5,0.5) -- (1.5, 1.5);
@@ -2316,7 +3158,7 @@
% \draw[->,thick,color=magenta] (1.3, 2.3) -- (1.3, 0.5);
% \draw[<->,thick,color=magenta] (0.5,2.6) -- (2.5, 2.6);
% \draw[<->,thick,color=magenta] (0.5,0.3) -- (2.5, 0.3);
-% }
+% }
%\end{verbatim}
% \end{minipage}
%
@@ -2357,7 +3199,7 @@
% {Y} {O}
% \DrawRubikLayerSideB {O}{G}{G}
% \draw[->,ultra thick,color=green] (0.5,5) -- (0.5, 4);
-% }
+% }
%\end{verbatim}
% \end{minipage}
%
@@ -2408,39 +3250,77 @@
% \DrawRubikCubeRD
% \draw[ultra thick,->,color=blue]
% (1.5,0.5) -- (2.5, 1.5);
-% }
+% }
%\end{verbatim}
% \end{minipage}
-%
+%
+% \bigskip
+%
+% In the following example we use a blue circle to highlight the cubie
+% to be rotated into the top layer.
+%
+% \bigskip
+%
+% \noindent%
+% \RubikCubeGrey
+% \RubikFaceUp{X}{W}{X}%
+% {W}{W}{W}%
+% {W}{W}{X}%
+% \RubikSliceBottomR{X}{X}{W}{G}{X}{X}%
+% \ShowCube{2.5cm}{0.5}{%
+% \DrawRubikCubeRU
+% \DrawRubikLayerSideRBy{O}
+% \draw[ultra thick,->,color=blue] (2.5,0.5) -- (2.5, 2.5);
+% \draw [color=blue, thick] (2.7, 0.3) circle (1.3);
+% }%
+% \hspace{3mm}
+% \begin{minipage}{0.6\textwidth}
+%\begin{verbatim}
+% \noindent%
+% \RubikCubeGrey
+% \RubikFaceUp{X}{W}{X}
+% {W}{W}{W}
+% {W}{W}{X}
+% \RubikSliceBottomR{X}{X}{W}{G}{X}{X}
+% \ShowCube{2.5cm}{0.5}{%
+% \DrawRubikCubeRU
+% \DrawRubikLayerSideRBy{O}
+% \draw[ultra thick,->,color=blue]
+% (2.5,0.5) -- (2.5, 2.5);
+% \draw [color=blue, thick] (2.7, 0.3) circle (1.3);
+% }%
+%\end{verbatim}
+% \end{minipage}
%
%
% \section{Final example}
%
% We now present, as a final example, the code used to draw the front page
-% figure\,\footnote{This is a sequence of order 6 used to generate the `cross'
-% configuration when solving the cube. Doing it on a `solved' cube allows you
-% to see how the three edge cubies move, and either flip (magenta arrows) or do
-% not flip (black arrow).}.
-% This code uses both the \rubikcube\ and \textsc{rubikrotation} packages,
-% and therefore needs to be run using the \LaTeX\ \verb!--shell-escape! command-line switch,
-% as described in the \textsc{rubikrotation} package.
-%
+% figure\,\footnote{This is a well-known sequence of order 6 used to cycle three
+% edge cubies; it is used to generate the `cross' configuration in the final layer
+% when solving the cube. Here we are performing the sequence on a `solved' cube,
+% since this allows you to see how the three edge cubies move, and either
+% flip (magenta arrows) or do not flip (black arrow).}.
+% This code uses the \cmd{\RubikRotation} command (from the \textsc{rubikrotation}
+% package), and therefore the \LaTeX\ engine needs to be run using the
+% \verb!--shell-escape! command-line switch (see Section~\ref{sec:rubikrotation} for details).
%
% \bigskip
-% \hfil
-% \RubikCubeSolved
-% \ShowCube{2cm}{0.4}{\DrawRubikCubeRU}
-% \ShowCube{2cm}{0.4}{%
+%
+% \noindent\hfil%
+% \RubikCubeSolved%
+% \ShowCube{1.6cm}{0.4}{\DrawRubikCubeRU}%
+% \quad\ShowCube{1.6cm}{0.4}{%
% \DrawFlatUpSide
% \draw[thick,->,color=magenta] (1.5,0.5) -- (2.4, 1.4);
% \draw[thick,->] (2.5,1.5) -- (1.6, 2.4);
% \draw[thick,->,color=magenta] (1.3, 2.3) -- (1.3, 0.5);
% \draw[thick,<->, color=blue] (0.5,2.6) -- (2.5, 2.6);
% \draw[thick,<->, color=blue] (0.5,0.3) -- (2.5, 0.3);
-% }
-% \Rubik{F}\Rubik{R}\Rubik{U}\Rubik{Rp}\Rubik{Up}\Rubik{Fp}%
-% \ \ \ $\longrightarrow$
-% \ShowCube{2cm}{0.4}{%
+% }%
+% \quad\Rubik{F}\Rubik{R}\Rubik{U}\Rubik{Rp}\Rubik{Up}\Rubik{Fp}%
+% \quad$\longrightarrow$%
+% \quad\ShowCube{1.6cm}{0.4}{%
% \DrawRubikLayerFace{W}{W}{B}
% {W}{W}{O}
% {W}{R}{B}
@@ -2451,31 +3331,30 @@
% \DrawRubikLayerSideB {G}{W}{O}
% }
% \hfil
-% \bigskip
%
+% \bigskip
%
%\begin{verbatim}
-% \hfil
-% \RubikCubeSolved
-% \ShowCube{2cm}{0.4}{\DrawRubikCubeRU}
-% \ShowCube{2cm}{0.4}{%
-% \DrawFlatUpSide
+% \noindent\hfil%
+% \RubikCubeSolved%
+% \ShowCube{1.6cm}{0.4}{\DrawRubikCubeRU}%
+% \quad\ShowCube{1.6cm}{0.4}{%
+% \DrawFlatUpSide%
% \draw[thick,->,color=magenta] (1.5,0.5) -- (2.4, 1.4);
% \draw[thick,->] (2.5,1.5) -- (1.6, 2.4);
% \draw[thick,->,color=magenta] (1.3, 2.3) -- (1.3, 0.5);
% \draw[thick,<->, color=blue] (0.5,2.6) -- (2.5, 2.6);
% \draw[thick,<->, color=blue] (0.5,0.3) -- (2.5, 0.3);
-% }
-% \Rubik{F}\Rubik{R}\Rubik{U}\Rubik{Rp}\Rubik{Up}\Rubik{Fp}%
-% \ \ \ $\longrightarrow$
-% \RubikRotation{F,R,U,Rp,Up,Fp}
-% \ShowCubeF{2cm}{0.4}{\DrawFlatUpSide}
+% }%
+% \RubikRotation{F,R,U,Rp,Up,Fp}%
+% \quad\ShowSequence{}{\Rubik}{\SequenceLong}\quad$\longrightarrow$%
+% \ShowCube{1.6cm}{0.4}{\DrawFlatUpSide}%
% \hfil
%\end{verbatim}
%
%
%
-% \subsection[Without using {\textbackslash}RubikRotation]{Without using \cmd{\RubikRotation..}}
+% \subsection[Without using {\textbackslash}RubikRotation]{Without using \cmd{\RubikRotation}}
%
% If you really need to draw the above figure \textit{without} using
% the \textsc{rubikrotation} package (as we had to in order to write
@@ -2483,11 +3362,14 @@
% commands
%\begin{verbatim}
% \RubikRotation{F,R,U,Rp,Up,Fp}
-% \ShowCubeF{2cm}{0.4}{\DrawFlatUpSide}
+% \ShowSequence{,}{\Rubik}{\SequenceLong} \ \ \ $\longrightarrow$
+% \ShowCube{2cm}{0.4}{\DrawFlatUpSide}
%\end{verbatim}
-% with the following set of \cmd{\DrawRubikLayer...} commands.
+% with the following commands:
%
%\begin{verbatim}
+% \Rubik{F}\Rubik{R}\Rubik{U}\Rubik{Rp}\Rubik{Up}\Rubik{Fp}
+% \ \ \ $\longrightarrow$
% \ShowCube{2cm}{0.4}{%
% \DrawRubikLayerFace{W}{W}{B}
% {W}{W}{O}
@@ -2497,71 +3379,129 @@
% {B} {W}
% {O} {W}
% \DrawRubikLayerSideB {G}{W}{O}
-% }
+% }
%\end{verbatim}
%
%
%
%
%
-% \section{Known issues \& shortcomings}
+% \section{Known limitations}
%
-% Please contact the authors regarding any ideas, errors or shortcomings etc.
+% Please contact the authors regarding any ideas for improvement, errors,
+% problems or shortcomings etc.
%
% \begin{itemize}
%
-% \item The rotation hieroglyphs are optimised for a 10pt font, and do
-% not scale with document font size. However, they do
-% seem to work reasonably well with both 11pt and 12pt fonts.
-% Any suggestions are welcome.
-%
-% \item The sidebars cannot be arbitrarily positioned.
+% \item Note that the rotation hieroglyphs are optimised for a 10pt font
+% and do not scale with document font size. However, they do work well in
+% conjunction with the standard 11pt and 12pt document fonts sizes. Nevertheless,
+% the font size can of course be changed by renewing the font command
+% (see Section~\ref{sec:rubikfont} for details).
+%
+% \item The sidebars cannot be arbitrarily positioned (note: hidden
+% faces can be arbitrarily positioned).
%
% \end{itemize}
%
%
-% \section{Acknowledgements}
-%
-% We would like to thank Peter Bartal and Peter Grill for useful ideas and
-% suggestions. We have built on some of their ideas and have acknowledged
-% these instances in the documentation.
-% We would also like to thank Christian Tellechea for the \cmd{\@join\{\}\{\}} command.
-%
-%
-%
-% \section{Future supporting packages}
+% \section{Future packages}
%
% Since Rubik-type cubes currently exist in a variety of sizes (from 2x2x2 to 11x11x11)
-% it is possible that similar packages dealing with cubes of other sizes may be made in
-% the future. Supporting tools may also be made
+% other authors may well create similar packages dealing with
+% cubes of other sizes the future. Supporting tools may also be made
% using various programming languages, e.g.,~Lua etc. Consequently the naming of such
% packages and tools, and even the associated CTAN directories, needs to be given
% some thought in order to prevent possible confusion.
%
-% In the event of new packages being made, we suggest that a CTAN directory structure
+% In the event of new packages being made, may we suggest that a CTAN directory structure
% along the following lines might be appropriate.
%
% $$
-% \textsc{rubik} \left\{
-% \begin{array}{l}
-% \mbox{rubiktools}\\
-% \mbox{rubik2x}\\
-% \mbox{rubik3x}\\
-% \ldots\\
-% \mbox{rubik11x}\\
-% \end{array}
-% \right.\\
+% \textsc{rubik}
+% \left\{
+% \begin{array}{l}
+% \mbox{rubiktools}\\
+% \mbox{rubik2x}\\
+% \mbox{rubik3x}\\
+% \ldots\\
+% \mbox{rubik11x}\\
+% \end{array}
+% \right.\\
% $$
%
%
%
-% \section{History}
+% \section{Change history}
%
% \begin{itemize}
-
+%
+% \item Version 4.0 (March 2017)
+%
+% ---Improved documentation.
+%
+% ---Improved inter-hieroglyph spacing and vertical position. The Computer Moderm sans bold font
+% (10/12pt) is used for the hieroglyphs and rotation codes (see Section~\ref{sec:coderubikfont}
+% for details).
+%
+% ---Improved the \cmd{\ShowCube} and \cmd{\ShowCubeF} macros (see Sections~\ref{sec:showcube}
+% and \ref{sec:showcubecode}).
+%
+% ---Additional notation for middle slice rotations (`m' notation), e.g.,~\rr{Rm}, \rr{Rmp} etc
+% (see Sections~\ref{sec:mnotation} and \ref{sec:codeJaap}).
+%
+% ---Additional notation for whole cube rotations (`c' notation), e.g.,~\rr{Rc}, \rr{Rcp} etc
+% (see Sections~\ref{sec:cnotation} and \ref{sec:codeJaap}).
+%
+% ---Added Randelshofer notation (the `CMST' rotations), e.g.,~\rr{CR}, \rr{MR} etc
+% (see Sections~\ref{sec:listofRandelshofercommands} and \ref{sec:codeRandelshofer}).
+%
+%
+% ---Two new (more-intuitive) \cmd{\Draw..} commands replace earlier (now deprecated)
+% ambiguous versions; these new versions are now consistent with
+% the other \cmd{\DrawRubikCubeXX} commands (see Section~\ref{sec:flatcommands}).
+% \begin{quote}
+% \cmd{\DrawRubikCubeF} (F = flat) ---replaces \cmd{\DrawRubikFlat}.
+% \newline\cmd{\DrawRubikCubeSF} (SF = semi-flat) ---replaces \cmd{\DrawRubikCubeFlat}.
+% \end{quote}
+%
+%
+% ---Six new commands for showing and annotating rotation sequences; the versions with a
+% terminal `F' also surround the object with an fbox to allow users to see the extent
+% of any associated white space
+% (see Sections~\ref{sec:showsequence} \& \ref{sec:sequencebrace}):
+% \begin{quote}
+% \cmd{\ShowSequence}
+% \newline\cmd{\ShowSequenceF}
+% \newline\cmd{\ShowSequencef}
+% \newline\cmd{\SequenceBraceA}
+% \newline\cmd{\SequenceBraceAF}
+% \newline\cmd{\SequenceBraceB}
+% \newline\cmd{\SequenceBraceBF}
+%
+% \end{quote}
+%
+% ---A new command for setting up or allocating a `solved' colour configuration.
+% (see Section~\ref{sec:solvedconfig}):
+% \begin{quote}
+% \cmd{\SolvedConfig}
+% \end{quote}
+%
+% ---A new command for setting up a `starter cube' for which the \textit{whole} cube
+% is allocated the default `grey' colour (see Section~\ref{sec:rubikcubegrey}):
+% \begin{quote}
+% \cmd{\RubikCubeGreyAll}
+% \end{quote}
+%
+% ---A new supporting \textsc{rubikpatterns} package has been added to
+% the Rubik bundle. It is a small macro database of well-known named Rubik patterns
+% and associated sequences (see Section~\ref{sec:patterns}).
+%
+%
+%
% \item Version 3.0 (September 2015)
%
-% ---All rotation commands can now use the rotation-code as an argument; for example,
+% ---All rotation commands can now use the rotation-code as an argument; for~example,
% the rotation \rr{D} can now be typeset using the command \cmd{\rr\{D\}} etc
% (see Section~\ref{sec:RubikCommands}).
% The new rotation commands are:
@@ -2605,13 +3545,13 @@
%
% ---Changed `Equator' $\rightarrow$ `Middle' in all \cmd{\DrawLayer..}
% commands (for consistency). Hence `E' $\rightarrow$ `M' in all Flat
-% commands and Slice commands. Note although former use of `Equator' is
+% commands and Slice commands. Note that although the former use of `Equator' is
% retained for backward compatibility (for the moment) it is now deprecated.
%
% ---Fixed a conflict with the \TeX\ \cmd{\sb} command as used by the \textbf{url}
% package which resulted in reference chaos when the \textbf{url} package was used with
-% the \Rubikcube\ package (internalised \cmd{\sb} to \cmd{\@sb}). Also internalised for
-% convenience \cmd{\sd} to \cmd{\@sd}; \cmd{\sh} to \cmd{\@sh}; \cmd{\sc} to \cmd{\@sc};
+% the \Rubikcube\ package (internalised \cmd{\sb} to \cmd{\@sb}). Also internalised, for
+% convenience, \cmd{\sd} to \cmd{\@sd}; \cmd{\sh} to \cmd{\@sh}; \cmd{\sc} to \cmd{\@sc};
% \cmd{\sq} to \cmd{\@sq}.
%
%
@@ -2623,13 +3563,25 @@
%
%
%
+% \section{Acknowledgements}
+%
+% We would like to thank Peter Bartal and Peter Grill for useful ideas and
+% suggestions. We have built on some of their ideas and have acknowledged
+% these instances in the documentation.
+% Finally, we would like to thank Christian Tellechea for the \cmd{\@join\{\}\{\}}
+% command (see Section~\ref{sec:usefulinternalcommands}),
+% Christian Schr\"{o}ppel for help regarding the \textsf{forarray} package
+% (see Section~\ref{sec:codeshowsequence}), and Herbert Kociemba for helpful comments.
+%
+%
+%
+%
% \section{References}
%
% \begin{itemize}
%
%
-% \item Bartal P (2011)
-%
+% \item Bartal P (2011). \
% \url{http://tex.stackexchange.com/questions/34482/}
%
% \item Chen JJ (2004). Group theory and the Rubik's cube.
@@ -2638,7 +3590,7 @@
%
% \item Davis T (2006). Group theory via Rubik's cube.
% \url{http://www.geometer.org/rubik/group.pdf}
-
+%
% \item Demaine ED, Demaine ML, Eisenstat S, Lubiw A and Winslow A (2011).
% Algorithms for solving Rubik's cubes.
% \url{http://www.arxiv.org/abs/1106.5736/}
@@ -2658,14 +3610,16 @@
% \newline\url{http://duvoid.fr/rubik/rubik-friddrich-couleurs.pdf}
% \newline\url{http://duvoid.fr/rubik/sources/rubik-friddrich-couleurs.tex}
%
-% \item Feuers\"{a}nger (2015). Manual for package \textsc{pgfplots}
-% (\texttt{pgfplots.pdf}). v\,1.12.1 (2015/05/02), \S\,3.2.3, page~20.
-% \url{http://www.ctan.org/pkg/pgfplots}.
+% \item Feuers\"{a}nger (2016). Manual for package \textsc{pgfplots}.
+% v\,1.13 (2016/01/06), \S\,3.2.3, page~21. (\texttt{pgfplots.pdf})
+% \url{http://www.ctan.org/pkg/pgfplots}. [re: preventing extra white space]
%
-% \item Fridrich J. \ \ \url{http://www.ws.binghamton.edu/fridrich/}.
+% \item Fridrich website (Fridrich J.) \ \ \url{http://www.ws.binghamton.edu/fridrich/}.
% See the useful `notation' section on the `Pretty patterns' webpage at
% \url{http://www.ws.binghamton.edu/fridrich/ptrns.html}.
%
+% \item Frey AH and Singmaster D (1982). \textit{Handbook of cubik math},
+% (Enslow Publishers, Inc.) (republished: 2010, Lutterworth Press, UK)
%
% \item Golomb SW (1981). Rubik's cube and a model of quark confinement.
% \textit{Am.\ J.\ Phys.}; vol~49, pp~1030--1031.
@@ -2678,12 +3632,13 @@
% \item Gymrek M (2009). The mathematics of the Rubik's cube.
% \newline\url{http://web.mit.edu/sp.268/www/rubik.pdf}
%
+% \item Heise website (Heise R). Rubik's cube theory. \url{http://www.ryanheise.com/cube/theory.html}
+%
% \item Hofstadter D (1981). Rubik cube. \textit{Scientific American}; March issue.
%
% \item Hutchings M (2011). The mathematics of Rubik's cube (slide presentation).
% \url{http://math.berkeley.edu/~hutching/rubik.pdf}
%
-%
% \item Jelinek website (Jelinek J). Rubik's cube solution methods.
% \url{http://www.rubikscube.info/}
%
@@ -2691,18 +3646,29 @@
% Rubik's cube, Merlin's machine and other mathematical toys}; pp~322.
% \url{http://www.mike.verdone.ca/media/rubiks.pdf}
%
-% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm}
-%
+%
+% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm}
+% {\newline}---for superflip see: \url{http://www.kociemba.org/math/oh.htm}
+%
+%
% \item Kriz I and Siegel P (2008). Rubik's cube-inspired puzzles demonstrate math's
% simple groups. \textit{Scientific American}; July 2008
%
+% \item Longridge website (Longridge M). The cube pattern archive. \url{http://www.cubeman.org}
%
% \item Randelshofer website (Randelshofer W). Pretty patterns.
% \url{http://www.randelshofer.ch/rubik/patterns/}
%
-% \item Reid website (Reid M) \ \ \url{http://www.cflmath.com/Rubik/},
+% \item Reid website (Reid M) \ \ \url{http://www.cflmath.com/Rubik},
% for patterns see \url{http://www.cflmath.com/Rubik/patterns.html}
%
+% \item Reid M. (1995). Superflip requires 20 face turns. (January 1995)
+% \url{http://www.math.ucf.edu/~reid/Rubik/CubeLovers/}
+% {\newline}[cited from Rokicki \textit{et~al.}, 2013].
+% {\newline}(Note: easier to use is the following html indexed version of the
+% archive of the Cube-Lovers usenet group (1982--1997)
+% \url{http://www.math.rwth-aachen.de/~Martin.Schoenert/Cube-Lovers/})
+%
%
% \item Rokicki T, Kociemba H, Davidson M and Dethridge J (2013). The diameter of the
% Rubik's cube is twenty. \textit{SIAM.\ J.\ Discrete Math.}, \underline{27}, 1082--1105.
@@ -2711,7 +3677,15 @@
% \item Rubik's cube. See Section on notation.
% \newline\url{http://en.wikipedia.org/wiki/Rubik's_Cube}
%
-% \item Speedsolving website. \url{www.speedsolving.com/}
+% \item RuWix website (Ferenec D) \ \ \url{http://www.ruwix.com}.
+% See the online Rubik's cube solver \url{http://www.ruwix.com/online-rubiks-cube-solver-program}.
+%
+% \item Scherphius website (Scherphius J). Jaap Puzzles website
+% \url{http://www.jaapsch.net/puzzles/symmetr1.htm}
+%
+% \item Singmaster D (1981). \textit{Notes on Rubik's magic cube} (Harmondsworth, Eng., Penguin Books)
+%
+% \item Speedsolving website. \url{http://www.speedsolving.com/}
%
% \item Tran R (2005). A mathematical approach to solving Rubik's cube.
% \url{http://www.math.ubc.ca/~cass/courses/m308/projects/rtran/rtran.pdf}
@@ -2722,9 +3696,9 @@
% [cited from \textit{Wikipedia} (Rubik's cube)]
%
%
-% \item Vandenbergh L. \ \ \textsc{cubezone} \url{http://www.cubezone.be}
+% \item Vandenbergh website (Vandenbergh L.) \ \ \textsc{cubezone} \url{http://www.cubezone.be}
%
-% \item WCA (2015). World Cube Association Regulations. See Section~12 for notation.
+% \item WCA (2016). World Cube Association Regulations. See \S\,12 for notation.
% \url{http://www.worldcubeassociation.org/regulations.htm}
%
%
@@ -2742,17 +3716,17 @@
% The conventions we adopt regarding capital letters and the
% XYZ argument ordering are detailed in Section~\ref{sec:conventions}.
%
-% Note that it is important in a graphics package to use a trailing \% on
-% the end of lines which break before the terminal curley bracket of a newcommand.
+% Note that it is important when using a graphics package to use a trailing \% on
+% the end of lines which break before the terminal curly bracket of a \cmd{\newcommand}.
% This is to prevent accumulating spurious spaces which may otherwise appear in
-% figures and diagrams as a strange or unexpected horizontal shift or whitespace.
+% figures and diagrams as a strange or unexpected horizontal shift or white-space.
%
% \subsection{\hspace{3mm}Package heading}
%
% \begin{macrocode}
%<*rubikcube>
-\def\RCfileversion{3.0}%
-\def\RCfiledate{2015/09/25}%
+\def\RCfileversion{4.0}%
+\def\RCfiledate{2017/03/03}%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{rubikcube}[\RCfiledate\space (v\RCfileversion)]
% \end{macrocode}
@@ -2763,100 +3737,38 @@
\RequirePackage{tikz}}%
% \end{macrocode}
%
-% \begin{macro}{\rubikcube}
-% First we create a suitable logo
+% The package requires the Forarray package (see Section~\ref{sec:codeshowsequence})---so
+% we load it if not already loaded.
% \begin{macrocode}
-\newcommand{\rubikcube}{\textsc{rubikcube}}%
-\newcommand{\Rubikcube}{\textsc{Rubikcube}}%
+\@ifpackageloaded{forarray}{}{%
+ \typeout{---rubikcube requires the Forarray package.}%
+ \RequirePackage{forarray}}%
% \end{macrocode}
-% \end{macro}
-%
-%
-% \subsection{\hspace{3mm}Some useful internal commands}
-% \label{sec:usefulinternalcommands}
-%
-% \begin{macro}{\@rr}
-% \begin{macro}{\@rrp}
-% \begin{macro}{\@rrw}
-% \begin{macro}{\@rrwp}
-% \begin{macro}{\@rrs}
-% \begin{macro}{\@rrsp}
-% \begin{macro}{\@rra}
-% \begin{macro}{\@rrap}
-% \begin{macro}{\@xyzh}
-% \begin{macro}{\@xyzhp}
-% \begin{macro}{\@xyzRubik}
-% \begin{macro}{\@xyzRubikp}
-% \begin{macro}{\@SquareLetter}
-% \begin{macro}{\@hRubik}
-% Internal commands. These are used to generate the
-% prime, w, w-prime, s, s-prime, a, a-prime
-% rotation commands. The \cmd{\@xyz..} commands are used to generate the
-% x,y,z,u,d,l,r,f,b, and their prime rotation commands.
-% The \cmd{\@SquareLetter} command is used to form the separate square hieroglyph form
-% used for rotations with no visible representation from the front
-% (eg~B.., Fs, Fsp, Fa, Fap, S, Sp, Sf, Sfp, Sb, Sbp).
-% The \cmd{\@hRubik} is the vertical shift used to raise the box carying the rotation
-% rotation-code in \cmd{\Rubik..} commands not visible from the front.
%
-% The idea is that by using these internal
-% tools we will be able to more easily standardise the size and position
-% of all the various glyphs. However, these internal tools are currently
-% only partially implemented (= work in progress).
-% \begin{macrocode}
-\newcommand{\@rr}[1]{\textbf{\textsf{#1}}}
-\newcommand{\@rrp}[1]{\textbf{\textsf{#1}$^\prime$}}
-\newcommand{\@rrw}[1]{\textbf{\textsf{#1\footnotesize{w}}}}
-\newcommand{\@rrwp}[1]{\textbf{\textsf{#1\footnotesize{w}}$^\prime$}}
-\newcommand{\@rrs}[1]{\textbf{\textsf{#1\footnotesize{s}}}}
-\newcommand{\@rrsp}[1]{\textbf{\textsf{#1\footnotesize{s}}$^\prime$}}
-\newcommand{\@rra}[1]{\textbf{\textsf{#1\footnotesize{a}}}}
-\newcommand{\@rrap}[1]{\textbf{\textsf{#1\footnotesize{a}}$^\prime$}}
-\newcommand{\@xyzh}[1]{\textbf{[\textsf{#1}]}\,}
-\newcommand{\@xyzhp}[1]{\textbf{[\textsf{#1}$^\prime$]}\,}
-\newcommand{\@xyzRubik}[1]{\raisebox{3.45pt}{\textbf{[\textsf{#1}]}}}
-\newcommand{\@xyzRubikp}[1]{\raisebox{3.45pt}{\textbf{[\textsf{#1}$^\prime$]}}}
-\newcommand{\@SquareLetter}[1]{\setlength\fboxsep{2.5pt}\fboxrule=0.8pt%
- \fbox{\rule[-1pt]{0pt}{8.5pt}\raisebox{-0.5pt}{#1}}}
-\newlength\@hRubik%
-\setlength{\@hRubik}{0.185cm}%
+% The package requires the IfThen package (see Section~\ref{sec:codeshowsequence})---so
+% we load it if not already loaded.
+% \begin{macrocode}
+\@ifpackageloaded{ifthen}{}{%
+ \typeout{---rubikcube requires the IfThen package.}%
+ \RequirePackage{ifthen}}%
% \end{macrocode}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
-% \end{macro}
%
%
-% \begin{macro}{\@join}
-% We also require a macro for joining two strings so we can convert
-% a rotation-code, say U, into a macro which typesets it in some form, say \cmd{\rrhU}.
-% The following \cmd{\@join\{\}\{\}} command is by Christian Tellechea.
-% {\newline}Usage: \cmd{\@join\marg{command-stem}\marg{rotation-code}}. For example,
-% to create the command \cmd{\rrhU} we would write |\@join{\rrh}{U}|, and hence
-% the command |\rrh{U}| is equivalent to \cmd{\rrhU} (see Section~\ref{sec:cmdsusingjoin}).
-% {\newline}Since this macro is also useful for processing rotation-codes in a list,
-% which may also include macros, it is important that |#2| is not detokenized.
-% \begin{macrocode}
-\newcommand*\@join[2]{%
- \csname\expandafter\@gobble\string#1#2\endcsname}
+%
+% \begin{macro}{\rubikcube}
+% First we create a suitable logo
+% \begin{macrocode}
+\newcommand{\rubikcube}{\textsc{rubikcube}}%
+\newcommand{\Rubikcube}{\textsc{Rubikcube}}%
% \end{macrocode}
-% \end{macro}
+% \end{macro}
%
%
% \subsection{\hspace{3mm}Colours}
% \label{sec:codecolours}
%
-% These colour allocations were initially defined by Peter Bartal (2011).
+% We have adopted the following colour allocations; these were initially
+% defined by Peter Bartal (2011) ---see Section~\ref{sec:colours}.
% We have modified only the colour grey, which is now defined as {black!30}.
%
% \begin{macrocode}
@@ -2871,6 +3783,37 @@
%
%
%
+% \subsection{\hspace{3mm}The rubikfont}
+% \label{sec:coderubikfont}
+%
+% \begin{macro}{\@rubikfont}
+% \begin{macro}{\@rubikfontFNS}
+% \begin{macro}{\@rubikprime}
+% We define two fonts for text associated with the Rubik glyphs
+% (both the `arrow' glyphs and the `letter' glyphs),
+% namely, (1)~Computer Modern Sans (cmss), bold extended (bx), normal shape (n)
+% at 10/12pt, and (2)~a footnotesize (FNS) version (8pt) for the lower-case letters
+% [for cmss see Latex Companion (2004), p.\,417 \& p.\,354\,\footnote{Note the typo in Table~7.5 (p.\,354):
+% the font-series code for the Sans semi-bold condensed form is `sbx' (not sbc).}].
+% This has the effect of keeping the size
+% of Rubik glyphs constant in the face of any changes in the document fonts.
+% We make the baseline-skip values the same, since the `arrow' glyphs generated by
+% the \cmd{\Rubik} commands involve a single baseline-skip (for example, as with
+% \verb!\Rubik{D}!; see Section~\ref{sec:coderotationD}).
+% We use the cmss font apostrophe as the `prime' symbol (the user has
+% the opportunity to use the maths \cmd{\prime}
+% instead---see Section~\ref{sec:rubikprime}).
+%\begin{macrocode}
+\newcommand{\@rubikfont}{\fontsize{10}{12pt}\usefont{T1}{cmss}{bx}{n}}
+\newcommand{\@rubikfontFNS}{\fontsize{8}{12pt}\usefont{T1}{cmss}{bx}{n}}
+\newcommand{\@rubikprime}{'}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
% \subsection{\hspace{3mm}ShowCube command}
% \label{sec:showcubecode}
%
@@ -2880,42 +3823,181 @@
% displays the cube inside a minipage, so that we can easily tailor the minipage
% width (|#1|) and also the TikZ scale factor (|#2|). The \cmd{\ShowCubeF} command
% places an fbox around the minipage so users can see the extent of any white space.
-% {\newline}\textsc{usage}: |\ShowCube{2cm}{0.5}{\DrawRubikCubeRU}|
+% {\newline}\textsc{usage}: |\ShowCube{2cm}{0.5}{\DrawRubikCubeRU}|
+%
+% February 2017 (RWDN): \ We first require a new length variable (which will become the minipage-width),
+% so we can add the length 1.6pt to it (this is the width of the TikZ ultra-thick line
+% which is used to draw the Rubik cubes).
+% In order for a width of an image made up of $x$~units to be equal
+% to $x \times (\mbox{scale-factor})$ we need to add an extra line-width
+% (i.e.,~to include the right-hand edge).
+% \begin{macrocode}
+\newlength{\@showcubewidth}%
+% \end{macrocode}
+% We can now build the two macros. We set the \cmd{\fboxsep} value to zero.
% \begin{macrocode}
\newcommand{\ShowCube}[3]{%
- \begin{minipage}{#1}%
+ \setlength{\fboxsep}{0cm}%
+ \setlength{\@showcubewidth}{#1}%
+ \advance\@showcubewidth by 1.6pt\relax%
+ \begin{minipage}{\the\@showcubewidth}%
\centering%
\begin{tikzpicture}[scale=#2]%
#3%
\end{tikzpicture}%
\end{minipage}%
-}
+}%
\newcommand{\ShowCubeF}[3]{%
- \fbox{%
- \begin{minipage}{#1}%
+ \setlength{\fboxsep}{0cm}%
+ \setlength{\fboxrule}{0.4pt}%
+ \setlength{\@showcubewidth}{#1}%
+ \advance\@showcubewidth by 1.6pt\relax%
+ \framebox{%
+ \begin{minipage}{\the\@showcubewidth}%
\centering%
\begin{tikzpicture}[scale=#2]%
#3%
\end{tikzpicture}%
\end{minipage}%
-}}
+}}%
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+% \subsection{\hspace{3mm}ShowSequence command}
+% \label{sec:codeshowsequence}
+%
+% \begin{macro}{\ShowSequence}
+% \begin{macro}{\ShowSequenceF}
+% \begin{macro}{\ShowSequencef}
+% The \cmd{\ShowSequence}\marg{separator}\marg{font-code}\marg{sequence} command
+% typesets a comma separated sequence of rotation commands.
+% (See Section~\ref{sec:showsequence}).
+% This command takes three mandatory arguments: the first is the separator (\verb!#1!),
+% the second is the font or style code (\verb!#2!), and third is a comma-separated
+% sequence of Rubik rotation commands (|#3|).
+%
+% This command requires the \texttt{forarray}
+% package---by Christian Schr\"{o}ppel---(for the \cmd{\ForEachX} command)
+% and the \texttt{ifthen} package---by David Carlisle---(for the \cmd{\ifthenelse} command).
+% These two packages are loaded at startup if not already loaded.
+% We first need to define two variables for use by the command; these are
+% derived from the \texttt{forarray} package.
+%
+% \begin{macrocode}
+\newcommand{\x}{\thislevelitem}
+\newcommand{\xcount}{\thislevelcount}
+% \end{macrocode}
+%
+% The \cmd{\ShowSequence} command typesets a sequence of elements, and places
+% an optional separator (|#1|) between them.
+% For each element of |#3| this command forms the construction |#2{element of #3}|.
+% For~example, if |#2 = \rr|, and an element of |#3| is D, then it forms |\rr{D}| etc.
+%
+% Note that in order to avoid placing a trailing comma after the final element,
+% we identify the first element (using |\xcount|) and then place a comma in front
+% all the remaining elements. This is because it is easy to identify the first element
+% of a sequence, but very difficult to identify the final element.
+%
+% We also create two fbox forms: the `F' form places an fbox about the whole output;
+% the `f' form places an fbox about each element in the output (these forms can be
+% helpful when checking white space.
+%
+% \noindent\textsc{usage}: |\ShowSequence{,}{\rr}{R,L,Up,Dp.....}|
+%
+% \begin{macrocode}
+\newcommand{\ShowSequence}[3]{%
+ \ForEachX{,}{%
+ \ifthenelse{\xcount=1}{#2{\x}}{#1#2{\x}}%
+ }{#3}%
+}%
+\newcommand{\ShowSequenceF}[3]{%
+\fbox{%
+ \ForEachX{,}{%
+ \ifthenelse{\xcount=1}{#2{\x}}{#1#2{\x}}%
+ }{#3}%
+}}%
+\newcommand{\ShowSequencef}[3]{%
+ \ForEachX{,}{%
+ \ifthenelse{\xcount=1}{\fbox{#2{\x}}}{#1{\fbox{#2{\x}}}}%
+ }{#3}%
+}%
% \end{macrocode}
+% \begin{macro}{\SequenceInfo}
+% \begin{macro}{\SequenceName}
+% \begin{macro}{\SequenceShort}
+% \begin{macro}{\SequenceLong}
+% \noindent\textsc{Sequence holders}: providing none of the Rubik rotation-codes has a trailing
+% integer (e.g.,~R3) then the Rubik macros (|\rr|, |\rrh|, |\Rubik|, |\textRubik|) will work
+% as expected when used as the second argument in the \cmd{\ShowSequence} command
+% (described above). However, a problem arises when trying to process in this way any Rubik
+% rotation-codes having a terminal integer (for example, short-codes e.g.,~R2, D3,...), since the
+% \cmd{\ShowSequence} macro cannot expand short-codes into their long-code
+% elements (e.g.,~~R,R,D,D,D,...).
+%
+% Accommodating such codes when using the \cmd{\ShowSequence} command is currently
+% solved by using separate `holders' for four derived strings, namely: \cmd{\SequenceInfo},
+% \cmd{\SequenceName},\cmd{\SequenceShort} and \cmd{\SequenceLong}
+% (for details see Section~\ref{sec:showsequence}).
+% These are generated automatically by the Perl \textsc{rubikrotation} program, which returns
+% a so-called `long' version of the `short' string (the argument of the \cmd{\RubikRotation}
+% command). For~example, the Perl program converts
+% any short codes (e.g.,~R2, D3,... ) $\rightarrow$ long form, e.g.,~R,R,D,D,D,...
+% (see the \textsc{rubikrotation} documentation for details).
+% In order for the four `holders' of these derived strings generated by the Perl program
+% (written to the file \texttt{rubikstateNEW.dat}) to be accessible to the user they need to
+% defined here so that they can then be `redefined' (by the Perl program) in the file
+% \texttt{rubikstateNEW.dat}:
+% \begin{macrocode}
+\newcommand{\SequenceInfo}{{}}% %% INFO only
+\newcommand{\SequenceName}{{}}% %% NAME only
+\newcommand{\SequenceShort}{{}}% %% original SHORT seq but with NO NAME
+\newcommand{\SequenceLong}{{}}% %% just the LONG string \& no name
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
% \end{macro}
% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsection{\hspace{3mm}SequenceBrace commands}
+% \label{sec:sequencebracecode}
%
+% \begin{macro}{\SequenceBraceA}
+% \begin{macro}{\SequenceBraceB}
+% The \cmd{\SequenceBraceX}\marg{name}\marg{sequence} command
+% is a tool for displaying a named sequence using a brace. The trailing~A
+% denotes that the brace is placed Above the sequence; B~denotes the brace is Below the sequence.
+% For usage see Section~\ref{sec:sequencebrace}.
+%
+% \begin{macrocode}
+\newcommand{\SequenceBraceA}[2]{$\overbrace{\mbox{#2}}^{\mbox{#1}}$}%
+\newcommand{\SequenceBraceB}[2]{$\underbrace{\mbox{#2}}_{\mbox{#1}}$}%
+\newcommand{\SequenceBraceAF}[2]{\fbox{$\overbrace{\mbox{#2}}^{\mbox{#1}}$}}%
+\newcommand{\SequenceBraceBF}[2]{\fbox{$\underbrace{\mbox{#2}}_{\mbox{#1}}$}}%
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
%
%
% \subsection{\hspace{3mm}Face commands}
%
-% Cube face notation = U, D, L, R, F, B (Singmaster)
-% {\newline}Cubie-square notation = t, m, b, l, m, r = top, middle,
+% Cube face notation: U, D, L, R, F, B (Singmaster)
+% {\newline}Cubie-square notation: t, m, b, l, m, r = top, middle,
% bottom, left, middle, right.
-% We use t,b for cubie-squares (facelets) to avoid confusion with cube Face notation.
+% We use the t, b notation for cubie-squares (facelets) to avoid confusion with cube Face notation.
% We number the cubie-squares on a face 1--9 reading from left-to-right,
% starting top-left, ending bottom-right, as follows
% (see also Figure~\ref{fig:facenotation}):
% {\newline}\strut\hspace{1cm}top row \ \ \ \ \ (1,2,3) = tl, tm, tr
-% {\newline}\strut\hspace{1cm}middle row (4,5,6) = ml, mm, mr
+% {\newline}\strut\hspace{1cm}middle row\, (4,5,6) = ml, mm, mr
% {\newline}\strut\hspace{1cm}bottom row (7,8,9) = bl, bm, br
%
% \begin{macro}{\RubikFaceUp}
@@ -2936,12 +4018,12 @@
% Each letter is an initial letter of the words Up, Down, Left, Right, Front, Back,
% left, middle, right, top, middle, bottom.
%
-% For example, in the command \cmd{\Urt\{\#1\}}
+% For~example, in the command \cmd{\Urt\{\#1\}}
% the U stands for the Up face of the cube, while the \texttt{rt} stands
% for the ``right-top'' facelet on this face. Note that the order
-% of the two lowercase letters (in this case \texttt{rt}) are always written
-% in the $x,y$ order; i.e.,~the first of the two lowercase letters relates to the $x$
-% direction (either left, middle, or right), while the second lowercase letter
+% of the two lower-case letters (in this case \texttt{rt}) are always written
+% in the $x,y$ order; i.e.,~the first of the two lower-case letters relates to the $x$
+% direction (either left, middle, or right), while the second lower-case letter
% relates to the $y$ direction (either top, middle, or bottom)---this rule makes it
% easy to remember the order.
% \end{macro}
@@ -2989,9 +4071,11 @@
% \begin{macro}{\RubikFaceRightAll}
% \begin{macro}{\RubikFaceFrontAll}
% \begin{macro}{\RubikFaceBackAll}
-% These 5 commands allocate the same colour to all 9 cubiesquares in the specified face (Up, Down, Left, Right, Front). Each command therefore takes only 1 argument (one of the colour codes).
+% These 5 commands allocate the same colour to all 9 cubie-squares
+% in the specified face (Up, Down, Left, Right, Front).
+% Each command therefore takes only 1~argument (one of the colour codes).
%
-% {\noindent}For example, \cmd{\RubikFaceUpAll\{R\}}
+% {\noindent}For~example, \cmd{\RubikFaceUpAll\{R\}}
% \end{macro}
% \end{macro}
% \end{macro}
@@ -3031,7 +4115,8 @@
}
% \end{macrocode}
%
-% {\noindent}We now use these commands to initialise all visible faces to default colour grey (X)
+% {\noindent}Finally, we now use these commands to initialise all
+% visible faces to the default colour grey~(X)
%
% \begin{macrocode}
\RubikFaceUpAll{X}%
@@ -3051,7 +4136,9 @@
% \begin{macro}{\RubikCubeGrey}
% This command sets the face/colour configuration (state) of a 3x3x3
% Rubik cube with no colours allocated except for the central cubie of each face.
-% These central colours match those defined for the RubikCubeSolved command.
+% The colour configuration of the central cubies matches those defined for
+% the RubikCubeSolved command (i.e.,~white opposite yellow etc).
+% We also implement an equivalent `gray' version (to be consistent with TikZ).
% \begin{macrocode}
\newcommand{\RubikCubeGrey}{%
\RubikFaceUp {X}{X}{X}{X}{W}{X}{X}{X}{X}%
@@ -3061,29 +4148,73 @@
\RubikFaceFront{X}{X}{X}{X}{O}{X}{X}{X}{X}%
\RubikFaceBack {X}{X}{X}{X}{R}{X}{X}{X}{X}%
}
+\newcommand{\RubikCubeGray}{\RubikCubeGrey}
% \end{macrocode}
% \end{macro}
%
%
-% \subsection{\hspace{3mm}RubikCubeSolved command}
%
-% \begin{macro}{\RubikCubeSolved}
+%
+% \subsection{\hspace{3mm}SolvedConfig command}
+%
+% \begin{macro}{\SolvedConfig}
% This command sets the face/colour configuration (state) of a typical
-% solved Rubik cube.
+% solved Rubik cube. Note that the order is Right, Left, Up, Down, Front, Back
+% (i.e.,~X$+$, X$-$, Y$+$, Y$-$, Z$+$, Z$-$, order).
+% We shall use this command to define solved cube configurations.
% \begin{macrocode}
-\newcommand{\RubikCubeSolved}{%
- \RubikFaceUpAll{W}%
- \RubikFaceDownAll{Y}%
- \RubikFaceLeftAll{B}%
- \RubikFaceRightAll{G}%
- \RubikFaceFrontAll{O}%
- \RubikFaceBackAll{R}%
+\newcommand{\SolvedConfig}[6]{%
+ \RubikFaceRightAll{#1}%
+ \RubikFaceLeftAll{#2}%
+ \RubikFaceUpAll{#3}%
+ \RubikFaceDownAll{#4}%
+ \RubikFaceFrontAll{#5}%
+ \RubikFaceBackAll{#6}%
}
% \end{macrocode}
% \end{macro}
%
%
%
+%
+% \subsection{\hspace{3mm}RubikCubeGreyAll command}
+% \label{sec:codegreyall}
+%
+% \begin{macro}{\RubikCubeGreyAll}
+% This command sets the face/colour configuration (state) of a 3x3x3
+% Rubik cube with no colours allocated.
+% This colour configuration is the same as the startup default state---all cubies will
+% appear grey. We implement it using the \cmd{\SolvedConfig} command (above).
+% We also implement an equivalent `gray' version (to be consistent with TikZ).
+% \begin{macrocode}
+\newcommand{\RubikCubeGreyAll}{\SolvedConfig{X}{X}{X}{X}{X}{X}}%
+\newcommand{\RubikCubeGrayAll}{\RubikCubeGreyAll}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{\hspace{3mm}RubikCubeSolved command}
+% \label{sec:codesolvedconfig}
+%
+% \begin{macro}{\RubikCubeSolved}
+% \begin{macro}{\RubikCubeSolvedWY}
+% \begin{macro}{\RubikCubeSolvedWB}
+% The first (default) command sets the face/colour configuration (state) one of the standard
+% commercially available solved Rubik cube (white opposite yellow). The argument order
+% follows the XYZ notation. For convenience we make a copy named \cmd{\RubikCubeSolvedWY}
+% (denoting the White opposite Yellow configuration), and also a different version named
+% \cmd{\RubikCubeSolvedWB} (denoting the White opposite Blue configuration).
+% These represent the two standard versions of the Rubik Cube.
+% \begin{macrocode}
+\newcommand{\RubikCubeSolved}{\SolvedConfig{G}{B}{W}{Y}{O}{R}}%
+\newcommand{\RubikCubeSolvedWY}{\RubikCubeSolved}%
+\newcommand{\RubikCubeSolvedWB}{\SolvedConfig{R}{O}{W}{B}{G}{Y}}%
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
% \subsection{\hspace{3mm}Slice commands}
%
% \begin{macro}{\RubikSliceTopR}
@@ -3148,7 +4279,7 @@
% and \TeX\ has only 9 macro parameters available, we are forced to draw
% Rubik cubes by first specifying the colours on each of the three faces,
% and then using a `DrawRubikCubeXY' command, where the trailing XY code
-% defines the view direction (X = either R, L; Y = either U, D).
+% defines the viewing direction (X = either R or L; Y = either U or D).
% The order of the XY code is important: X~first, Y~second (so it is easy to remember).
%
% On each face the facelets are drawn in the following order: Top row
@@ -3158,7 +4289,7 @@
% through the four corners of the facelet in the following order:
% lb $\rightarrow$ lt $\rightarrow$ rt $\rightarrow$ rb; the code being
% lb (LeftBottom), lt (LeftTop), rt (RightTop), rb (RightBottom)
-% (only need four coords); the grid origin is at the bottom-left corner of the
+% (only need four coords); the (x,y) grid origin is at the bottom-left corner of the
% \textsc{front} face.
%
% \begin{macro}{\DrawRubikCubeFrontFace}
@@ -3197,7 +4328,7 @@
% \subsubsection{\hspace{3mm}Viewing direction}
%
% The command `DrawRubikCubeXY' command uses the trailing XY code
-% to specify the view direction (X = either R, L; Y = either U, D).
+% to specify the view direction (X = either R or L; Y = either U or D).
% The order of the XY code is important: X~first, Y~second (so it is easy
% to remember).
%
@@ -3209,7 +4340,8 @@
% The colours are allocated to particular facelets using the \cmd{\RubikFaceUp},
% \cmd{\RubikFaceRight} and \cmd{\RubikFaceFront} commands.
%
-% The (x,y) grid origin is at the bottom-left corner of the \textsc{front} face.
+% The (x,y) grid origin is at the bottom-left corner of the \textsc{front} face
+% (see Section~\ref{sec:coordinates}).
% The perspective is designed so that the 2D~graphic image of the side face
% (\textsc{right} in this particular case) has its `horizontal' lines running
% at 45~degrees. This has the useful advantage that the 2D~width of the side is
@@ -3450,9 +4582,10 @@
% These two LayerFace commands each draw and paint a single
% face of 9~facelets. The first command takes 9 ordered colour parameters,
% (ordered in layers from top left to bottom right, so \texttt{\#1}
-% is the placeholder for the colour of the TopLeft facelet etc.)
-% The second takes only one colour parameter (since \texttt{All} the
+% is the place-holder for the colour of the TopLeft facelet etc.)
+% The second command takes only one colour parameter (since \texttt{All} the
% colours are the same).
+%
% The drawing origin (0,0) = bottom left corner. The facelets are drawn
% from left to right.
% NOTE: this macro is SAME as the internal command
@@ -3517,8 +4650,12 @@
%
% [\textsc{note}: These new commands (version 3.0) were modified from the
% earlier \cmd{\FlatUp}, \cmd{\FlatDown} etc., commands; i.e.,~they were
-% reformulated as a set of \cmd{\Draw...} commands to make them consistent
-% with all the other \cmd{\Draw..} commands].
+% reformulated as a set of \cmd{\Draw...} commands so as to make this
+% notation consistent with the other \cmd{\Draw..} commands.
+% Note also that, for user convenience, all of these commands have
+% been copied (in version~4.0) to equivalent \cmd{\DrawFace..}
+% versions associated with their two coordinate arguments
+% set to $x=0$, $y=0$---see Section~\ref{sec:drawfacecode}]
%
% \begin{macro}{\DrawFlatUp}
% \begin{macro}{\DrawFlatDown}
@@ -3526,11 +4663,13 @@
% \begin{macro}{\DrawFlatRight}
% \begin{macro}{\DrawFlatFront}
% \begin{macro}{\DrawFlatBack}
-% Each of these commands draws a separate (flat) face (9~facelets).
+% Each of these commands draws a separate (flat) face (9~facelets)
+% (see Section~\ref{sec:flatcommands}).
% Each command (except \cmd{\DrawFlatFront}) takes two arguments,
% namely the X-coordinate and Y-coordinate of the bottom-left
% corner of the face. This (X,Y) pair of coordinates therefore allows
-% the user to position the face. These commands were motivated by a need to
+% the user to position the face in relation to the cube itself.
+% These commands were motivated by a need to
% be able to show hidden faces under certain circumstances.
%
% Note that the Y-argument currently only works fully
@@ -3553,9 +4692,9 @@
% of a Rubik cube.
%
% The (x,y) variables are here encoded as (\cmd{\ux}, \cmd{\uy}) where the
-% `u' stands for Up etc. However, since we are unable to use `dx, dy' with the
-% \cmd{\DrawFlatDown} command (since dx and dy are already used in the
-% \cmd{\cube@dxdydz...} command) we encode these instead as (\cmd{\ddx}, \cmd{\ddy}).
+% `u' stands for Up etc. However, since we are unable to use a `dx, dy' notation
+% with the \cmd{\DrawFlatDown} command (since dx and dy are already used by the
+% \cmd{\cube@dxdydz...} command), we encode these instead as (\cmd{\ddx}, \cmd{\ddy}).
%
% \end{macro}
% \end{macro}
@@ -3689,7 +4828,7 @@
}
%%-----------------------
\newcommand{\DrawFlatFront}{%
-%% This command is used /only/ by the \cmd{\DrawRubikFlat} command.
+%% This command is used /only/ by the \cmd{\DrawRubikCubeF} command.
%% NOTE: x, y variables not implemented as not required here
%%---top row
\draw[line join=round,line cap=round,ultra thick,fill=\Flt]%
@@ -3756,12 +4895,12 @@
}
% \end{macrocode}
%
-% \begin{macro}{\DrawRubikFlat}
-% Draws a standard flat representation of the Rubik
-% cube (colours only). Note that \cmd{\DrawFlatFront} does not
-% take any arguments (x,y) arguments.
+% \begin{macro}{\DrawRubikCubeF}
+% Draws a standard flat (F) representation of the Rubik
+% cube (colours only). Note that \cmd{\DrawFlatFront} (below)
+% does not take any arguments (x,y).
% \begin{macrocode}
-\newcommand{\DrawRubikFlat}{%
+\newcommand{\DrawRubikCubeF}{%
\DrawFlatUp{0}{3}%
\DrawFlatDown{0}{-3}%
\DrawFlatLeft{-3}{0}%
@@ -3772,12 +4911,13 @@
% \end{macrocode}
% \end{macro}
%
-% \begin{macro}{\DrawRubikCubeFlat}
+%
+% \begin{macro}{\DrawRubikCubeSF}
% Draws a Rubik cube together with the three hidden faces
-% (colours only) in a semi-flat representation. The (x,y)
-% arguments are for the bottom-left corner of the face.
+% (colours only) in a semi-flat (SF) representation. The (x,y)
+% arguments (below) are for the bottom-left corner of the face.
% \begin{macrocode}
-\newcommand{\DrawRubikCubeFlat}{%
+\newcommand{\DrawRubikCubeSF}{%
\DrawRubikCube%
\DrawFlatDown{0}{-3}%
\DrawFlatLeft{-3}{0}%
@@ -3789,6 +4929,7 @@
%
%
% \subsubsection{DrawFlatXSide commands}
+% \label{sec:drawflatxsidecode}
%
% These six commands draw a face together with all four sidebars
% (colours only). We use the \cmd{\DrawFlatX} commands to draw the face.
@@ -3798,7 +4939,10 @@
% Top (T) and Bottom (B) = left to right;
% Left (L) and Right (R) = top to bottom;
% (see the \cmd{\DrawRubikLayerSideX} command for details of the arguments).
-%
+%
+% Note that for user convenience, we we have copied many of these commands
+% to a \cmd{\DrawFace..} version (see Section~\ref{sec:drawfacecode}).
+%
%
% \begin{macro}{\DrawFlatUpSide}
% Draws the \textsc{up} face together with all four sidebars
@@ -3891,6 +5035,31 @@
%
%
%
+% \subsection{\hspace{3mm}DrawFace commands}
+% \label{sec:drawfacecode}
+%
+% We now copy the above \cmd{\DrawFlat..} commands
+% as \cmd{\DrawFace..} commands for the purpose of user
+% convenience, since most of the time the user wants just to
+% draw a particular face with or without the associated side bars.
+% In a future version we may well, therefore, deprecate some of the above
+% `Flat' command names.
+% \begin{macrocode}
+\newcommand{\DrawFaceUp}{\DrawFlatUp{0}{0}}
+\newcommand{\DrawFaceDown}{\DrawFlatDown{0}{0}}
+\newcommand{\DrawFaceLeft}{\DrawFlatLeft{0}{0}}
+\newcommand{\DrawFaceRight}{\DrawFlatRight{0}{0}}
+\newcommand{\DrawFaceFront}{\DrawFlatFront{0}{0}}
+\newcommand{\DrawFaceBack}{\DrawFlatBack{0}{0}}
+\newcommand{\DrawFaceUpSide}{\DrawFlatUpSide}
+\newcommand{\DrawFaceDownSide}{\DrawFlatDownSide}
+\newcommand{\DrawFaceLeftSide}{\DrawFlatLeftSide}
+\newcommand{\DrawFaceRightSide}{\DrawFlatRightSide}
+\newcommand{\DrawFaceFrontSide}{\DrawFlatFrontSide}
+\newcommand{\DrawFaceBackSide}{\DrawFlatBackSide}
+% \end{macrocode}
+%
+%
% \subsection{\hspace{3mm}SideBar commands}
%
% SideBar commands draw narrow bars of colour indicating the
@@ -3949,7 +5118,7 @@
% Note that the TikZ \cmd{\pgfmathsetmacro} commands (which do the maths)
% must be inside the TeX sidebar command in order to work.
% The start point of the TikZ \cmd{\draw} command for each bar rectangle
-% is botton Left corner of the bar =(\cmd{\dx},\cmd{\dy})
+% is bottom Left corner of the bar =(\cmd{\dx},\cmd{\dy})
% \end{macro}
% \end{macro}
% \end{macro}
@@ -3999,15 +5168,15 @@
% Right, Top, Middle, Bottom, x, y, as follows:
% \begin{quote}
% X$_1$ is an $x$ parameter: either $\langle L\mid M \mid R\rangle$
-% {\newline}X$_2$ is an $y$ parameter: either $\langle T\mid M \mid B\rangle$
+% {\newline}X$_2$ is a \, $y$ parameter: either $\langle T\mid M \mid B\rangle$
% {\newline}X$_3$ is an extra parameter: either $\langle x\mid y \rangle$,
% required by corner sidebars to indicate whether the sidebar was either
% above or below $\langle y \rangle$, or to the left or
% right $\langle x \rangle$ of the associated cubie.
% An $X_3$ parameter is not required for the sidebar of an edge cubie, since
-% only one location is posible in these cases.
+% only one location is possible in these cases.
% \end{quote}
-% For example, the following command
+% For~example, the following command
% \begin{quote}
% \cmd{\DrawRubikLayerSideLTy\{G\}}
% \end{quote}
@@ -4038,7 +5207,7 @@
% \end{macrocode}
%
%
-% \subsubsection{\hspace{3mm}Drawing multiple cubie sidebars}
+% \subsubsection{\hspace{3mm}Drawing multiple cubie sidebars}
%
% \begin{macro}{\DrawRubikLayerSideT}
% \begin{macro}{\DrawRubikLayerSideB}
@@ -4107,6 +5276,65 @@
% \end{macro}
%
%
+% \subsection{\hspace{3mm}RubikSide commands}
+% \label{sec:rubiksidecode}
+%
+% \begin{macro}{\RubikSideLeft}
+% \begin{macro}{\RubikSideRight}
+% \begin{macro}{\RubikSideFront}
+% \begin{macro}{\RubikSideBack}
+% RubikSide commands allocate colours to the side facelets of the
+% UP~face---see Section~\ref{sec:rubikside}.
+% These facelets are the top three facelets of each side Front, Back, Left, Right.
+% \begin{macrocode}
+\newcommand{\RubikSideFront}[3]{%
+\def\Flt{#1}\def\Fmt{#2}\def\Frt{#3}%
+}
+\newcommand{\RubikSideRight}[3]{%
+\def\Rlt{#1}\def\Rmt{#2}\def\Rrt{#3}%
+}
+\newcommand{\RubikSideLeft}[3]{%
+\def\Llt{#1}\def\Lmt{#2}\def\Lrt{#3}%
+}
+\newcommand{\RubikSideBack}[3]{%
+\def\Blt{#1}\def\Bmt{#2}\def\Brt{#3}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\RubikSideLeftAll}
+% \begin{macro}{\RubikSideRightAll}
+% \begin{macro}{\RubikSideFrontAll}
+% \begin{macro}{\RubikSideBackAll}
+% These 4 commands allocate the same colour to all 3 cubiesquares in the specified face
+% (Left, Right, Front, Back). Each command therefore takes only 1 argument
+% (one of the colour codes).
+%
+% {\noindent}For~example, \cmd{\RubikSideUpAll\{R\}}
+% \begin{macrocode}
+\newcommand{\RubikSideFrontAll}[1]{%
+\def\Flt{#1}\def\Fmt{#1}\def\Frt{#1}%
+}
+\newcommand{\RubikSideRightAll}[1]{%
+\def\Rlt{#1}\def\Rmt{#1}\def\Rrt{#1}%
+}
+\newcommand{\RubikSideLeftAll}[1]{%
+\def\Llt{#1}\def\Lmt{#1}\def\Lrt{#1}%
+}
+\newcommand{\RubikSideBackAll}[1]{%
+\def\Blt{#1}\def\Bmt{#1}\def\Brt{#1}%
+}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
%
% \subsection{\hspace{3mm}NCube command}
%
@@ -4123,7 +5351,7 @@
% The command takes four ordered arguments, as follows:
% \begin{quote}
% \#1 = number of cubies ($n>0$) along each side,
-% {\newline}\#2, \#3, \#4 = colors of the visible faces (in X,Y,Z order);
+% {\newline}\#2, \#3, \#4 = colours of the visible faces (in X,Y,Z order);
% X=Right face colour, Y=Up face colour, Z=Front face colour.
% \end{quote}
% We use the \cmd{\pgfmathsetmacro}\marg{variable-name}\marg{numeric value or maths}
@@ -4144,10 +5372,11 @@
% \end{macro}
%
% \begin{macro}{\cube@dxdydz}
-% This internal command is used only by the \cmd{\DrawNCubeAll} command.
-% The original version of this command was developed by Peter Bartal (see Bartal, 2011).
-% It was modified (2012) by RWD Nickalls (to implement a more
-% intuitive X, Y, Z ordering of parameters).
+% This internal command is used only by the \cmd{\DrawNCubeAll} command
+% (see above). The original version of this command was developed
+% by Peter Bartal (see Bartal, 2011).
+% It was later modified (2012) by RWD Nickalls (to implement a more
+% intuitive X, Y, Z ordering of the face colour parameters).
%
% The cube need not be in the origin, the distances of
% the \textsc{down}-behind [L] corner from
@@ -4175,7 +5404,7 @@
% options to each of the TikZ \cmd{\draw} commands, in order to improve
% the line joining (first two options); (2) adjusted the \cmd{\cube@dxdydz} macro
% to adopt the ordered XYZ face colour notation
-% (by reassigning \#2, \#3, \#4).
+% (by reassigning \#2, \#3, \#4 to the X, Y, Z face colours, as shown above).
%
% \begin{macrocode}
\newcommand{\cube@dxdydz}[7]{%
@@ -4192,7 +5421,7 @@
\draw[line join=round,line cap=round,ultra thick,fill=#4]%
(#5,#6,\dz) -- (\dx,#6,\dz) -- (\dx,\dy,\dz) -- (#5,\dy,\dz) -- cycle;
%% The 'rectangle' command does not work with 3D coordinates,
-%% so this is the way to draw the squres with space coordinates
+%% so this is the way to draw the squares with space coordinates
%% Draw UP face (using the Y colour = #3)
\draw[line join=round,line cap=round,ultra thick,fill=#3]%
(#5,\dy,\dz) -- (\dx,\dy,\dz) -- (\dx,\dy,#7) -- (#5,\dy,#7) -- cycle;
@@ -4214,10 +5443,10 @@
% (adjust \texttt{cy}) and horizontal viewpoint (adjust \texttt{cx})
% of a single cubie (described in more detail in the \rubikcube\
% package documentation).
-% Note that we cannot use the names \texttt{dx}, \texttt{dy} for variables since
-% these have been allocated already (see above). However, we do use
-% \texttt{dx}, \texttt{dy} in the command names as these will be more
-% readily understood by the user.
+% Note that we cannot use the names \texttt{dx}, \texttt{dy} for the
+% variables here since these names have been allocated already
+% (see above). However, we can use \texttt{dx}, \texttt{dy} in the
+% command names as these will be more readily understood by the user.
% \begin{macrocode}
\newcommand{\Cubiedx}[1]{\pgfmathsetmacro{\cx}{#1}}
\newcommand{\Cubiedy}[1]{\pgfmathsetmacro{\cy}{#1}}
@@ -4307,8 +5536,8 @@
%
% As before, the viewpoint is specified using an appended
% two-letter XY ordered viewpoint code: either RU, RD, LU, LD.
-% These commands take three arguments, namely three different XYZ
-% ordered colour codes (R,O,Y,G,B,W,X).
+% These commands take three arguments (since just three faces are visible with this
+% cube format), namely three different XYZ ordered colour codes (R,O,Y,G,B,W,X).
% \newline\textsc{format}: \cmd{\textCubieRU}\marg{Xcolour}\marg{Ycolour}\marg{Zcolour}
% \newline\textsc{usage}: |\textCubieRU{G}{B}{W}|
% \end{macro}
@@ -4361,27 +5590,50 @@
%
% \subsubsection{\hspace{3mm}Introduction}
%
-% We use a special prefix notation to denote each of four different repreresentations
-% of the various Rubik cube rotations as follows: the name of the rotation (rr), its
+% We use a special prefix notation to denote each of four different representations
+% of the various Rubik cube rotations as follows: the name of the Rubik rotation (rr), its
% associated hieroglyph (rrh), and combinations of name and hieroglyph both vertical (Rubik)
% and horizontal (textRubik). A rotation command is a combination of a rotation-code appended
% to one of the four prefixes.
%
-% For example, the command \cmd{\rrhD} generates the hieroglyph (rrh) associated with
+% For~example, the command \cmd{\rrhD} generates the hieroglyph (rrh) associated with
% the rotation-code D. In this form it is used internally, but it is also available for the user.
-% However, it is also made available to the user in the more intuitive form
-% |\rrh{D}| by the use of the internal macro |\@join| (see Sections~\ref{sec:cmdsusingjoin}
-% and \ref{sec:usefulinternalcommands}).
+%
+% In version~3.0, however, all the rotation commands were also made available to the user
+% in the much more intuitive form stem\{argument\} form, for~example,
+% |\rrh{D}|. In practice, this `argument' form actually generates the original non-argument
+% form by the use of the internal macro |\@join|.
+% For example, \verb!\rrh{D}! $\rightarrow$ join(\verb!\rrh! + \verb!D!) $\rightarrow$ \verb!\rrhD!
+% (see Sections~\ref{sec:cmdsusingjoin} for details).
%
-% The square hieroglyphs are built up in stages. We first create an internal
-% command for drawing the square (\cmd{\DrawNotationBox}), and then draw the
-% contents (lines, arrows, arcs of circles, and sometimes just text).
-% (for the TikZ ARC command see TikZ pgfmanual (2012) page~146 (\S 14.8)).
+% The hieroglyphs are of two types: `arrow' glyphs (all exactly square),
+% and `letter' glyphs (mostly square, but many are rectangular); however both
+% types are made to have the same height so they sit nicely when arranged side-by-side.
+% A lot of special macros for handling and generating these glyphs are described below
+% in Section~\ref{sec:usefulinternalcommands} (and also in Section~\ref{sec:codedrawnotationbox}).
+%
+% The `arrow' hieroglyphs are built up in stages using TikZ. We first create a
+% command for drawing the square (\cmd{\DrawNotationBox};
+% see Section~\ref{sec:codedrawnotationbox}) and then draw the
+% contents (lines, arrows, arcs of circles). For an example,
+% see the D~form \rrh{D}\ constructed in Section~\ref{sec:coderotationD}.
+%
+% The `letter' hieroglyphs (glyphs for which the rotations cannot be seen from the front,
+% and hence cannot have arrows) just give a letter representation of the rotation
+% (say, Bw for `back wide'). These glyphs are therefore made using an fbox (for convenience),
+% and therefore these are sometimes not square. Some vertical fine-tuning using
+% the \verb!\raisebox! command is often required to force these `letter' glyphs to
+% have the same vertical position as their `arrow' cousins. For an example,
+% see the form \rrh{Bw}\ constructed Section~\ref{sec:coderotationBw}).
%
% The presence of small overfilled \cmd{\hbox}es associated with these squares
% were originally checked using the \texttt{ltugboat.cls}, and all fixed mainly
% by setting the associated minipages $\rightarrow$ width = 0.6cm,
% and using TikZ scale=0.5.
+%
+%
+% \subsubsection{\hspace{3mm}DrawNotationBox}
+% \label{sec:codedrawnotationbox}
%
%
% \begin{macro}{\DrawNotationBox}
@@ -4389,7 +5641,7 @@
% Note that we start at (0,0) and draw to the final point
% in order to make a nice corner join.
%
-% TODO: ? make this a proper internal command
+% todo: ? make this a proper internal command
% using \verb!@! sometime.
%
% \begin{macrocode}
@@ -4403,10 +5655,11 @@
% (e.g.,~\cmd{\@sd}, \cmd{\@sh} \ldots\ etc.) which will be required
% for use in drawing the various lines and arrows.
% Some hieroglyphs contain either one circular arc, or two concentric arcs,
-% and these arcs require both a center and a start point.
+% and these arcs require both a centre and a start point.
% Note that the final argument does not use any units.
+% For the TikZ ARC command see TikZ pgfmanual (2012) page~146 (\S 14.8).
%
-% TODO: make a small diagram to illustrate the position of these
+% todo: make a small diagram to illustrate the position of these
% parameters and make things a bit clearer sometime.
%
%\begin{macrocode}
@@ -4422,23 +5675,148 @@
\pgfmathsetmacro{\@sqcy}{\@scy+0.25} %% SQuare CenterY cpprd
% \end{macrocode}
%
-% All the \verb!@! internal commands used in the following commands
-% and macros are described in Section~\ref{sec:usefulinternalcommands}.
%
%
%
-% \subsubsection{\hspace{3mm}Using {\textbackslash}\texttt{join}}
+% \subsubsection{\hspace{3mm}Some useful internal commands}
+% \label{sec:usefulinternalcommands}
+%
+% \begin{macro}{\@rr}
+% \begin{macro}{\@rrp}
+% \begin{macro}{\@rrw}
+% \begin{macro}{\@rrwp}
+% \begin{macro}{\@rrs}
+% \begin{macro}{\@rrsp}
+% \begin{macro}{\@rra}
+% \begin{macro}{\@rrap}
+% \begin{macro}{\@xyzh}
+% \begin{macro}{\@xyzhp}
+% \begin{macro}{\@xyzRubik}
+% \begin{macro}{\@xyzRubikp}
+% \begin{macro}{\@SquareLetter}
+% \begin{macro}{\@hRubik}
+% These internal commands are used to generate the
+% prime, w, w-prime, s, s-prime, a, a-prime
+% rotation commands. The \cmd{\@xyz..} commands are used to generate the
+% x, y, z, u, d, l, r, f, b commands and their associated prime rotation commands.
+% The \cmd{\@SquareLetter} command is used to form the separate square hieroglyph form
+% used for rotations with no visible representation from the front
+% (e.g.,~B.., Fs, Fsp, Fa, Fap, S, Sp, Sf, Sfp, Sb, Sbp).
+% The \cmd{\@hRubik} is the vertical shift used to raise the box carrying the rotation
+% rotation-code in \cmd{\Rubik..} commands not visible from the front.
+%
+% The commands \verb!\@xyzhbdfl! and \verb!\@xyzbdflRubik! relate to the
+% axis rotations denoted as b, d, f, l; since these four letters have long upstrokes
+% they require special fine-tuning for vertical position.
+%
+% The idea is that by using these internal
+% tools taking parameters we are able to more easily standardise the size
+% and position of all the various glyphs. For details of the
+% rubikfont and rubikprime see Section~\ref{sec:coderubikfont}).
+%
+% Note that the TikZ `thick' line code = 0.8pt (used in \cmd{\@SquareLetter}).
+%
+% \begin{macrocode}
+\newcommand{\@rr}[1]{{\@rubikfont #1}}
+\newcommand{\@rrp}[1]{{\@rubikfont #1\@rubikprime}}
+\newcommand{\@rrw}[1]{{\@rubikfont #1{\@rubikfontFNS w}}}
+\newcommand{\@rrwp}[1]{{\@rubikfont #1{\@rubikfontFNS w}\@rubikprime}}
+\newcommand{\@rrs}[1]{{\@rubikfont #1{\@rubikfontFNS s}}}
+\newcommand{\@rrsp}[1]{{\@rubikfont #1{\@rubikfontFNS s}\@rubikprime}}
+\newcommand{\@rra}[1]{{\@rubikfont #1{\@rubikfontFNS a}}}
+\newcommand{\@rrap}[1]{{\@rubikfont #1{\@rubikfontFNS a}\@rubikprime}}
+\newcommand{\@rru}[1]{{\@rubikfont #1{\@rubikfontFNS u}}}
+\newcommand{\@rrup}[1]{{\@rubikfont #1{\@rubikfontFNS u}\@rubikprime}}
+\newcommand{\@rrd}[1]{{\@rubikfont #1{\@rubikfontFNS d}}}
+\newcommand{\@rrdp}[1]{{\@rubikfont #1{\@rubikfontFNS d}\@rubikprime}}
+\newcommand{\@rrl}[1]{{\@rubikfont #1{\@rubikfontFNS l}}}
+\newcommand{\@rrlp}[1]{{\@rubikfont #1{\@rubikfontFNS l}\@rubikprime}}
+\newcommand{\@rrr}[1]{{\@rubikfont #1{\@rubikfontFNS r}}}
+\newcommand{\@rrrp}[1]{{\@rubikfont #1{\@rubikfontFNS r}\@rubikprime}}
+\newcommand{\@rrf}[1]{{\@rubikfont #1{\@rubikfontFNS f}}}
+\newcommand{\@rrfp}[1]{{\@rubikfont #1{\@rubikfontFNS f}\@rubikprime}}
+\newcommand{\@rrb}[1]{{\@rubikfont #1{\@rubikfontFNS b}}}
+\newcommand{\@rrbp}[1]{{\@rubikfont #1{\@rubikfontFNS b}\@rubikprime}}
+\newcommand{\@rrc}[1]{{\@rubikfont #1{\@rubikfontFNS c}}}
+\newcommand{\@rrcp}[1]{{\@rubikfont #1{\@rubikfontFNS c}\@rubikprime}}
+\newcommand{\@rrm}[1]{{\@rubikfont #1{\@rubikfontFNS m}}}
+\newcommand{\@rrmp}[1]{{\@rubikfont #1{\@rubikfontFNS m}\@rubikprime}}
+\newcommand{\@xyzh}[1]{[{\@rubikfont #1}]}
+\newcommand{\@xyzhp}[1]{[{\@rubikfont #1\@rubikprime}]}
+\newcommand{\@xyzRubik}[1]{\raisebox{3.45pt}{[{\@rubikfont #1}]}}
+\newcommand{\@xyzRubikp}[1]{\raisebox{3.45pt}{[{\@rubikfont #1\@rubikprime}]}}
+\newcommand{\@xyzhbdfl}[1]{[\raisebox{-0.6pt}{{\@rubikfont #1}}]}
+\newcommand{\@xyzbdflRubik}[1]{\raisebox{3.45pt}{[\raisebox{-0.6pt}{{\@rubikfont #1}}]}}
+\newcommand{\@SquareLetter}[1]{\setlength{\fboxsep}{2.5pt}%
+ \setlength{\fboxrule}{0.8pt}%
+ \fbox{\rule[-1pt]{0pt}{8.5pt}\raisebox{-0.5pt}{#1}}}
+\newlength\@hRubik%
+\setlength{\@hRubik}{0.185cm}%
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@tlen}
+% Feb 2017 (RWDN): \ We also need to define a small length for fine-tuning the default
+% horizontal space between a pair of `letter' hieroglyphs, eg~B (i.e.,~when no
+% additional space has been added by the user), so that this matches that between a pair of
+% `arrow' hieroglyphs. This length is inserted on both sides of the square frame.
+% This length is used in two settings: (a)~in `letter' hieroglyphs (for an example,
+% see the definition of the macro \cmd{\SquareB} in Section~\ref{sec:coderotationB}),
+% and in (b)~in `arrow' hieroglyphs (for an example,
+% see the definition of the macro \cmd{\rrhD} in Section~\ref{sec:coderotationD}).
+%
+%\begin{macrocode}
+\newcommand{\@tlen}{\hspace{1pt}}%
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@join}
+% We also require a macro for joining two strings so we can convert
+% a rotation-code, say U, into a macro which typesets it in some form, say \cmd{\rrhU}.
+% The following \cmd{\@join\{\}\{\}} command is by Christian Tellechea (many thanks\,!).
+% {\newline}\textsc{usage}: \cmd{\@join\marg{command-stem}\marg{rotation-code}}. For~example,
+% to create the command \cmd{\rrhU} we would write |\@join{\rrh}{U}|, and hence
+% the command |\rrh{U}| is equivalent to \cmd{\rrhU} (see Section~\ref{sec:cmdsusingjoin}).
+% {\newline}Since this macro is also useful for processing rotation-codes in a list,
+% which may also include macros, it is important that |#2| is not detokenized.
+% \begin{macrocode}
+\newcommand*\@join[2]{%
+ \csname\expandafter\@gobble\string#1#2\endcsname}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+%
+% \subsubsection{\hspace{3mm}Using {\textbackslash}\texttt{@join}}
% \label{sec:cmdsusingjoin}
%
% \begin{macro}{\textRubik}
% \begin{macro}{\Rubik}
% \begin{macro}{\rr}
% \begin{macro}{\rrh}
-% The following four commands typeset a single rotation, where the rotation-code (eg~U) is
+% The following four commands typeset a single rotation, where the rotation-code (e.g.,~U) is
% the argument (see Section~\ref{sec:overview}). As an example, the format for
% the \cmd{\rrh\{\}} command is
% \cmd{\rrh}\marg{rotation-code}. In practice, these four commands are really a
-% sort of front-end for all the commands which follow this section. For example, the
+% sort of front-end for all the commands which follow this section. For~example, the
% command \cmd{\rrh\{U\}} generates the command \cmd{\rrhU} which itself typesets the
% rotation hieroglyph for the rotation~U, etc.
%
@@ -4461,6 +5839,7 @@
%
%
% \subsubsection{\hspace{3mm}Rotation B}
+% \label{sec:coderotationB}
%
% \begin{macro}{\rrB}
% \begin{macro}{\SquareB}
@@ -4469,12 +5848,20 @@
% \begin{macro}{\textRubikB}
% These commands all draw forms which denote the B (\textsc{back}-face) rotation.
% Not visible from the front.
+%
+% Feb 2017 (RWDN): added the \cmd{\@tlen} length (= 1pt; defined above) to the
+% \cmd{\SquareB} command, and removed the terminal \cmd{\,} space
+% from the rrhB, RubikB, textRubikB commands, and copied
+% this action with all the subsequent Letter hieroglyphs (e.g.,~B, Bw,..).
+% These minor changes were to improve the spacing between two Letter hieroglyphs,
+% and make it match that between two square `arrow' hieroglyphs.
+% The same changes were made to all the `letter' hieroglyphs.
% \begin{macrocode}
\newcommand{\rrB}{\@rr{B}}
-\newcommand{\SquareB}{\@SquareLetter{\rrB}}
-\newcommand{\rrhB}{\raisebox{-0.25mm}{\SquareB}\,}
-\newcommand{\RubikB}{\raisebox{\@hRubik}{\SquareB}\,}
-\newcommand{\textRubikB}{\rrhB\,}
+\newcommand{\SquareB}{\@tlen\@SquareLetter{\rrB}\@tlen}
+\newcommand{\rrhB}{\raisebox{-0.25mm}{\SquareB}}
+\newcommand{\RubikB}{\raisebox{\@hRubik}{\SquareB}}
+\newcommand{\textRubikB}{\rrhB}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4494,10 +5881,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrBp}{\@rrp{B}}
-\newcommand{\SquareBp}{\@SquareLetter{\rrBp}}
-\newcommand{\rrhBp}{\raisebox{-0.25mm}{\SquareBp}\,}
-\newcommand{\RubikBp}{\raisebox{\@hRubik}{\SquareBp}\,}
-\newcommand{\textRubikBp}{\rrhBp\,}
+\newcommand{\SquareBp}{\@tlen\@SquareLetter{\rrBp}\@tlen}
+\newcommand{\rrhBp}{\raisebox{-0.25mm}{\SquareBp}}
+\newcommand{\RubikBp}{\raisebox{\@hRubik}{\SquareBp}}
+\newcommand{\textRubikBp}{\rrhBp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4507,6 +5894,7 @@
%
%
% \subsubsection{\hspace{3mm}Rotation Bw}
+% \label{sec:coderotationBw}
%
% \begin{macro}{\rrBw}
% \begin{macro}{\SquareBw}
@@ -4516,12 +5904,11 @@
% These commands all draw forms which denote the Bw rotation.
% Not visible from the front.
% \begin{macrocode}
-%\newcommand{\rrBw}{\textbf{\textsf{Bw}}}
\newcommand{\rrBw}{\@rrw{B}}
-\newcommand{\SquareBw}{\@SquareLetter{\rrBw}}
-\newcommand{\rrhBw}{\raisebox{-0.25mm}{\SquareBw}\,}
-\newcommand{\RubikBw}{\raisebox{\@hRubik}{\SquareBw}\,}
-\newcommand{\textRubikBw}{\rrhBw\,}
+\newcommand{\SquareBw}{\@tlen\@SquareLetter{\rrBw}\@tlen}
+\newcommand{\rrhBw}{\raisebox{-0.25mm}{\SquareBw}}
+\newcommand{\RubikBw}{\raisebox{\@hRubik}{\SquareBw}}
+\newcommand{\textRubikBw}{\rrhBw}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4540,12 +5927,11 @@
% These commands all draw forms which denote the Bwp rotation.
% Not visible from the front.
% \begin{macrocode}
-%\newcommand{\rrBwp}{\textbf{\textsf{Bwp}}}
\newcommand{\rrBwp}{\@rrwp{B}}
-\newcommand{\SquareBwp}{\@SquareLetter{\rrBwp}}
-\newcommand{\rrhBwp}{\raisebox{-0.25mm}{\SquareBwp}\,}
-\newcommand{\RubikBwp}{\raisebox{\@hRubik}{\SquareBwp}\,}
-\newcommand{\textRubikBwp}{\rrhBwp\,}
+\newcommand{\SquareBwp}{\@tlen\@SquareLetter{\rrBwp}\@tlen}
+\newcommand{\rrhBwp}{\raisebox{-0.25mm}{\SquareBwp}}
+\newcommand{\RubikBwp}{\raisebox{\@hRubik}{\SquareBwp}}
+\newcommand{\textRubikBwp}{\rrhBwp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4564,12 +5950,11 @@
% These commands all draw forms which denote the Bs rotation.
% Not visible from the front.
% \begin{macrocode}
-%\newcommand{\rrBs}{\textbf{\textsf{Bs}}}
\newcommand{\rrBs}{\@rrs{B}}
-\newcommand{\SquareBs}{\@SquareLetter{\rrBs}}
-\newcommand{\rrhBs}{\raisebox{-0.25mm}{\SquareBs}\,}
-\newcommand{\RubikBs}{\raisebox{\@hRubik}{\SquareBs}\,}
-\newcommand{\textRubikBs}{\rrhBs\,}
+\newcommand{\SquareBs}{\@tlen\@SquareLetter{\rrBs}\@tlen}
+\newcommand{\rrhBs}{\raisebox{-0.25mm}{\SquareBs}}
+\newcommand{\RubikBs}{\raisebox{\@hRubik}{\SquareBs}}
+\newcommand{\textRubikBs}{\rrhBs}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4588,12 +5973,11 @@
% These commands all draw forms which denote the Bsp rotation.
% Not visible from the front.
% \begin{macrocode}
-%\newcommand{\rrBsp}{\textbf{\textsf{Bsp}}}
\newcommand{\rrBsp}{\@rrsp{B}}
-\newcommand{\SquareBsp}{\@SquareLetter{\rrBsp}}
-\newcommand{\rrhBsp}{\raisebox{-0.25mm}{\SquareBsp}\,}
-\newcommand{\RubikBsp}{\raisebox{\@hRubik}{\SquareBsp}\,}
-\newcommand{\textRubikBsp}{\rrhBsp\,}
+\newcommand{\SquareBsp}{\@tlen\@SquareLetter{\rrBsp}\@tlen}
+\newcommand{\rrhBsp}{\raisebox{-0.25mm}{\SquareBsp}}
+\newcommand{\RubikBsp}{\raisebox{\@hRubik}{\SquareBsp}}
+\newcommand{\textRubikBsp}{\rrhBsp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4612,12 +5996,11 @@
% These commands all draw forms which denote the Ba rotation.
% Not visible from the front.
% \begin{macrocode}
-%\newcommand{\rrBa}{\textbf{\textsf{Ba}}}
\newcommand{\rrBa}{\@rra{B}}
-\newcommand{\SquareBa}{\@SquareLetter{\rrBa}}
-\newcommand{\rrhBa}{\raisebox{-0.25mm}{\SquareBa}\,}
-\newcommand{\RubikBa}{\raisebox{\@hRubik}{\SquareBa}\,}
-\newcommand{\textRubikBa}{\rrhBa\,}
+\newcommand{\SquareBa}{\@tlen\@SquareLetter{\rrBa}\@tlen}
+\newcommand{\rrhBa}{\raisebox{-0.25mm}{\SquareBa}}
+\newcommand{\RubikBa}{\raisebox{\@hRubik}{\SquareBa}}
+\newcommand{\textRubikBa}{\rrhBa}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4636,12 +6019,11 @@
% These commands all draw forms which denote the Bap rotation.
% Not visible from the front.
% \begin{macrocode}
-%\newcommand{\rrBap}{\textbf{\textsf{Bap}}}
\newcommand{\rrBap}{\@rrap{B}}
-\newcommand{\SquareBap}{\@SquareLetter{\rrBap}}
-\newcommand{\rrhBap}{\raisebox{-0.25mm}{\SquareBap}\,}
-\newcommand{\RubikBap}{\raisebox{\@hRubik}{\SquareBap}\,}
-\newcommand{\textRubikBap}{\rrhBap\,}
+\newcommand{\SquareBap}{\@tlen\@SquareLetter{\rrBap}\@tlen}
+\newcommand{\rrhBap}{\raisebox{-0.25mm}{\SquareBap}}
+\newcommand{\RubikBap}{\raisebox{\@hRubik}{\SquareBap}}
+\newcommand{\textRubikBap}{\rrhBap}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -4651,6 +6033,7 @@
%
%
% \subsubsection{\hspace{3mm}Rotation D}
+% \label{sec:coderotationD}
%
% \begin{macro}{\rrD}
% \begin{macro}{\SquareD}
@@ -4658,8 +6041,12 @@
% \begin{macro}{\RubikD}
% \begin{macro}{\textRubikD}
% These commands all draw forms which denote the D rotation.
+%
+% Feb 2017 (RWDN): \ added the \cmd{\@tlen} length to the \cmd{\rrhD} command to improve the
+% spacing between two `arrow' square hieroglyphs; and also removed the terminal \cmd{\,}
+% space. The same changes were made to all the `arrow' hieroglyphs.
% \begin{macrocode}
-\newcommand{\rrD}{\textbf{\textsf{D}}}
+\newcommand{\rrD}{\@rr{D}}
%%
\newcommand{\SquareD}{%
\begin{tikzpicture}[scale=0.5]
@@ -4669,15 +6056,16 @@
\draw [thick, ->] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhD}{\raisebox{-0.333\height}{\SquareD}\,}
+\newcommand{\rrhD}{\raisebox{-0.333\height}{\@tlen\SquareD\@tlen}}
%%
\newcommand{\RubikD}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareD\\
-\rrD
+\rrD%
\end{minipage}%
-}
+}}
\newcommand{\textRubikD}{\rrD\,\rrhD}
% \end{macrocode}
% \end{macro}
@@ -4696,7 +6084,7 @@
% \begin{macro}{\textRubikDp}
% These commands all draw forms which denote the Dp rotation.
% \begin{macrocode}
-\newcommand{\rrDp}{\textbf{\textsf{D}$^\prime$}}
+\newcommand{\rrDp}{\@rrp{D}}
%%
\newcommand{\SquareDp}{%
\begin{tikzpicture}[scale=0.5]
@@ -4706,15 +6094,16 @@
\draw [thick, <-] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDp}{\raisebox{-0.333\height}{\SquareDp}\,}
+\newcommand{\rrhDp}{\raisebox{-0.333\height}{\@tlen\SquareDp\@tlen}}
%%
\newcommand{\RubikDp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDp\\
-\rrDp
+\rrDp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDp}{\rrDp\,\rrhDp}
% \end{macrocode}
% \end{macro}
@@ -4733,7 +6122,7 @@
% \begin{macro}{\textRubikDw}
% These commands all draw forms which denote the Dw rotation.
% \begin{macrocode}
-\newcommand{\rrDw}{\textbf{\textsf{D\footnotesize{w}}}}
+\newcommand{\rrDw}{\@rrw{D}}
%%
\newcommand{\SquareDw}{%
\begin{tikzpicture}[scale=0.5]
@@ -4743,15 +6132,16 @@
\draw [thick, ->] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDw}{\raisebox{-0.333\height}{\SquareDw}\,}
+\newcommand{\rrhDw}{\raisebox{-0.333\height}{\@tlen\SquareDw\@tlen}}
%%
\newcommand{\RubikDw}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDw\\
-\rrDw
+\rrDw%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDw}{\rrDw\,\rrhDw}
% \end{macrocode}
% \end{macro}
@@ -4770,7 +6160,7 @@
% \begin{macro}{\textRubikDwp}
% These commands all draw forms which denote the Dwp rotation.
% \begin{macrocode}
-\newcommand{\rrDwp}{\textbf{\textsf{D\footnotesize{w}}$^\prime$}}
+\newcommand{\rrDwp}{\@rrwp{D}}
%%
\newcommand{\SquareDwp}{%
\begin{tikzpicture}[scale=0.5]
@@ -4780,15 +6170,16 @@
\draw [thick, <-] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDwp}{\raisebox{-0.333\height}{\SquareDwp}\,}
+\newcommand{\rrhDwp}{\raisebox{-0.333\height}{\@tlen\SquareDwp\@tlen}}
%%
\newcommand{\RubikDwp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDwp\\
-\rrDwp
+\rrDwp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDwp}{\rrDwp\,\rrhDwp}
% \end{macrocode}
% \end{macro}
@@ -4817,15 +6208,16 @@
\draw [thick, ->] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDs}{\raisebox{-0.333\height}{\SquareDs}\,}
+\newcommand{\rrhDs}{\raisebox{-0.333\height}{\@tlen\SquareDs\@tlen}}
%%
\newcommand{\RubikDs}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDs\\
-\rrDs
+\rrDs%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDs}{\rrDs\,\rrhDs}
% \end{macrocode}
% \end{macro}
@@ -4854,15 +6246,16 @@
\draw [thick, <-] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDsp}{\raisebox{-0.333\height}{\SquareDsp}\,}
+\newcommand{\rrhDsp}{\raisebox{-0.333\height}{\@tlen\SquareDsp\@tlen}}
%%
\newcommand{\RubikDsp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDsp\\
-\rrDsp
+\rrDsp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDsp}{\rrDsp\,\rrhDsp}
% \end{macrocode}
% \end{macro}
@@ -4891,15 +6284,16 @@
\draw [thick, ->] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDa}{\raisebox{-0.333\height}{\SquareDa}\,}
+\newcommand{\rrhDa}{\raisebox{-0.333\height}{\@tlen\SquareDa\@tlen}}
%%
\newcommand{\RubikDa}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDa\\
-\rrDa
+\rrDa%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDa}{\rrDa\,\rrhDa}
% \end{macrocode}
% \end{macro}
@@ -4928,15 +6322,16 @@
\draw [thick, <-] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhDap}{\raisebox{-0.333\height}{\SquareDap}\,}
+\newcommand{\rrhDap}{\raisebox{-0.333\height}{\@tlen\SquareDap\@tlen}}
%%
\newcommand{\RubikDap}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareDap\\
-\rrDap
+\rrDap%
\end{minipage}%
-}
+}}
\newcommand{\textRubikDap}{\rrDap\,\rrhDap}
% \end{macrocode}
% \end{macro}
@@ -4955,7 +6350,7 @@
% \begin{macro}{\textRubikE}
% These commands all draw forms which denote the E rotation.
% \begin{macrocode}
-\newcommand{\rrE}{\textbf{\textsf{E}}}
+\newcommand{\rrE}{\@rr{E}}
%%
\newcommand{\SquareE}{%
\begin{tikzpicture}[scale=0.5]
@@ -4965,15 +6360,16 @@
\draw [thick] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhE}{\raisebox{-0.333\height}{\SquareE}\,}
+\newcommand{\rrhE}{\raisebox{-0.333\height}{\@tlen\SquareE\@tlen}}
%%
\newcommand{\RubikE}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareE\\
-\rrE
+\rrE%
\end{minipage}%
-}
+}}
\newcommand{\textRubikE}{\rrE\,\rrhE}
% \end{macrocode}
% \end{macro}
@@ -4992,7 +6388,7 @@
% \begin{macro}{\textRubikEp}
% These commands all draw forms which denote the Ep rotation.
% \begin{macrocode}
-\newcommand{\rrEp}{\textbf{\textsf{E}$^\prime$}}
+\newcommand{\rrEp}{\@rrp{E}}
%%
\newcommand{\SquareEp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5002,15 +6398,16 @@
\draw [thick] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhEp}{\raisebox{-0.333\height}{\SquareEp}\,}
+\newcommand{\rrhEp}{\raisebox{-0.333\height}{\@tlen\SquareEp\@tlen}}
%%
\newcommand{\RubikEp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareEp\\
-\rrEp
+\rrEp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikEp}{\rrEp\,\rrhEp}
% \end{macrocode}
% \end{macro}
@@ -5029,7 +6426,7 @@
% \begin{macro}{\textRubikF}
% These commands all draw forms which denote the F rotation.
% \begin{macrocode}
-\newcommand{\rrF}{\textbf{\textsf{F}}}
+\newcommand{\rrF}{\@rr{F}}
%%
\newcommand{\SquareF}{%
\begin{tikzpicture}[scale=0.5]
@@ -5037,15 +6434,16 @@
\draw [thick, <-] (\@scx, \@scy) arc[radius=0.35, start angle=-60, delta angle=290];
\end{tikzpicture}%
}
-\newcommand{\rrhF}{\raisebox{-0.333\height}{\SquareF}\,}
+\newcommand{\rrhF}{\raisebox{-0.333\height}{\@tlen\SquareF\@tlen}}
%%
\newcommand{\RubikF}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareF\\
-\rrF
+\rrF%
\end{minipage}%
-}
+}}
\newcommand{\textRubikF}{\rrF\,\rrhF}
% \end{macrocode}
% \end{macro}
@@ -5064,7 +6462,7 @@
% \begin{macro}{\textRubikFp}
% These commands all draw forms which denote the Fp rotation.
% \begin{macrocode}
-\newcommand{\rrFp}{\textbf{\textsf{F}$^\prime$}}
+\newcommand{\rrFp}{\@rrp{F}}
%%
\newcommand{\SquareFp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5072,15 +6470,16 @@
\draw [thick, ->] (\@scx, \@scy) arc[radius=0.35, start angle=-60, delta angle=290];
\end{tikzpicture}%
}
-\newcommand{\rrhFp}{\raisebox{-0.333\height}{\SquareFp}\,}
+\newcommand{\rrhFp}{\raisebox{-0.333\height}{\@tlen\SquareFp\@tlen}}
%%
\newcommand{\RubikFp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareFp\\
-\rrFp
+\rrFp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikFp}{\rrFp\,\rrhFp}
% \end{macrocode}
% \end{macro}
@@ -5099,7 +6498,7 @@
% \begin{macro}{\textRubikFw}
% These commands all draw forms which denote the Fw rotation.
% \begin{macrocode}
-\newcommand{\rrFw}{\textbf{\textsf{F\footnotesize{w}}}}
+\newcommand{\rrFw}{\@rrw{F}}
%%
\newcommand{\SquareFw}{%
\begin{tikzpicture}[scale=0.5]
@@ -5109,15 +6508,16 @@
%\node (squareLab) at (0.5,0.5) {$o$};
\end{tikzpicture}%
}
-\newcommand{\rrhFw}{\raisebox{-0.333\height}{\SquareFw}\,}
+\newcommand{\rrhFw}{\raisebox{-0.333\height}{\@tlen\SquareFw\@tlen}}
%%
\newcommand{\RubikFw}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareFw\\
-\rrFw
+\rrFw%
\end{minipage}%
-}
+}}
\newcommand{\textRubikFw}{\rrFw\,\rrhFw}
% \end{macrocode}
% \end{macro}
@@ -5136,7 +6536,7 @@
% \begin{macro}{\textRubikFwp}
% These commands all draw forms which denote the Fwp rotation.
% \begin{macrocode}
-\newcommand{\rrFwp}{\textbf{\textsf{F\footnotesize{w}}$^\prime$}}
+\newcommand{\rrFwp}{\@rrwp{F}}
%%
\newcommand{\SquareFwp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5145,15 +6545,16 @@
\draw [thick] (\@sqcx,\@sqcy) arc[radius=0.1, start angle=-60, delta angle=360];
\end{tikzpicture}%
}
-\newcommand{\rrhFwp}{\raisebox{-0.333\height}{\SquareFwp}\,}
+\newcommand{\rrhFwp}{\raisebox{-0.333\height}{\@tlen\SquareFwp\@tlen}}
%%
\newcommand{\RubikFwp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareFwp\\
-\rrFwp
+\rrFwp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikFwp}{\rrFwp\,\rrhFwp}
%%
% \end{macrocode}
@@ -5179,10 +6580,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrFs}{\@rrs{F}}
-\newcommand{\SquareFs}{\@SquareLetter{\rrFs}}
-\newcommand{\rrhFs}{\raisebox{-0.25mm}{\SquareFs}\,}
-\newcommand{\RubikFs}{\raisebox{\@hRubik}{\SquareFs}\,}
-\newcommand{\textRubikFs}{\rrhFs\,}
+\newcommand{\SquareFs}{\@tlen\@SquareLetter{\rrFs}\@tlen}
+\newcommand{\rrhFs}{\raisebox{-0.25mm}{\SquareFs}}
+\newcommand{\RubikFs}{\raisebox{\@hRubik}{\SquareFs}}
+\newcommand{\textRubikFs}{\rrhFs}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5205,10 +6606,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrFsp}{\@rrsp{F}}
-\newcommand{\SquareFsp}{\@SquareLetter{\rrFsp}}
-\newcommand{\rrhFsp}{\raisebox{-0.25mm}{\SquareFsp}\,}
-\newcommand{\RubikFsp}{\raisebox{\@hRubik}{\SquareFsp}\,}
-\newcommand{\textRubikFsp}{\rrhFsp\,}
+\newcommand{\SquareFsp}{\@tlen\@SquareLetter{\rrFsp}\@tlen}
+\newcommand{\rrhFsp}{\raisebox{-0.25mm}{\SquareFsp}}
+\newcommand{\RubikFsp}{\raisebox{\@hRubik}{\SquareFsp}}
+\newcommand{\textRubikFsp}{\rrhFsp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5231,10 +6632,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrFa}{\@rra{F}}
-\newcommand{\SquareFa}{\@SquareLetter{\rrFa}}
-\newcommand{\rrhFa}{\raisebox{-0.25mm}{\SquareFa}\,}
-\newcommand{\RubikFa}{\raisebox{\@hRubik}{\SquareFa}\,}
-\newcommand{\textRubikFa}{\rrhFa\,}
+\newcommand{\SquareFa}{\@tlen\@SquareLetter{\rrFa}\@tlen}
+\newcommand{\rrhFa}{\raisebox{-0.25mm}{\SquareFa}}
+\newcommand{\RubikFa}{\raisebox{\@hRubik}{\SquareFa}}
+\newcommand{\textRubikFa}{\rrhFa}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5257,10 +6658,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrFap}{\@rrap{F}}
-\newcommand{\SquareFap}{\@SquareLetter{\rrFap}}
-\newcommand{\rrhFap}{\raisebox{-0.25mm}{\SquareFap}\,}
-\newcommand{\RubikFap}{\raisebox{\@hRubik}{\SquareFap}\,}
-\newcommand{\textRubikFap}{\rrhFap\,}
+\newcommand{\SquareFap}{\@tlen\@SquareLetter{\rrFap}\@tlen}
+\newcommand{\rrhFap}{\raisebox{-0.25mm}{\SquareFap}}
+\newcommand{\RubikFap}{\raisebox{\@hRubik}{\SquareFap}}
+\newcommand{\textRubikFap}{\rrhFap}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5277,7 +6678,7 @@
% \begin{macro}{\textRubikL}
% These commands all draw forms which denote the L rotation.
% \begin{macrocode}
-\newcommand{\rrL}{\textbf{\textsf{L}}}
+\newcommand{\rrL}{\@rr{L}}
%%
\newcommand{\SquareL}{%
\begin{tikzpicture}[scale=0.5]
@@ -5287,15 +6688,16 @@
\draw [thick] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhL}{\raisebox{-0.333\height}{\SquareL}\,}
+\newcommand{\rrhL}{\raisebox{-0.333\height}{\@tlen\SquareL\@tlen}}
%%
\newcommand{\RubikL}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareL\\
-\rrL
+\rrL%
\end{minipage}%
-}
+}}
\newcommand{\textRubikL}{\rrL\,\rrhL}
% \end{macrocode}
% \end{macro}
@@ -5314,7 +6716,7 @@
% \begin{macro}{\textRubikLp}
% These commands all draw forms which denote the Lp rotation.
% \begin{macrocode}
-\newcommand{\rrLp}{\textbf{\textsf{L}$^\prime$}}
+\newcommand{\rrLp}{\@rrp{L}}
%%
\newcommand{\SquareLp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5324,15 +6726,16 @@
\draw [thick] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLp}{\raisebox{-0.333\height}{\SquareLp}\,}
+\newcommand{\rrhLp}{\raisebox{-0.333\height}{\@tlen\SquareLp\@tlen}}
%%
\newcommand{\RubikLp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLp\\
-\rrLp
+\rrLp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLp}{\rrLp\,\rrhLp}
% \end{macrocode}
% \end{macro}
@@ -5351,7 +6754,7 @@
% \begin{macro}{\textRubikLw}
% These commands all draw forms which denote the Lw rotation.
% \begin{macrocode}
-\newcommand{\rrLw}{\textbf{\textsf{L\footnotesize{w}}}}
+\newcommand{\rrLw}{\@rrw{L}}
%%
\newcommand{\SquareLw}{%
\begin{tikzpicture}[scale=0.5]
@@ -5361,15 +6764,16 @@
\draw [thick] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLw}{\raisebox{-0.333\height}{\SquareLw}\,}
+\newcommand{\rrhLw}{\raisebox{-0.333\height}{\@tlen\SquareLw\@tlen}}
%%
\newcommand{\RubikLw}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLw\\
-\rrLw
+\rrLw%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLw}{\rrLw\,\rrhLw}
% \end{macrocode}
% \end{macro}
@@ -5388,7 +6792,7 @@
% \begin{macro}{\textRubikLwp}
% These commands all draw forms which denote the Lwp rotation.
% \begin{macrocode}
-\newcommand{\rrLwp}{\textbf{\textsf{L\footnotesize{w}}$^\prime$}}
+\newcommand{\rrLwp}{\@rrwp{L}}
%%
\newcommand{\SquareLwp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5398,15 +6802,16 @@
\draw [thick] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLwp}{\raisebox{-0.333\height}{\SquareLwp}\,}
+\newcommand{\rrhLwp}{\raisebox{-0.333\height}{\@tlen\SquareLwp\@tlen}}
%%
\newcommand{\RubikLwp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLwp\\
-\rrLwp
+\rrLwp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLwp}{\rrLwp\,\rrhLwp}
% \end{macrocode}
% \end{macro}
@@ -5435,15 +6840,16 @@
\draw [thick, <-] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLs}{\raisebox{-0.333\height}{\SquareLs}\,}
+\newcommand{\rrhLs}{\raisebox{-0.333\height}{\@tlen\SquareLs\@tlen}}
%%
\newcommand{\RubikLs}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLs\\
-\rrLs
+\rrLs%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLs}{\rrLs\,\rrhLs}
% \end{macrocode}
% \end{macro}
@@ -5472,15 +6878,16 @@
\draw [thick, ->] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLsp}{\raisebox{-0.333\height}{\SquareLsp}\,}
+\newcommand{\rrhLsp}{\raisebox{-0.333\height}{\@tlen\SquareLsp\@tlen}}
%%
\newcommand{\RubikLsp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLsp\\
-\rrLsp
+\rrLsp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLsp}{\rrLsp\,\rrhLsp}
% \end{macrocode}
% \end{macro}
@@ -5509,15 +6916,16 @@
\draw [thick, ->] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLa}{\raisebox{-0.333\height}{\SquareLa}\,}
+\newcommand{\rrhLa}{\raisebox{-0.333\height}{\@tlen\SquareLa\@tlen}}
%%
\newcommand{\RubikLa}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLa\\
-\rrLa
+\rrLa%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLa}{\rrLa\,\rrhLa}
% \end{macrocode}
% \end{macro}
@@ -5546,15 +6954,16 @@
\draw [thick, <-] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhLap}{\raisebox{-0.333\height}{\SquareLap}\,}
+\newcommand{\rrhLap}{\raisebox{-0.333\height}{\@tlen\SquareLap\@tlen}}
%%
\newcommand{\RubikLap}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareLap\\
-\rrLap
+\rrLap%
\end{minipage}%
-}
+}}
\newcommand{\textRubikLap}{\rrLap\,\rrhLap}
% \end{macrocode}
% \end{macro}
@@ -5573,7 +6982,7 @@
% \begin{macro}{\textRubikM}
% These commands all draw forms which denote the M rotation.
% \begin{macrocode}
-\newcommand{\rrM}{\textbf{\textsf{M}}}
+\newcommand{\rrM}{\@rr{M}}
%%
\newcommand{\SquareM}{%
\begin{tikzpicture}[scale=0.5]
@@ -5583,15 +6992,16 @@
\draw [thick] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhM}{\raisebox{-0.333\height}{\SquareM}\,}
+\newcommand{\rrhM}{\raisebox{-0.333\height}{\@tlen\SquareM\@tlen}}
%%
\newcommand{\RubikM}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareM\\
-\rrM
+\rrM%
\end{minipage}%
-}
+}}
\newcommand{\textRubikM}{\rrM\,\rrhM}
% \end{macrocode}
% \end{macro}
@@ -5610,7 +7020,7 @@
% \begin{macro}{\textRubikMp}
% These commands all draw forms which denote the Mp rotation.
% \begin{macrocode}
-\newcommand{\rrMp}{\textbf{\textsf{M}$^\prime$}}
+\newcommand{\rrMp}{\@rrp{M}}
%%
\newcommand{\SquareMp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5620,15 +7030,16 @@
\draw [thick] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhMp}{\raisebox{-0.333\height}{\SquareMp}\,}
+\newcommand{\rrhMp}{\raisebox{-0.333\height}{\@tlen\SquareMp\@tlen}}
%%
\newcommand{\RubikMp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareMp\\
-\rrMp
+\rrMp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikMp}{\rrMp\,\rrhMp}
% \end{macrocode}
% \end{macro}
@@ -5647,7 +7058,7 @@
% \begin{macro}{\textRubikR}
% These commands all draw forms which denote the R rotation.
% \begin{macrocode}
-\newcommand{\rrR}{\textbf{\textsf{R}}}
+\newcommand{\rrR}{\@rr{R}}
%%
\newcommand{\SquareR}{%
\begin{tikzpicture}[scale=0.5]
@@ -5658,15 +7069,16 @@
\draw [thick, ->] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhR}{\raisebox{-0.333\height}{\SquareR}\,}
+\newcommand{\rrhR}{\raisebox{-0.333\height}{\@tlen\SquareR\@tlen}}
%%
\newcommand{\RubikR}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareR\\
-\rrR
+\rrR%
\end{minipage}%
-}
+}}
\newcommand{\textRubikR}{\rrR\,\rrhR}
% \end{macrocode}
% \end{macro}
@@ -5685,7 +7097,7 @@
% \begin{macro}{\textRubikRp}
% These commands all draw forms which denote the Rp rotation.
% \begin{macrocode}
-\newcommand{\rrRp}{\textbf{\textsf{R}$^\prime$}}
+\newcommand{\rrRp}{\@rrp{R}}
%%
\newcommand{\SquareRp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5695,15 +7107,16 @@
\draw [thick, <-] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRp}{\raisebox{-0.333\height}{\SquareRp}\,}
+\newcommand{\rrhRp}{\raisebox{-0.333\height}{\@tlen\SquareRp\@tlen}}
%%
\newcommand{\RubikRp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRp\\
-\rrRp
+\rrRp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRp}{\rrRp\,\rrhRp}
% \end{macrocode}
% \end{macro}
@@ -5722,7 +7135,7 @@
% \begin{macro}{\textRubikRw}
% These commands all draw forms which denote the Rw rotation.
% \begin{macrocode}
-\newcommand{\rrRw}{\textbf{\textsf{R\footnotesize{w}}}}
+\newcommand{\rrRw}{\@rrw{R}}
%%
\newcommand{\SquareRw}{%
\begin{tikzpicture}[scale=0.5]
@@ -5732,15 +7145,16 @@
\draw [thick, ->] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRw}{\raisebox{-0.333\height}{\SquareRw}\,}
+\newcommand{\rrhRw}{\raisebox{-0.333\height}{\@tlen\SquareRw\@tlen}}
%%
\newcommand{\RubikRw}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRw\\
-\rrRw
+\rrRw%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRw}{\rrRw\,\rrhRw}
% \end{macrocode}
% \end{macro}
@@ -5759,7 +7173,7 @@
% \begin{macro}{\textRubikRwp}
% These commands all draw forms which denote the Rwp rotation.
% \begin{macrocode}
-\newcommand{\rrRwp}{\textbf{\textsf{R\footnotesize{w}}$^\prime$}}
+\newcommand{\rrRwp}{\@rrwp{R}}
%%
\newcommand{\SquareRwp}{%
\begin{tikzpicture}[scale=0.5]
@@ -5769,15 +7183,16 @@
\draw [thick, <-] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRwp}{\raisebox{-0.333\height}{\SquareRwp}\,}
+\newcommand{\rrhRwp}{\raisebox{-0.333\height}{\@tlen\SquareRwp\@tlen}}
%%
\newcommand{\RubikRwp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRwp\\
-\rrRwp
+\rrRwp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRwp}{\rrRwp\,\rrhRwp}
% \end{macrocode}
% \end{macro}
@@ -5806,15 +7221,16 @@
\draw [thick,->] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRs}{\raisebox{-0.333\height}{\SquareRs}\,}
+\newcommand{\rrhRs}{\raisebox{-0.333\height}{\@tlen\SquareRs\@tlen}}
%%
\newcommand{\RubikRs}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRs\\
-\rrRs
+\rrRs%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRs}{\rrRs\,\rrhRs}
% \end{macrocode}
% \end{macro}
@@ -5843,15 +7259,16 @@
\draw [thick,<-] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRsp}{\raisebox{-0.333\height}{\SquareRsp}\,}
+\newcommand{\rrhRsp}{\raisebox{-0.333\height}{\@tlen\SquareRsp\@tlen}}
%%
\newcommand{\RubikRsp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRsp\\
-\rrRsp
+\rrRsp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRsp}{\rrRsp\,\rrhRsp}
% \end{macrocode}
% \end{macro}
@@ -5880,15 +7297,16 @@
\draw [thick,->] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRa}{\raisebox{-0.333\height}{\SquareRa}\,}
+\newcommand{\rrhRa}{\raisebox{-0.333\height}{\@tlen\SquareRa\@tlen}}
%%
\newcommand{\RubikRa}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRa\\
-\rrRa
+\rrRa%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRa}{\rrRa\,\rrhRa}
% \end{macrocode}
% \end{macro}
@@ -5917,15 +7335,16 @@
\draw [thick,<-] (\@sddd, \@sb) -- (\@sddd, \@sbh);
\end{tikzpicture}%
}
-\newcommand{\rrhRap}{\raisebox{-0.333\height}{\SquareRap}\,}
+\newcommand{\rrhRap}{\raisebox{-0.333\height}{\@tlen\SquareRap\@tlen}}
%%
\newcommand{\RubikRap}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareRap\\
-\rrRap
+\rrRap%
\end{minipage}%
-}
+}}
\newcommand{\textRubikRap}{\rrRap\,\rrhRap}
% \end{macrocode}
% \end{macro}
@@ -5946,10 +7365,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrS}{\@rr{S}}
-\newcommand{\SquareS}{\@SquareLetter{\rrS}}
-\newcommand{\rrhS}{\raisebox{-0.25mm}{\SquareS}\,}
-\newcommand{\RubikS}{\raisebox{\@hRubik}{\SquareS}\,}
-\newcommand{\textRubikS}{\rrhS\,}
+\newcommand{\SquareS}{\@tlen\@SquareLetter{\rrS}\@tlen}
+\newcommand{\rrhS}{\raisebox{-0.25mm}{\SquareS}}
+\newcommand{\RubikS}{\raisebox{\@hRubik}{\SquareS}}
+\newcommand{\textRubikS}{\rrhS}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5969,10 +7388,10 @@
% Not visible from the front.
% \begin{macrocode}
\newcommand{\rrSp}{\@rrp{S}}
-\newcommand{\SquareSp}{\@SquareLetter{\rrSp}}
-\newcommand{\rrhSp}{\raisebox{-0.25mm}{\SquareSp}\,}
-\newcommand{\RubikSp}{\raisebox{\@hRubik}{\SquareSp}\,}
-\newcommand{\textRubikSp}{\rrhSp\,}
+\newcommand{\SquareSp}{\@tlen\@SquareLetter{\rrSp}\@tlen}
+\newcommand{\rrhSp}{\raisebox{-0.25mm}{\SquareSp}}
+\newcommand{\RubikSp}{\raisebox{\@hRubik}{\SquareSp}}
+\newcommand{\textRubikSp}{\rrhSp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -5988,18 +7407,19 @@
% \begin{macro}{\RubikSu}
% \begin{macro}{\textRubikSu}
% These commands draw forms of the Singmaster Su slice rotation.
-% We also need to finetune the spacing
+% We also need to fine-tune the spacing
% between these `slice' hieroglyphs (especially Fs and Bs).
% \begin{macrocode}
-\newcommand{\rrSu}{\textbf{\textsf{S\footnotesize{u}}}}
+\newcommand{\rrSu}{\@rru{S}}
\newcommand{\rrhSu}{\rrhEp}%
\newcommand{\RubikSu}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareEp\\
-\rrSu
+\rrSu%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSu}{\rrSu\,\rrhEp}
% \end{macrocode}
% \end{macro}
@@ -6015,18 +7435,19 @@
% \begin{macro}{\RubikSup}
% \begin{macro}{\textRubikSup}
% These commands draw forms of the Singmaster Sup slice rotation.
-% We also need to finetune the spacing
+% We also need to fine-tune the spacing
% between these `slice' hieroglyphs (especially Fs and Bs).
% \begin{macrocode}
-\newcommand{\rrSup}{\textbf{\textsf{S\footnotesize{u}}$^\prime$}}
+\newcommand{\rrSup}{\@rrup{S}}
\newcommand{\rrhSup}{\rrhE}%
\newcommand{\RubikSup}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareE\\
-\rrSup
+\rrSup%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSup}{\rrSup\,\rrhE}
% \end{macrocode}
% \end{macro}
@@ -6043,15 +7464,16 @@
% \begin{macro}{\textRubikSd}
% These commands draw forms of the Singmaster Sd slice rotation.
% \begin{macrocode}
-\newcommand{\rrSd}{\textbf{\textsf{S\footnotesize{d}}}}
+\newcommand{\rrSd}{\@rrd{S}}
\newcommand{\rrhSd}{\rrhE}%
\newcommand{\RubikSd}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareE\\
-\rrSd
+\rrSd%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSd}{\rrSd\,\rrhE}
% \end{macrocode}
% \end{macro}
@@ -6068,15 +7490,16 @@
% \begin{macro}{\textRubikSdp}
% These commands draw forms of the Singmaster Sdp slice rotation.
% \begin{macrocode}
-\newcommand{\rrSdp}{\textbf{\textsf{S\footnotesize{d}}$^\prime$}}
+\newcommand{\rrSdp}{\@rrdp{S}}
\newcommand{\rrhSdp}{\rrhEp}%
\newcommand{\RubikSdp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareEp\\
-\rrSdp
+\rrSdp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSdp}{\rrSdp\,\rrhEp}
% \end{macrocode}
% \end{macro}
@@ -6093,15 +7516,16 @@
% \begin{macro}{\textRubikSl}
% These commands draw forms of the Singmaster Sl slice rotation.
% \begin{macrocode}
-\newcommand{\rrSl}{\textbf{\textsf{S\footnotesize{l}}}}
+\newcommand{\rrSl}{\@rrl{S}}
\newcommand{\rrhSl}{\rrhM}%
\newcommand{\RubikSl}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareM\\
-\rrSl
+\rrSl%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSl}{\rrSl\,\rrhM}
% \end{macrocode}
% \end{macro}
@@ -6118,15 +7542,16 @@
% \begin{macro}{\textRubikSlp}
% These commands draw forms of the Singmaster Slp slice rotation.
% \begin{macrocode}
-\newcommand{\rrSlp}{\textbf{\textsf{S\footnotesize{l}}$^\prime$}}
+\newcommand{\rrSlp}{\@rrlp{S}}
\newcommand{\rrhSlp}{\rrhMp}%
\newcommand{\RubikSlp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareMp\\
-\rrSlp
+\rrSlp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSlp}{\rrSlp\,\rrhMp}
% \end{macrocode}
% \end{macro}
@@ -6143,15 +7568,16 @@
% \begin{macro}{\textRubikSr}
% These commands draw forms of the Singmaster Sr slice rotation.
% \begin{macrocode}
-\newcommand{\rrSr}{\textbf{\textsf{S\footnotesize{r}}}}
+\newcommand{\rrSr}{\@rrr{S}}
\newcommand{\rrhSr}{\rrhMp}%
\newcommand{\RubikSr}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareMp\\
-\rrSr
+\rrSr%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSr}{\rrSr\,\rrhMp}
% \end{macrocode}
% \end{macro}
@@ -6168,15 +7594,16 @@
% \begin{macro}{\textRubikSrp}
% These commands draw forms of the Singmaster Srp slice rotation.
% \begin{macrocode}
-\newcommand{\rrSrp}{\textbf{\textsf{S\footnotesize{r}}$^\prime$}}
+\newcommand{\rrSrp}{\@rrrp{S}}
\newcommand{\rrhSrp}{\rrhM}%
\newcommand{\RubikSrp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareM\\
-\rrSrp
+\rrSrp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikSrp}{\rrSrp\,\rrhM}
% \end{macrocode}
% \end{macro}
@@ -6199,11 +7626,11 @@
% bounded by \{\} so no need to reset to defaults.
% Not visible from the front.
% \begin{macrocode}
-\newcommand{\rrSf}{\textbf{\textsf{S\footnotesize{f}}}}
-\newcommand{\SquareSf}{\@SquareLetter{\rrSf}}
-\newcommand{\rrhSf}{\raisebox{-0.25mm}{\SquareSf}\,}
-\newcommand{\RubikSf}{\raisebox{\@hRubik}{\SquareSf}\,}
-\newcommand{\textRubikSf}{\rrhSf\,}
+\newcommand{\rrSf}{\@rrf{S}}
+\newcommand{\SquareSf}{\@tlen\@SquareLetter{\rrSf}\@tlen}
+\newcommand{\rrhSf}{\raisebox{-0.25mm}{\SquareSf}}
+\newcommand{\RubikSf}{\raisebox{\@hRubik}{\SquareSf}}
+\newcommand{\textRubikSf}{\rrhSf}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6225,11 +7652,11 @@
% bounded by \{\} so no need to reset to defaults.
% Not visible from the front.
% \begin{macrocode}
-\newcommand{\rrSfp}{\textbf{\textsf{S\footnotesize{f}}$^\prime$}}
-\newcommand{\SquareSfp}{\@SquareLetter{\rrSfp}}
-\newcommand{\rrhSfp}{\raisebox{-0.25mm}{\SquareSfp}\,}
-\newcommand{\RubikSfp}{\raisebox{\@hRubik}{\SquareSfp}\,}
-\newcommand{\textRubikSfp}{\rrhSfp\,}
+\newcommand{\rrSfp}{\@rrfp{S}}
+\newcommand{\SquareSfp}{\@tlen\@SquareLetter{\rrSfp}\@tlen}
+\newcommand{\rrhSfp}{\raisebox{-0.25mm}{\SquareSfp}}
+\newcommand{\RubikSfp}{\raisebox{\@hRubik}{\SquareSfp}}
+\newcommand{\textRubikSfp}{\rrhSfp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6251,11 +7678,11 @@
% bounded by \{\} so no need to reset to defaults.
% Not visible from the front.
% \begin{macrocode}
-\newcommand{\rrSb}{\textbf{\textsf{S\footnotesize{b}}}}
-\newcommand{\SquareSb}{\@SquareLetter{\rrSb}}
-\newcommand{\rrhSb}{\raisebox{-0.25mm}{\SquareSb}\,}
-\newcommand{\RubikSb}{\raisebox{\@hRubik}{\SquareSb}\,}
-\newcommand{\textRubikSb}{\rrhSb\,}
+\newcommand{\rrSb}{\@rrb{S}}
+\newcommand{\SquareSb}{\@tlen\@SquareLetter{\rrSb}\@tlen}
+\newcommand{\rrhSb}{\raisebox{-0.25mm}{\SquareSb}}
+\newcommand{\RubikSb}{\raisebox{\@hRubik}{\SquareSb}}
+\newcommand{\textRubikSb}{\rrhSb}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6277,11 +7704,11 @@
% bounded by \{\} so no need to reset to defaults.
% Not visible from th front.
% \begin{macrocode}
-\newcommand{\rrSbp}{\textbf{\textsf{S\footnotesize{b}}$^\prime$}}
-\newcommand{\SquareSbp}{\@SquareLetter{\rrSbp}}
-\newcommand{\rrhSbp}{\raisebox{-0.25mm}{\SquareSbp}\,}
-\newcommand{\RubikSbp}{\raisebox{\@hRubik}{\SquareSbp}\,}
-\newcommand{\textRubikSbp}{\rrhSbp\,}
+\newcommand{\rrSbp}{\@rrbp{S}}
+\newcommand{\SquareSbp}{\@tlen\@SquareLetter{\rrSbp}\@tlen}
+\newcommand{\rrhSbp}{\raisebox{-0.25mm}{\SquareSbp}}
+\newcommand{\RubikSbp}{\raisebox{\@hRubik}{\SquareSbp}}
+\newcommand{\textRubikSbp}{\rrhSbp}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6298,7 +7725,7 @@
% \begin{macro}{\textRubikU}
% These commands all draw forms which denote the U rotation.
% \begin{macrocode}
-\newcommand{\rrU}{\textbf{\textsf{U}}}
+\newcommand{\rrU}{\@rr{U}}
%%
\newcommand{\SquareU}{%
\begin{tikzpicture}[scale=0.5]
@@ -6308,15 +7735,16 @@
\draw [thick] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhU}{\raisebox{-0.333\height}{\SquareU}\,}
+\newcommand{\rrhU}{\raisebox{-0.333\height}{\@tlen\SquareU\@tlen}}
%%
\newcommand{\RubikU}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareU\\
-\rrU
+\rrU%
\end{minipage}%%
-}
+}}
\newcommand{\textRubikU}{\rrU\,\rrhU}
% \end{macrocode}
% \end{macro}
@@ -6335,7 +7763,7 @@
% \begin{macro}{\textRubikUw}
% These commands all draw forms which denote the Uw rotation.
% \begin{macrocode}
-\newcommand{\rrUw}{\textbf{\textsf{U\footnotesize{w}}}}
+\newcommand{\rrUw}{\@rrw{U}}
%%
\newcommand{\SquareUw}{%
\begin{tikzpicture}[scale=0.5]
@@ -6346,15 +7774,16 @@
\end{tikzpicture}%
}
%
-\newcommand{\rrhUw}{\raisebox{-0.333\height}{\SquareUw}\,}
+\newcommand{\rrhUw}{\raisebox{-0.333\height}{\@tlen\SquareUw\@tlen}}
%%
\newcommand{\RubikUw}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUw\\
-\rrUw
+\rrUw%
\end{minipage}%%
-}
+}}
%%
\newcommand{\textRubikUw}{\rrUw\,\rrhUw}
% \end{macrocode}
@@ -6374,7 +7803,7 @@
% \begin{macro}{\textRubikUp}
% These commands all draw forms which denote the Up rotation.
% \begin{macrocode}
-\newcommand{\rrUp}{\textbf{\textsf{U}$^\prime$}}
+\newcommand{\rrUp}{\@rrp{U}}
%%
\newcommand{\SquareUp}{%
\begin{tikzpicture}[scale=0.5]
@@ -6384,15 +7813,16 @@
\draw [thick] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhUp}{\raisebox{-0.333\height}{\SquareUp}\,}
+\newcommand{\rrhUp}{\raisebox{-0.333\height}{\@tlen\SquareUp\@tlen}}
%%
\newcommand{\RubikUp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUp\\
-\rrUp
+\rrUp%
\end{minipage}%%
-}
+}}
\newcommand{\textRubikUp}{\rrUp\,\rrhUp}
% \end{macrocode}
% \end{macro}
@@ -6411,7 +7841,7 @@
% \begin{macro}{\textRubikUwp}
% These commands all draw forms which denote the Uwp rotation.
% \begin{macrocode}
-\newcommand{\rrUwp}{\textbf{\textsf{U\footnotesize{w}}$^\prime$}}
+\newcommand{\rrUwp}{\@rrwp{U}}
%%
\newcommand{\SquareUwp}{%
\begin{tikzpicture}[scale=0.5]
@@ -6421,15 +7851,16 @@
\draw [thick] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhUwp}{\raisebox{-0.333\height}{\SquareUwp}\,}
+\newcommand{\rrhUwp}{\raisebox{-0.333\height}{\@tlen\SquareUwp\@tlen}}
%%
\newcommand{\RubikUwp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUwp\\
-\rrUwp
+\rrUwp%
\end{minipage}%%
-}
+}}
\newcommand{\textRubikUwp}{\rrUwp\,\rrhUwp}
% \end{macrocode}
% \end{macro}
@@ -6458,15 +7889,16 @@
\draw [thick, <-] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhUs}{\raisebox{-0.333\height}{\SquareUs}\,}
+\newcommand{\rrhUs}{\raisebox{-0.333\height}{\@tlen\SquareUs\@tlen}}
%%
\newcommand{\RubikUs}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUs\\
-\rrUs
+\rrUs%
\end{minipage}%
-}
+}}
\newcommand{\textRubikUs}{\rrUs\,\rrhUs}
% \end{macrocode}
% \end{macro}
@@ -6495,15 +7927,16 @@
\draw [thick, ->] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhUsp}{\raisebox{-0.333\height}{\SquareUsp}\,}
+\newcommand{\rrhUsp}{\raisebox{-0.333\height}{\@tlen\SquareUsp\@tlen}}
%%
\newcommand{\RubikUsp}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUsp\\
-\rrUsp
+\rrUsp%
\end{minipage}%
-}
+}}
\newcommand{\textRubikUsp}{\rrUsp\,\rrhUsp}
% \end{macrocode}
% \end{macro}
@@ -6532,15 +7965,16 @@
\draw [thick, ->] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhUa}{\raisebox{-0.333\height}{\SquareUa}\,}
+\newcommand{\rrhUa}{\raisebox{-0.333\height}{\@tlen\SquareUa\@tlen}}
%%
\newcommand{\RubikUa}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUa\\
-\rrUa
+\rrUa%
\end{minipage}%
-}
+}}
\newcommand{\textRubikUa}{\rrUa\,\rrhUa}
% \end{macrocode}
% \end{macro}
@@ -6569,15 +8003,16 @@
\draw [thick, <-] (\@sb,\@sd) -- (\@sbh, \@sd);
\end{tikzpicture}%
}
-\newcommand{\rrhUap}{\raisebox{-0.333\height}{\SquareUap}\,}
+\newcommand{\rrhUap}{\raisebox{-0.333\height}{\@tlen\SquareUap\@tlen}}
%%
\newcommand{\RubikUap}{%
+{\@rubikfont%
\begin{minipage}{0.6cm}
-\centering
+\centering%
\SquareUap\\
-\rrUap
+\rrUap%
\end{minipage}%
-}
+}}
\newcommand{\textRubikUap}{\rrUap\,\rrhUap}
% \end{macrocode}
% \end{macro}
@@ -6595,7 +8030,7 @@
% \begin{macro}{\Rubikx}
% These commands all draw forms which denote the x rotation.
% \begin{macrocode}
-\newcommand{\rrx}{\textbf{\textsf{x}}}
+\newcommand{\rrx}{\@rr{x}}
\newcommand{\Rubikx}{\@xyzRubik{x}}
\newcommand{\rrhx}{\@xyzh{x}}
% \end{macrocode}
@@ -6607,7 +8042,7 @@
% \begin{macro}{\Rubikxp}
% These commands all draw forms which denote the xp rotation.
% \begin{macrocode}
-\newcommand{\rrxp}{\textbf{\textsf{x}$^\prime$}}
+\newcommand{\rrxp}{\@rrp{x}}
\newcommand{\Rubikxp}{\@xyzRubikp{x}}
\newcommand{\rrhxp}{\@xyzhp{x}}
% \end{macrocode}
@@ -6623,7 +8058,7 @@
% \begin{macro}{\Rubiky}
% These commands all draw forms which denote the y rotation.
% \begin{macrocode}
-\newcommand{\rry}{\textbf{\textsf{y}}}
+\newcommand{\rry}{\@rr{y}}
\newcommand{\Rubiky}{\@xyzRubik{y}}
\newcommand{\rrhy}{\@xyzh{y}}
% \end{macrocode}
@@ -6635,7 +8070,7 @@
% \begin{macro}{\Rubikyp}
% These commands all draw forms which denote the yp rotation.
% \begin{macrocode}
-\newcommand{\rryp}{\textbf{\textsf{y}$^\prime$}}
+\newcommand{\rryp}{\@rrp{y}}
\newcommand{\Rubikyp}{\@xyzRubikp{y}}
\newcommand{\rrhyp}{\@xyzhp{y}}
% \end{macrocode}
@@ -6651,7 +8086,7 @@
% \begin{macro}{\Rubikz}
% These commands all draw forms which denote the z rotation.
% \begin{macrocode}
-\newcommand{\rrz}{\textbf{\textsf{z}}}
+\newcommand{\rrz}{\@rr{z}}
\newcommand{\Rubikz}{\@xyzRubik{z}}
\newcommand{\rrhz}{\@xyzh{z}}
% \end{macrocode}
@@ -6663,7 +8098,7 @@
% \begin{macro}{\Rubikzp}
% These commands all draw forms which denote the zp rotation.
% \begin{macrocode}
-\newcommand{\rrzp}{\textbf{\textsf{z}$^\prime$}}
+\newcommand{\rrzp}{\@rrp{z}}
\newcommand{\Rubikzp}{\@xyzRubikp{z}}
\newcommand{\rrhzp}{\@xyzhp{z}}
% \end{macrocode}
@@ -6679,7 +8114,7 @@
% \begin{macro}{\Rubiku}
% These commands all draw forms which denote the u rotation.
% \begin{macrocode}
-\newcommand{\rru}{\textbf{\textsf{u}}}
+\newcommand{\rru}{\@rr{u}}
\newcommand{\Rubiku}{\@xyzRubik{u}}
\newcommand{\rrhu}{\@xyzh{u}}
% \end{macrocode}
@@ -6691,9 +8126,9 @@
% \begin{macro}{\Rubikd}
% These commands all draw forms which denote the d rotation.
% \begin{macrocode}
-\newcommand{\rrd}{\textbf{\textsf{d}}}
-\newcommand{\Rubikd}{\@xyzRubik{d}}
-\newcommand{\rrhd}{\@xyzh{d}}
+\newcommand{\rrd}{\@rr{d}}
+\newcommand{\rrhd}{\@xyzhbdfl{d}}
+\newcommand{\Rubikd}{\@xyzbdflRubik{d}}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6707,9 +8142,9 @@
% \begin{macro}{\Rubikl}
% These commands all draw forms which denote the l rotation.
% \begin{macrocode}
-\newcommand{\rrl}{\textbf{\textsf{l}}}
-\newcommand{\Rubikl}{\@xyzRubik{l}}
-\newcommand{\rrhl}{\@xyzh{l}}
+\newcommand{\rrl}{\@rr{l}}
+\newcommand{\rrhl}{\@xyzhbdfl{l}}
+\newcommand{\Rubikl}{\@xyzbdflRubik{l}}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6719,7 +8154,7 @@
% \begin{macro}{\Rubikr}
% These commands all draw forms which denote the r rotation.
% \begin{macrocode}
-\newcommand{\rrr}{\textbf{\textsf{r}}}
+\newcommand{\rrr}{\@rr{r}}
\newcommand{\Rubikr}{\@xyzRubik{r}}
\newcommand{\rrhr}{\@xyzh{r}}
% \end{macrocode}
@@ -6735,9 +8170,9 @@
% \begin{macro}{\Rubikf}
% These commands all draw forms which denote the f rotation.
% \begin{macrocode}
-\newcommand{\rrf}{\textbf{\textsf{f}}}
-\newcommand{\Rubikf}{\@xyzRubik{f}}
-\newcommand{\rrhf}{\@xyzh{f}}
+\newcommand{\rrf}{\@rr{f}}
+\newcommand{\rrhf}{\@xyzhbdfl{f}}
+\newcommand{\Rubikf}{\@xyzbdflRubik{f}}
% \end{macrocode}
% \end{macro}
% \end{macro}
@@ -6747,15 +8182,1703 @@
% \begin{macro}{\Rubikb}
% These commands all draw forms which denote the b rotation.
% \begin{macrocode}
-\newcommand{\rrb}{\textbf{\textsf{b}}}
-\newcommand{\Rubikb}{\@xyzRubik{b}}
-\newcommand{\rrhb}{\@xyzh{b}}
+\newcommand{\rrb}{\@rr{b}}
+\newcommand{\rrhb}{\@xyzhbdfl{b}}
+\newcommand{\Rubikb}{\@xyzbdflRubik{b}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsection{\hspace{3mm}Face(c) and Face(m) rotations}
+% \label{sec:codeJaap}
+%
+% This subsection (added Nov 2016) is to accommodate some additional notation,
+% much used on the Jaap Puzzles website (Scherphius J), which, although quite
+% convenient, is technically `non-standard'. This additional notation
+% makes available the (middle slice) rotations of the form Rm, Rmp, Lm, Lmp, ... and
+% also the (whole cube) rotations Rc, Lc, ... (referenced to a face) as used on the
+% Cube Lovers usenet group (1981--1997). This notation was probably invented by Singmaster
+% (see Scherphius J).
+%
+% \begin{macro}{\@xyzhc}
+% \begin{macro}{\@xyzhcp}
+% \begin{macro}{\@xyzRubikc}
+% \begin{macro}{\@xyzRubikcp}
+% First we have some useful facilitating commands we shall make use of in
+% conjunction with the Face(c) and Face(cp) notation.
+% \begin{macrocode}
+\newcommand{\@xyzhc}[1]{[\raisebox{-1.2pt}%
+ {{\@rubikfont #1\@rubikfontFNS c}}]}
+\newcommand{\@xyzhcp}[1]{[\raisebox{-1.2pt}%
+ {{\@rubikfont #1{\@rubikfontFNS c}\@rubikprime}}]}
+\newcommand{\@xyzRubikc}[1]{\raisebox{3.45pt}%
+ {[\raisebox{-1.2pt}{{\@rubikfont #1\@rubikfontFNS c}}]}}
+\newcommand{\@xyzRubikcp}[1]{\raisebox{3.45pt}%
+ {[\raisebox{-1.2pt}{{\@rubikfont #1{\@rubikfontFNS c}\@rubikprime}}]}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Rc and Rcp}
+%
+% Whole cube rotations Rc = x, Rcp = xp.
+%
+% \begin{macro}{\rrRc}
+% \begin{macro}{\rrhRc}
+% \begin{macro}{\RubikRc}
+% These commands all draw forms which denote the Rc rotation.
+% \begin{macrocode}
+\newcommand{\rrRc}{\@rrc{R}}
+\newcommand{\RubikRc}{\@xyzRubikc{R}}
+\newcommand{\rrhRc}{\@xyzhc{R}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrRcp}
+% \begin{macro}{\rrhRcp}
+% \begin{macro}{\RubikRcp}
+% These commands all draw forms which denote the Rcp rotation.
+% \begin{macrocode}
+\newcommand{\rrRcp}{\@rrcp{R}}
+\newcommand{\RubikRcp}{\@xyzRubikcp{R}}
+\newcommand{\rrhRcp}{\@xyzhcp{R}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Lc and Lcp}
+%
+% Whole cube rotations Lc = xp, Lcp = x.
+%
+% \begin{macro}{\rrLc}
+% \begin{macro}{\rrhLc}
+% \begin{macro}{\RubikLc}
+% These commands all draw forms which denote the Lc rotation.
+% \begin{macrocode}
+\newcommand{\rrLc}{\@rrc{L}}
+\newcommand{\RubikLc}{\@xyzRubikc{L}}
+\newcommand{\rrhLc}{\@xyzhc{L}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrLcp}
+% \begin{macro}{\rrhLcp}
+% \begin{macro}{\RubikLcp}
+% These commands all draw forms which denote the Lcp rotation.
+% \begin{macrocode}
+\newcommand{\rrLcp}{\@rrcp{L}}
+\newcommand{\RubikLcp}{\@xyzRubikcp{L}}
+\newcommand{\rrhLcp}{\@xyzhcp{L}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Uc and Ucp}
+%
+% Whole cube rotation Uc = y, Ucp=yp.
+%
+% \begin{macro}{\rrUc}
+% \begin{macro}{\rrhUc}
+% \begin{macro}{\RubikUc}
+% These commands all draw forms which denote the Uc rotation.
+% \begin{macrocode}
+\newcommand{\rrUc}{\@rrc{U}}
+\newcommand{\RubikUc}{\@xyzRubikc{U}}
+\newcommand{\rrhUc}{\@xyzhc{U}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrUcp}
+% \begin{macro}{\rrhUcp}
+% \begin{macro}{\RubikUcp}
+% These commands all draw forms which denote the Ucp rotation.
+% \begin{macrocode}
+\newcommand{\rrUcp}{\@rrcp{U}}
+\newcommand{\RubikUcp}{\@xyzRubikcp{U}}
+\newcommand{\rrhUcp}{\@xyzhcp{U}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Dc and Dcp}
+%
+% Whole cube rotations Dc = yp, Dcp = y.
+%
+% \begin{macro}{\rrDc}
+% \begin{macro}{\rrhDc}
+% \begin{macro}{\RubikDc}
+% These commands all draw forms which denote the Dc rotation.
+% \begin{macrocode}
+\newcommand{\rrDc}{\@rrc{D}}
+\newcommand{\RubikDc}{\@xyzRubikc{D}}
+\newcommand{\rrhDc}{\@xyzhc{D}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrDcp}
+% \begin{macro}{\rrhDcp}
+% \begin{macro}{\RubikDcp}
+% These commands all draw forms which denote the Dcp rotation.
+% \begin{macrocode}
+\newcommand{\rrDcp}{\@rrcp{D}}
+\newcommand{\RubikDcp}{\@xyzRubikcp{D}}
+\newcommand{\rrhDcp}{\@xyzhcp{D}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Fc and Fcp}
+%
+% Whole cube rotations Fc = z, Fcp = zp.
+%
+% \begin{macro}{\rrFc}
+% \begin{macro}{\rrhFc}
+% \begin{macro}{\RubikFc}
+% These commands all draw forms which denote the Fc rotation.
+% \begin{macrocode}
+\newcommand{\rrFc}{\@rrc{F}}
+\newcommand{\RubikFc}{\@xyzRubikc{F}}
+\newcommand{\rrhFc}{\@xyzhc{F}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrFcp}
+% \begin{macro}{\rrhFcp}
+% \begin{macro}{\RubikFcp}
+% These commands all draw forms which denote the Fcp rotation.
+% \begin{macrocode}
+\newcommand{\rrFcp}{\@rrcp{F}}
+\newcommand{\RubikFcp}{\@xyzRubikcp{F}}
+\newcommand{\rrhFcp}{\@xyzhcp{F}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Bc and Bcp}
+%
+% Whole cube rotation Bc = zp, Bcp = z.
+%
+% \begin{macro}{\rrBc}
+% \begin{macro}{\rrhBc}
+% \begin{macro}{\RubikBc}
+% These commands all draw forms which denote the Bc rotation.
+% \begin{macrocode}
+\newcommand{\rrBc}{\@rrc{B}}
+\newcommand{\RubikBc}{\@xyzRubikc{B}}
+\newcommand{\rrhBc}{\@xyzhc{B}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrBcp}
+% \begin{macro}{\rrhBcp}
+% \begin{macro}{\RubikBcp}
+% These commands all draw forms which denote the Bcp rotation.
+% \begin{macrocode}
+\newcommand{\rrBcp}{\@rrcp{B}}
+\newcommand{\RubikBcp}{\@xyzRubikcp{B}}
+\newcommand{\rrhBcp}{\@xyzhcp{B}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Rm and Rmp}
+%
+% Rm = Mp= Sr (M follows Left). We use Sr and Srp as the templates.
+%
+% \begin{macro}{\rrRm}
+% \begin{macro}{\rrhRm}
+% \begin{macro}{\RubikRm}
+% \begin{macro}{\textRubikRm}
+% These commands draw forms of the Rm slice rotation.
+% \begin{macrocode}
+\newcommand{\rrRm}{\@rrm{R}}
+\newcommand{\rrhRm}{\rrhMp}%
+\newcommand{\RubikRm}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareMp\\
+\rrRm%
+\end{minipage}%
+}}
+\newcommand{\textRubikRm}{\rrRm\,\rrhMp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrRmp}
+% \begin{macro}{\rrhRmp}
+% \begin{macro}{\RubikRmp}
+% \begin{macro}{\textRubikRmp}
+% These commands draw forms of the Rmp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrRmp}{\@rrmp{R}}
+\newcommand{\rrhRmp}{\rrhM}%
+\newcommand{\RubikRmp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareM\\
+\rrRmp%
+\end{minipage}%
+}}
+\newcommand{\textRubikRmp}{\rrRmp\,\rrhM}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Lm and Lmp}
+%
+% Lm = M = Sl (M follows Left). We use Sl and Slp as the templates.
+%
+% \begin{macro}{\rrLm}
+% \begin{macro}{\rrhLm}
+% \begin{macro}{\RubikLm}
+% \begin{macro}{\textRubikLm}
+% These commands draw forms of the Lm slice rotation.
+% \begin{macrocode}
+\newcommand{\rrLm}{\@rrm{L}}
+\newcommand{\rrhLm}{\rrhM}%
+\newcommand{\RubikLm}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareM\\
+\rrLm%
+\end{minipage}%
+}}
+\newcommand{\textRubikLm}{\rrLm\,\rrhM}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrLmp}
+% \begin{macro}{\rrhLmp}
+% \begin{macro}{\RubikLmp}
+% \begin{macro}{\textRubikLmp}
+% These commands draw forms of the Lmp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrLmp}{\@rrmp{L}}
+\newcommand{\rrhLmp}{\rrhMp}%
+\newcommand{\RubikLmp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareMp\\
+\rrLmp%
+\end{minipage}%
+}}
+\newcommand{\textRubikLmp}{\rrLmp\,\rrhMp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Um and Ump}
+%
+% Um = Ep = Su (E follows Down). We use Su and Sup as the templates.
+%
+% \begin{macro}{\rrUm}
+% \begin{macro}{\rrhUm}
+% \begin{macro}{\RubikUm}
+% \begin{macro}{\textRubikUm}
+% These commands draw forms of the Um slice rotation.
+% We also need to fine-tune the spacing
+% between these `slice' hieroglyphs (especially Fs and Bs).
+% \begin{macrocode}
+\newcommand{\rrUm}{\@rrm{U}}
+\newcommand{\rrhUm}{\rrhEp}%
+\newcommand{\RubikUm}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareEp\\
+\rrUm%
+\end{minipage}%
+}}
+\newcommand{\textRubikUm}{\rrUm\,\rrhEp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrUmp}
+% \begin{macro}{\rrhUmp}
+% \begin{macro}{\RubikUmp}
+% \begin{macro}{\textRubikUmp}
+% These commands draw forms of the Ump slice rotation.
+% We also need to fine-tune the spacing
+% between these `slice' hieroglyphs (especially Fs and Bs).
+% \begin{macrocode}
+\newcommand{\rrUmp}{\@rrmp{U}}
+\newcommand{\rrhUmp}{\rrhE}%
+\newcommand{\RubikUmp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareE\\
+\rrUmp%
+\end{minipage}%
+}}
+\newcommand{\textRubikUmp}{\rrUmp\,\rrhE}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Dm and Dmp}
+%
+% Dm = E = Sd (E follows Down). We use Sd and Sdp as the templates.
+%
+% \begin{macro}{\rrDm}
+% \begin{macro}{\rrhDm}
+% \begin{macro}{\RubikDm}
+% \begin{macro}{\textRubikDm}
+% These commands draw forms of the Singmaster Dm slice rotation.
+% \begin{macrocode}
+\newcommand{\rrDm}{\@rrm{D}}
+\newcommand{\rrhDm}{\rrhE}%
+\newcommand{\RubikDm}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareE\\
+\rrDm%
+\end{minipage}%
+}}
+\newcommand{\textRubikDm}{\rrDm\,\rrhE}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrDmp}
+% \begin{macro}{\rrhDmp}
+% \begin{macro}{\RubikDmp}
+% \begin{macro}{\textRubikDmp}
+% These commands draw forms of the Singmaster Dmp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrDmp}{\@rrmp{D}}
+\newcommand{\rrhDmp}{\rrhEp}%
+\newcommand{\RubikDmp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareEp\\
+\rrDmp%
+\end{minipage}%
+}}
+\newcommand{\textRubikDmp}{\rrDmp\,\rrhEp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Fm and Fmp}
+%
+% Fm = S = Sf (S follows Front).
+% S is not visible from the front, so is represented in a square box.
+% We use Sf and Sfp as the templates.
+%
+% \begin{macro}{\rrFm}
+% \begin{macro}{\rrhFm}
+% \begin{macro}{\RubikFm}
+% \begin{macro}{\textRubikFm}
+% These commands draw forms of the Fm slice rotation.
+% We need to just make square with Fm in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrFm}{\@rrm{F}}
+\newcommand{\SquareFm}{\@tlen\@SquareLetter{\rrFm}\@tlen}
+\newcommand{\rrhFm}{\raisebox{-0.25mm}{\SquareFm}}
+\newcommand{\RubikFm}{\raisebox{\@hRubik}{\SquareFm}}
+\newcommand{\textRubikFm}{\rrhFm}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrFmp}
+% \begin{macro}{\rrhFmp}
+% \begin{macro}{\RubikFmp}
+% \begin{macro}{\textRubikFmp}
+% These commands draw forms of the Fmp slice rotation.
+% We need to just make square with Fmp in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrFmp}{\@rrmp{F}}
+\newcommand{\SquareFmp}{\@tlen\@SquareLetter{\rrFmp}\@tlen}
+\newcommand{\rrhFmp}{\raisebox{-0.25mm}{\SquareFmp}}
+\newcommand{\RubikFmp}{\raisebox{\@hRubik}{\SquareFmp}}
+\newcommand{\textRubikFmp}{\rrhFmp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations Bm and Bmp}
+%
+% Bm = Sp = Sb. We use Sb and Sbp as the templates.
+%
+% \begin{macro}{\rrBm}
+% \begin{macro}{\rrhBm}
+% \begin{macro}{\RubikBm}
+% \begin{macro}{\textRubikBm}
+% These commands draw forms of the Bm slice rotation.
+% We need to just make square with Bm in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrBm}{\@rrm{B}}
+\newcommand{\SquareBm}{\@tlen\@SquareLetter{\rrBm}\@tlen}
+\newcommand{\rrhBm}{\raisebox{-0.25mm}{\SquareBm}}
+\newcommand{\RubikBm}{\raisebox{\@hRubik}{\SquareBm}}
+\newcommand{\textRubikBm}{\rrhBm}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrBmp}
+% \begin{macro}{\rrhBmp}
+% \begin{macro}{\RubikBmp}
+% \begin{macro}{\textRubikBmp}
+% These commands draw forms of the Bmp slice rotation.
+% We need to just make square with Bmp in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrBmp}{\@rrmp{B}}
+\newcommand{\SquareBmp}{\@tlen\@SquareLetter{\rrBmp}\@tlen}
+\newcommand{\rrhBmp}{\raisebox{-0.25mm}{\SquareBmp}}
+\newcommand{\RubikBmp}{\raisebox{\@hRubik}{\SquareBmp}}
+\newcommand{\textRubikBmp}{\rrhBmp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+% \subsection{\hspace{3mm}Randelshofer superset ENG rotations (CMST)}
+% \label{sec:codeRandelshofer}
+%
+% (see webpage: \verb!Randelshofer.ch/rubik/patterns/doc/supersetENG_3x3.html!)
+%
+% This section relates to the recent Rubik notation developed
+% by Randelshofer (see URL above), known as the ``superset ENG rotations''
+% (see Sections~\ref{sec:RubikCommands} and \ref{sec:listofRandelshofercommands}
+% for details).
+%
+% I denote this notation as ``CMST'' (i.e.,~his C, M, S and T notation).
+% Although this notation replicates previously existing World Cube Association notation,
+% we include it here for completeness. Fortunately the Randelshofer notation does
+% not conflict with existing notation.
+%
+% Briefly, the CMST letters denote whole Cube, Middle, outer-Slice and wide (T)
+% rotations associated with named faces. For example, the rotation-code MR
+% indicates a rotation of the middle slice parallel to the \textsc{right} face,
+% and in the same sense (direction) as \rr{R}\ (see Section~\ref{sec:RubikCommands} for details).
+%
+%
+% First we make some useful facilitating commands for the CX1 and CX1p forms
+% as these are handled with raised square brackets.
+% We model these four macros on the equivalent
+% \verb!\@xyzh!, \verb!\@xyzhp!,\verb!\@xyzRubik!,\verb!\@xyzRubikp! macros defined above.
+% \begin{macrocode}
+\newcommand{\@randhc}[1]{[\raisebox{-1.2pt}{{\@rubikfont C#1}}]}
+\newcommand{\@randhcp}[1]{[\raisebox{-1.2pt}{{\@rubikfont C#1\@rubikprime}}]}
+\newcommand{\@randRubikc}[1]%
+ {\raisebox{3.45pt}{[\raisebox{-1.2pt}{{\@rubikfont C#1}}]}}
+\newcommand{\@randRubikcp}[1]%
+ {\raisebox{3.45pt}{[\raisebox{-1.2pt}{{\@rubikfont C#1\@rubikprime}}]}}
+% \end{macrocode}
+%
+%
+% In the following we create the base form of a rotation code, eg \rrhCR\ and then
+% the user typesets this rotation using CR as the argument for \verb!\rrh{}!.
+% This works because the macro \verb!\@join{}{}! is used to join \cmd{\rrh}
+% and CR $\rightarrow$ \cmd{\rrhCR} etc.
+%
+% The = signs at the beginning of each new section indicate the equivalence
+% between the Randelshofer notation and the current (World Cube Association)
+% notation.
+%
+%
+% \subsubsection{\hspace{3mm}Rotations CR and CRp}
+%
+% Whole cube rotations CR = Rc = x, CRp = Rcp = xp.
+%
+% \begin{macro}{\rrCR}
+% \begin{macro}{\rrhCR}
+% \begin{macro}{\RubikCR}
+% These commands all draw forms which denote the CR = Rc rotation.
+% \begin{macrocode}
+\newcommand{\rrCR}{\@rr{CR}}
+\newcommand{\RubikCR}{\@randRubikc{R}}
+\newcommand{\rrhCR}{\@randhc{R}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrCRp}
+% \begin{macro}{\rrhCRp}
+% \begin{macro}{\RubikCRp}
+% These commands all draw forms which denote the CRp = Rcp rotation.
+% \begin{macrocode}
+\newcommand{\rrCRp}{\@rrp{CR}}
+\newcommand{\RubikCRp}{\@randRubikcp{R}}
+\newcommand{\rrhCRp}{\@randhcp{R}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations CL and CLp}
+%
+% Whole cube rotations CL = Lc = xp, CLp = Lcp = x.
+%
+% \begin{macro}{\rrCL}
+% \begin{macro}{\rrhCL}
+% \begin{macro}{\RubikCL}
+% These commands all draw forms which denote the CL rotation.
+% \begin{macrocode}
+\newcommand{\rrCL}{\@rr{CL}}
+\newcommand{\RubikCL}{\@randRubikc{L}}
+\newcommand{\rrhCL}{\@randhc{L}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrCLp}
+% \begin{macro}{\rrhCLp}
+% \begin{macro}{\RubikCLp}
+% These commands all draw forms which denote the CLp rotation.
+% \begin{macrocode}
+\newcommand{\rrCLp}{\@rrp{CL}}
+\newcommand{\RubikCLp}{\@randRubikcp{L}}
+\newcommand{\rrhCLp}{\@randhcp{L}}
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
%
%
+% \subsubsection{\hspace{3mm}Rotations CU and CUp}
+%
+% Whole cube rotation CU = Uc = y, CUp = Ucp=yp.
+%
+% \begin{macro}{\rrCU}
+% \begin{macro}{\rrhCU}
+% \begin{macro}{\RubikCU}
+% These commands all draw forms which denote the CU rotation.
+% \begin{macrocode}
+\newcommand{\rrCU}{\@rr{CU}}
+\newcommand{\RubikCU}{\@randRubikc{U}}
+\newcommand{\rrhCU}{\@randhc{U}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrCUp}
+% \begin{macro}{\rrhCUp}
+% \begin{macro}{\RubikCUp}
+% These commands all draw forms which denote the CUp rotation.
+% \begin{macrocode}
+\newcommand{\rrCUp}{\@rrp{CU}}
+\newcommand{\RubikCUp}{\@randRubikcp{U}}
+\newcommand{\rrhCUp}{\@randhcp{U}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations CD and CDp}
+%
+% Whole cube rotations CD = Dc = yp, CDp = Dcp = y.
+%
+% \begin{macro}{\rrCD}
+% \begin{macro}{\rrhCD}
+% \begin{macro}{\RubikCD}
+% These commands all draw forms which denote the CD rotation.
+% \begin{macrocode}
+\newcommand{\rrCD}{\@rr{CD}}
+\newcommand{\RubikCD}{\@randRubikc{D}}
+\newcommand{\rrhCD}{\@randhc{D}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrCDp}
+% \begin{macro}{\rrhCDp}
+% \begin{macro}{\RubikCDp}
+% These commands all draw forms which denote the CDp rotation.
+% \begin{macrocode}
+\newcommand{\rrCDp}{\@rrp{CD}}
+\newcommand{\RubikCDp}{\@randRubikcp{D}}
+\newcommand{\rrhCDp}{\@randhcp{D}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations CF and CFp}
+%
+% Whole cube rotations CF = Fc = z, CFp = Fcp = zp.
+%
+% \begin{macro}{\rrCF}
+% \begin{macro}{\rrhCF}
+% \begin{macro}{\RubikCF}
+% These commands all draw forms which denote the CF rotation.
+% \begin{macrocode}
+\newcommand{\rrCF}{\@rr{CF}}
+\newcommand{\RubikCF}{\@randRubikc{F}}
+\newcommand{\rrhCF}{\@randhc{F}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrCFp}
+% \begin{macro}{\rrhCFp}
+% \begin{macro}{\RubikCFp}
+% These commands all draw forms which denote the CFp rotation.
+% \begin{macrocode}
+\newcommand{\rrCFp}{\@rrp{CF}}
+\newcommand{\RubikCFp}{\@randRubikcp{F}}
+\newcommand{\rrhCFp}{\@randhcp{F}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations CB and CBp}
+%
+% Whole cube rotation CB = Bc = zp, CBp = Bcp = z.
+%
+% \begin{macro}{\rrCB}
+% \begin{macro}{\rrhCB}
+% \begin{macro}{\RubikCB}
+% These commands all draw forms which denote the CB rotation.
+% \begin{macrocode}
+\newcommand{\rrCB}{\@rr{CB}}
+\newcommand{\RubikCB}{\@randRubikc{B}}
+\newcommand{\rrhCB}{\@randhc{B}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \begin{macro}{\rrCBp}
+% \begin{macro}{\rrhCBp}
+% \begin{macro}{\RubikCBp}
+% These commands all draw forms which denote the CBp rotation.
+% \begin{macrocode}
+\newcommand{\rrCBp}{\@rrp{CB}}
+\newcommand{\RubikCBp}{\@randRubikcp{B}}
+\newcommand{\rrhCBp}{\@randhcp{B}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsubsection{\hspace{3mm}Rotations MR and MRp}
+%
+% MR = Rm = Mp= Sr (M follows Left). We use Sr and Srp as the templates.
+%
+% \begin{macro}{\rrMR}
+% \begin{macro}{\rrhMR}
+% \begin{macro}{\RubikMR}
+% \begin{macro}{\textRubikMR}
+% These commands draw forms of the MR middle slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMR}{\@rr{MR}}
+\newcommand{\rrhMR}{\rrhMp}%
+\newcommand{\RubikMR}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareMp\\
+\rrMR%
+\end{minipage}%
+}}
+\newcommand{\textRubikMR}{\rrMR\,\rrhMp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrMRp}
+% \begin{macro}{\rrhMRp}
+% \begin{macro}{\RubikMRp}
+% \begin{macro}{\textRubikMRp}
+% These commands draw forms of the MRp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMRp}{\@rrp{MR}}
+\newcommand{\rrhMRp}{\rrhM}%
+\newcommand{\RubikMRp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareM\\
+\rrMRp%
+\end{minipage}%
+}}
+\newcommand{\textRubikMRp}{\rrMRp\,\rrhM}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations ML and MLp}
+%
+% ML = Lm = M = Sl (M follows Left). We use Sl and Slp as the templates.
+%
+% \begin{macro}{\rrML}
+% \begin{macro}{\rrhML}
+% \begin{macro}{\RubikML}
+% \begin{macro}{\textRubikML}
+% These commands draw forms of the ML slice rotation.
+% \begin{macrocode}
+\newcommand{\rrML}{\@rr{ML}}
+\newcommand{\rrhML}{\rrhM}%
+\newcommand{\RubikML}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareM\\
+\rrML%
+\end{minipage}%
+}}
+\newcommand{\textRubikML}{\rrML\,\rrhM}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrMLp}
+% \begin{macro}{\rrhMLp}
+% \begin{macro}{\RubikMLp}
+% \begin{macro}{\textRubikMLp}
+% These commands draw forms of the MLp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMLp}{\@rrp{ML}}
+\newcommand{\rrhMLp}{\rrhMp}%
+\newcommand{\RubikMLp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareMp\\
+\rrMLp%
+\end{minipage}%
+}}
+\newcommand{\textRubikMLp}{\rrMLp\,\rrhMp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations MU and MUp}
+%
+% MU = Um = Ep = Su (E follows Down). We use Su and Sup as the templates.
+%
+% \begin{macro}{\rrMU}
+% \begin{macro}{\rrhMU}
+% \begin{macro}{\RubikMU}
+% \begin{macro}{\textRubikMU}
+% These commands draw forms of the MU slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMU}{\@rr{MU}}
+\newcommand{\rrhMU}{\rrhEp}%
+\newcommand{\RubikMU}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareEp\\
+\rrMU%
+\end{minipage}%
+}}
+\newcommand{\textRubikMU}{\rrMU\,\rrhEp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrMUp}
+% \begin{macro}{\rrhMUp}
+% \begin{macro}{\RubikMUp}
+% \begin{macro}{\textRubikMUp}
+% These commands draw forms of the MUp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMUp}{\@rrp{MU}}
+\newcommand{\rrhMUp}{\rrhE}%
+\newcommand{\RubikMUp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareE\\
+\rrMUp%
+\end{minipage}%
+}}
+\newcommand{\textRubikMUp}{\rrMUp\,\rrhE}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations MD and MDp}
+%
+% MD = Dm = E = Sd (E follows Down). We use Sd and Sdp as the templates.
+%
+% \begin{macro}{\rrMD}
+% \begin{macro}{\rrhMD}
+% \begin{macro}{\RubikMD}
+% \begin{macro}{\textRubikMD}
+% These commands draw forms of the Randelshofer MD slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMD}{\@rr{MD}}
+\newcommand{\rrhMD}{\rrhE}%
+\newcommand{\RubikMD}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareE\\
+\rrMD%
+\end{minipage}%
+}}
+\newcommand{\textRubikMD}{\rrMD\,\rrhE}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrMDp}
+% \begin{macro}{\rrhMDp}
+% \begin{macro}{\RubikMDp}
+% \begin{macro}{\textRubikMDp}
+% These commands draw forms of the Randelshofer MDp slice rotation.
+% \begin{macrocode}
+\newcommand{\rrMDp}{\@rrp{MD}}
+\newcommand{\rrhMDp}{\rrhEp}%
+\newcommand{\RubikMDp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareEp\\
+\rrMDp%
+\end{minipage}%
+}}
+\newcommand{\textRubikMDp}{\rrMDp\,\rrhEp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations MF and MFp}
+%
+% MF = Fm = S = Sf (S follows Front).
+% MF = S is not visible from the front, so is represented in a square box.
+% We use Sf and Sfp as the templates.
+%
+% \begin{macro}{\rrMF}
+% \begin{macro}{\rrhMF}
+% \begin{macro}{\RubikMF}
+% \begin{macro}{\textRubikMF}
+% These commands draw forms of the MF slice rotation.
+% We need to just make square with MF in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrMF}{\@rr{MF}}
+\newcommand{\SquareMF}{\@tlen\@SquareLetter{\rrMF}\@tlen}
+\newcommand{\rrhMF}{\raisebox{-0.25mm}{\SquareMF}}
+\newcommand{\RubikMF}{\raisebox{\@hRubik}{\SquareMF}}
+\newcommand{\textRubikMF}{\rrhMF}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrMFp}
+% \begin{macro}{\rrhMFp}
+% \begin{macro}{\RubikMFp}
+% \begin{macro}{\textRubikMFp}
+% These commands draw forms of the MFp slice rotation.
+% We need to just make square with MFp in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrMFp}{\@rrp{MF}}
+\newcommand{\SquareMFp}{\@tlen\@SquareLetter{\rrMFp}\@tlen}
+\newcommand{\rrhMFp}{\raisebox{-0.25mm}{\SquareMFp}}
+\newcommand{\RubikMFp}{\raisebox{\@hRubik}{\SquareMFp}}
+\newcommand{\textRubikMFp}{\rrhMFp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations MB and MBp}
+%
+% MB = Bm = Sp = Sb. We use Sb and Sbp as the templates.
+%
+% \begin{macro}{\rrMB}
+% \begin{macro}{\rrhMB}
+% \begin{macro}{\RubikMB}
+% \begin{macro}{\textRubikMB}
+% These commands draw forms of the MB slice rotation.
+% We need to just make square with MB in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrMB}{\@rr{MB}}
+\newcommand{\SquareMB}{\@tlen\@SquareLetter{\rrMB}\@tlen}
+\newcommand{\rrhMB}{\raisebox{-0.25mm}{\SquareMB}}
+\newcommand{\RubikMB}{\raisebox{\@hRubik}{\SquareMB}}
+\newcommand{\textRubikMB}{\rrhMB}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrMBp}
+% \begin{macro}{\rrhMBp}
+% \begin{macro}{\RubikMBp}
+% \begin{macro}{\textRubikMBp}
+% These commands draw forms of the MBp slice rotation.
+% We need to just make square with MBp in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrMBp}{\@rrp{MB}}
+\newcommand{\SquareMBp}{\@tlen\@SquareLetter{\rrMBp}\@tlen}
+\newcommand{\rrhMBp}{\raisebox{-0.25mm}{\SquareMBp}}
+\newcommand{\RubikMBp}{\raisebox{\@hRubik}{\SquareMBp}}
+\newcommand{\textRubikMBp}{\rrhMBp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsubsection{\hspace{3mm}Rotations T (wide)}
+%
+% TR = Rw \ \ (We use Rw and Rwp as the templates).
+%
+% {\noindent}We first set up some useful T and Tp macros for use with (L,R,U,D,F,B)
+% slightly more general than before. As before the rubikfont command needs to be
+% delimited using two curly brackets to contain the font expression.
+% \begin{macrocode}
+\newcommand{\@rrT}[1]{{\@rubikfont T#1}}
+\newcommand{\@rrhT}[1]{\@join{\rrh#1}{w}}%
+\newcommand{\@textRubikT}[1]{\@rrT{#1}\,\@join{\rrh#1}{w}}
+%
+\newcommand{\@RubikT}[1]{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%%
+\@join{\Square#1}{w}\\%
+\@rrT{#1}%%
+\end{minipage}%
+}}
+%%
+\newcommand{\@rrTp}[1]{{\@rubikfont T#1\@rubikprime}}
+\newcommand{\@rrhTp}[1]{\@join{\rrh#1}{wp}}%
+\newcommand{\@textRubikTp}[1]{\@rrTp{#1}\,\@join{\rrh#1}{wp}}
+%%
+\newcommand{\@RubikTp}[1]{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%%
+\@join{\Square#1}{wp}\\%
+\@rrTp{#1}%%
+\end{minipage}%
+}}
+% \end{macrocode}
+%
+%
+%
+% \begin{macro}{\rrTL}
+% \begin{macro}{\rrhTL}
+% \begin{macro}{\RubikTL}
+% \begin{macro}{\textRubikTL}
+% These commands draw forms of the TL = Lw wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTL}{\@rrT{L}}% = rrLw
+\newcommand{\rrhTL}{\@rrhT{L}}
+\newcommand{\textRubikTL}{\@textRubikT{L}}
+\newcommand{\RubikTL}{\@RubikT{L}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\rrTLp}
+% \begin{macro}{\rrhTLp}
+% \begin{macro}{\RubikTLp}
+% \begin{macro}{\textRubikTLp}
+% These commands draw forms of the TLp = Lwp wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTLp}{\@rrTp{L}}
+\newcommand{\rrhTLp}{\@rrhTp{L}}
+\newcommand{\textRubikTLp}{\@textRubikTp{L}}
+\newcommand{\RubikTLp}{\@RubikTp{L}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\rrTR}
+% \begin{macro}{\rrhTR}
+% \begin{macro}{\RubikTR}
+% \begin{macro}{\textRubikTR}
+% These commands draw forms of the TR = Rw wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTR}{\@rrT{R}}
+\newcommand{\rrhTR}{\@rrhT{R}}
+\newcommand{\textRubikTR}{\@textRubikT{R}}
+\newcommand{\RubikTR}{\@RubikT{R}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\rrTRp}
+% \begin{macro}{\rrhTRp}
+% \begin{macro}{\RubikTRp}
+% \begin{macro}{\textRubikTRp}
+% These commands draw forms of the TRp = Rmp wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTRp}{\@rrTp{R}}
+\newcommand{\rrhTRp}{\@rrhTp{R}}
+\newcommand{\textRubikTRp}{\@textRubikTp{R}}
+\newcommand{\RubikTRp}{\@RubikTp{R}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\rrTU}
+% \begin{macro}{\rrhTU}
+% \begin{macro}{\RubikTU}
+% \begin{macro}{\textRubikTU}
+% These commands draw forms of the TU = Uw wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTU}{\@rrT{U}}
+\newcommand{\rrhTU}{\@rrhT{U}}
+\newcommand{\textRubikTU}{\@textRubikT{U}}
+\newcommand{\RubikTU}{\@RubikT{U}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\rrTUp}
+% \begin{macro}{\rrhTUp}
+% \begin{macro}{\RubikTUp}
+% \begin{macro}{\textRubikTUp}
+% These commands draw forms of the TUp = Uwp wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTUp}{\@rrTp{U}}
+\newcommand{\rrhTUp}{\@rrhTp{U}}
+\newcommand{\textRubikTUp}{\@textRubikTp{U}}
+\newcommand{\RubikTUp}{\@RubikTp{U}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\rrTD}
+% \begin{macro}{\rrhTD}
+% \begin{macro}{\RubikTD}
+% \begin{macro}{\textRubikTD}
+% These commands draw forms of the TD = Dw wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTD}{\@rrT{D}}
+\newcommand{\rrhTD}{\@rrhT{D}}
+\newcommand{\textRubikTD}{\@textRubikT{D}}
+\newcommand{\RubikTD}{\@RubikT{D}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\rrTDp}
+% \begin{macro}{\rrhTDp}
+% \begin{macro}{\RubikTDp}
+% \begin{macro}{\textRubikTDp}
+% These commands draw forms of the TDp = Dwp wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTDp}{\@rrTp{D}}
+\newcommand{\rrhTDp}{\@rrhTp{D}}
+\newcommand{\textRubikTDp}{\@textRubikTp{D}}
+\newcommand{\RubikTDp}{\@RubikTp{D}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrTF}
+% \begin{macro}{\rrhTF}
+% \begin{macro}{\RubikTF}
+% \begin{macro}{\textRubikTF}
+% These commands draw forms of the TF = Fw wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTF}{\@rrT{F}}
+\newcommand{\rrhTF}{\@rrhT{F}}
+\newcommand{\textRubikTF}{\@textRubikT{F}}
+\newcommand{\RubikTF}{\@RubikT{F}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\rrTFp}
+% \begin{macro}{\rrhTFp}
+% \begin{macro}{\RubikTFp}
+% \begin{macro}{\textRubikTFp}
+% These commands draw forms of the TFp = Fwp wide slice rotation.
+% \begin{macrocode}
+\newcommand{\rrTFp}{\@rrTp{F}}
+\newcommand{\rrhTFp}{\@rrhTp{F}}
+\newcommand{\textRubikTFp}{\@textRubikTp{F}}
+\newcommand{\RubikTFp}{\@RubikTp{F}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\rrTB}
+% \begin{macro}{\rrhTB}
+% \begin{macro}{\RubikTB}
+% \begin{macro}{\textRubikTB}
+% These commands draw forms of the TB = Bw wide slice rotation.
+% NOTE we just use the letters TB in a square
+% \begin{macrocode}
+\newcommand{\rrTB}{\@rrT{B}}
+\newcommand{\SquareTB}{\@tlen\@SquareLetter{\rrTB}\@tlen}
+\newcommand{\rrhTB}{\raisebox{-0.25mm}{\SquareTB}}
+\newcommand{\textRubikTB}{\rrhTB}
+\newcommand{\RubikTB}{\raisebox{\@hRubik}{\SquareTB}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+% \begin{macro}{\rrTBp}
+% \begin{macro}{\rrhTBp}
+% \begin{macro}{\RubikTBp}
+% \begin{macro}{\textRubikTBp}
+% These commands draw forms of the TBp = Bwp wide slice rotation.
+% NOTE we just use the letters TB' in a square
+% \begin{macrocode}
+\newcommand{\rrTBp}{\@rrTp{B}}
+\newcommand{\SquareTBp}{\@tlen\@SquareLetter{\rrTBp}\@tlen}
+\newcommand{\rrhTBp}{\raisebox{-0.25mm}{\SquareTBp}}
+\newcommand{\textRubikTBp}{\rrhTBp}
+\newcommand{\RubikTBp}{\raisebox{\@hRubik}{\SquareTBp}}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsubsection{\hspace{3mm}Rotations SR and SRp (opposite slices)}
+%
+% opposite slices in same direction
+% SR = Rs (both rotating in R direction)
+%
+% \begin{macro}{\rrSR}
+% \begin{macro}{\rrhSR}
+% \begin{macro}{\RubikSR}
+% \begin{macro}{\textRubikSR}
+% These commands draw forms of the SR opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSR}{\@rr{SR}}
+\newcommand{\rrhSR}{\rrhRs}%
+\newcommand{\RubikSR}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareRs\\
+\rrSR%
+\end{minipage}%
+}}
+\newcommand{\textRubikSR}{\rrSR\,\rrhRs}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrSRp}
+% \begin{macro}{\rrhSRp}
+% \begin{macro}{\RubikSRp}
+% \begin{macro}{\textRubikSRp}
+% These commands draw forms of the SRp opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSRp}{\@rrp{SR}}
+\newcommand{\rrhSRp}{\rrhRsp}%
+\newcommand{\RubikSRp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareRsp\\
+\rrSRp%
+\end{minipage}%
+}}
+\newcommand{\textRubikSRp}{\rrSRp\,\rrhRsp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations SL and SLp}
+%
+% SL = Ls (both rotating in L direction)
+%
+% \begin{macro}{\rrSL}
+% \begin{macro}{\rrhSL}
+% \begin{macro}{\RubikSL}
+% \begin{macro}{\textRubikSL}
+% These commands draw forms of the SL opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSL}{\@rr{SL}}
+\newcommand{\rrhSL}{\rrhLs}%
+\newcommand{\RubikSL}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareLs\\
+\rrSL%
+\end{minipage}%
+}}
+\newcommand{\textRubikSL}{\rrSL\,\rrhLs}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrSLp}
+% \begin{macro}{\rrhSLp}
+% \begin{macro}{\RubikSLp}
+% \begin{macro}{\textRubikSLp}
+% These commands draw forms of the SLp opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSLp}{\@rrp{SL}}
+\newcommand{\rrhSLp}{\rrhLsp}%
+\newcommand{\RubikSLp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareLsp\\
+\rrSLp%
+\end{minipage}%
+}}
+\newcommand{\textRubikSLp}{\rrSLp\,\rrhLsp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations SU and SUp}
+%
+% SU = Us (both rotating in U direction)
+%
+% \begin{macro}{\rrSU}
+% \begin{macro}{\rrhSU}
+% \begin{macro}{\RubikSU}
+% \begin{macro}{\textRubikSU}
+% These commands draw forms of the SU opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSU}{\@rr{SU}}
+\newcommand{\rrhSU}{\rrhUs}%
+\newcommand{\RubikSU}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareUs\\
+\rrSU%
+\end{minipage}%
+}}
+\newcommand{\textRubikSU}{\rrSU\,\rrhUs}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrSUp}
+% \begin{macro}{\rrhSUp}
+% \begin{macro}{\RubikSUp}
+% \begin{macro}{\textRubikSUp}
+% These commands draw forms of the SUp opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSUp}{\@rrp{SU}}
+\newcommand{\rrhSUp}{\rrhUsp}%
+\newcommand{\RubikSUp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareUsp\\
+\rrSUp%
+\end{minipage}%
+}}
+\newcommand{\textRubikSUp}{\rrSUp\,\rrhUsp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations SD and SDp}
+%
+% SD = Ds (both rotating in D direction)
+%
+% \begin{macro}{\rrSD}
+% \begin{macro}{\rrhSD}
+% \begin{macro}{\RubikSD}
+% \begin{macro}{\textRubikSD}
+% These commands draw forms of the SD opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSD}{\@rr{SD}}
+\newcommand{\rrhSD}{\rrhDs}%
+\newcommand{\RubikSD}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareDs\\
+\rrSD%
+\end{minipage}%
+}}
+\newcommand{\textRubikSD}{\rrSD\,\rrhDs}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrSDp}
+% \begin{macro}{\rrhSDp}
+% \begin{macro}{\RubikSDp}
+% \begin{macro}{\textRubikSDp}
+% These commands draw forms of the SDp opposite slice rotation.
+% \begin{macrocode}
+\newcommand{\rrSDp}{\@rrp{SD}}
+\newcommand{\rrhSDp}{\rrhDsp}%
+\newcommand{\RubikSDp}{%
+{\@rubikfont%
+\begin{minipage}{0.6cm}
+\centering%
+\SquareDsp\\
+\rrSDp%
+\end{minipage}%
+}}
+\newcommand{\textRubikSDp}{\rrSDp\,\rrhDsp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsubsection{\hspace{3mm}Rotations SF and SFp}
+%
+% SF = Fs is not visible from the front, so is represented in a square box.
+% Both rotating in the F direction
+% We use Fs and Fsp as the templates.
+%
+% \begin{macro}{\rrSF}
+% \begin{macro}{\rrhSF}
+% \begin{macro}{\RubikSF}
+% \begin{macro}{\textRubikSF}
+% These commands draw forms of the SF opposite slice rotation.
+% We need to just make square with SF in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrSF}{\@rr{SF}}
+\newcommand{\SquareSF}{\@tlen\@SquareLetter{\rrSF}\@tlen}
+\newcommand{\rrhSF}{\raisebox{-0.25mm}{\SquareSF}}
+\newcommand{\RubikSF}{\raisebox{\@hRubik}{\SquareSF}}
+\newcommand{\textRubikSF}{\rrhSF}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrSFp}
+% \begin{macro}{\rrhSFp}
+% \begin{macro}{\RubikSFp}
+% \begin{macro}{\textRubikSFp}
+% These commands draw forms of the SFp opposite slice rotation.
+% We need to just make square with SFp in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrSFp}{\@rrp{SF}}
+\newcommand{\SquareSFp}{\@tlen\@SquareLetter{\rrSFp}\@tlen}
+\newcommand{\rrhSFp}{\raisebox{-0.25mm}{\SquareSFp}}
+\newcommand{\RubikSFp}{\raisebox{\@hRubik}{\SquareSFp}}
+\newcommand{\textRubikSFp}{\rrhSFp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+%
+% \subsubsection{\hspace{3mm}Rotations SB and SBp}
+%
+% SB = Bs is not visible from the front, so is represented in a square box.
+% Both rotating in the B direction
+% We use Bs and Bsp as the templates.
+%
+% \begin{macro}{\rrSB}
+% \begin{macro}{\rrhSB}
+% \begin{macro}{\RubikSB}
+% \begin{macro}{\textRubikSB}
+% These commands draw forms of the SB opposite slice rotation.
+% We need to just make square with SB in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrSB}{\@rr{SB}}
+\newcommand{\SquareSB}{\@tlen\@SquareLetter{\rrSB}\@tlen}
+\newcommand{\rrhSB}{\raisebox{-0.25mm}{\SquareSB}}
+\newcommand{\RubikSB}{\raisebox{\@hRubik}{\SquareSB}}
+\newcommand{\textRubikSB}{\rrhSB}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\rrSBp}
+% \begin{macro}{\rrhSBp}
+% \begin{macro}{\RubikSBp}
+% \begin{macro}{\textRubikSBp}
+% These commands draw forms of the SBp opposite slice rotation.
+% We need to just make square with SBp in square;
+% adjust box height using a \cmd{\rule};
+% adjust \cmd{\fboxsep} (default=3pt);
+% adjust \cmd{\fboxrule} (default=0.4pt);
+% bounded by \{\} so no need to reset to defaults.
+% Not visible from the front.
+% \begin{macrocode}
+\newcommand{\rrSBp}{\@rrp{SB}}
+\newcommand{\SquareSBp}{\@tlen\@SquareLetter{\rrSBp}\@tlen}
+\newcommand{\rrhSBp}{\raisebox{-0.25mm}{\SquareSBp}}
+\newcommand{\RubikSBp}{\raisebox{\@hRubik}{\SquareSBp}}
+\newcommand{\textRubikSBp}{\rrhSBp}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+%
+%
+%
+% \subsection{\hspace{3mm}Axis rotations (textRubik versions)}
+% \label{sec:codetextrubikaxisversions}
+%
+% For completeness we include a \cmd{\textRubik} version of all the
+% axis rotation codes (making them equal to their hieroglyphic \cmd{\rrh} version).
+% Obviously this list must go at the end of this file. While these commands are perhaps
+% strictly unnecessary, the motivation is to allow users to include them in
+% a \cmd{\ShowSequence} command when using the \cmd{\textRubik} font argument.
+%
+% \begin{macrocode}
+\newcommand{\textRubikx}{\rrhx}
+\newcommand{\textRubikxp}{\rrhxp}
+\newcommand{\textRubiky}{\rrhy}
+\newcommand{\textRubikyp}{\rrhyp}
+\newcommand{\textRubikz}{\rrhz}
+\newcommand{\textRubikzp}{\rrhzp}
+\newcommand{\textRubikl}{\rrhl}
+\newcommand{\textRubikr}{\rrhr}
+\newcommand{\textRubiku}{\rrhu}
+\newcommand{\textRubikd}{\rrhd}
+\newcommand{\textRubikf}{\rrhf}
+\newcommand{\textRubikb}{\rrhb}
+\newcommand{\textRubikLc}{\rrhLc}
+\newcommand{\textRubikLcp}{\rrhLcp}
+\newcommand{\textRubikRc}{\rrhRc}
+\newcommand{\textRubikRcp}{\rrhRcp}
+\newcommand{\textRubikUc}{\rrhUc}
+\newcommand{\textRubikUcp}{\rrhUcp}
+\newcommand{\textRubikDc}{\rrhDc}
+\newcommand{\textRubikDcp}{\rrhDcp}
+\newcommand{\textRubikFc}{\rrhFc}
+\newcommand{\textRubikFcp}{\rrhFcp}
+\newcommand{\textRubikBc}{\rrhBc}
+\newcommand{\textRubikBcp}{\rrhBcp}
+\newcommand{\textRubikCL}{\rrhCL}
+\newcommand{\textRubikCLp}{\rrhCLp}
+\newcommand{\textRubikCR}{\rrhCR}
+\newcommand{\textRubikCRp}{\rrhCRp}
+\newcommand{\textRubikCU}{\rrhCU}
+\newcommand{\textRubikCUp}{\rrhCUp}
+\newcommand{\textRubikCD}{\rrhCD}
+\newcommand{\textRubikCDp}{\rrhCDp}
+\newcommand{\textRubikCF}{\rrhCF}
+\newcommand{\textRubikCFp}{\rrhCFp}
+\newcommand{\textRubikCB}{\rrhCB}
+\newcommand{\textRubikCBp}{\rrhCBp}
+% \end{macrocode}
+%
+%
+%
% --------------------------
% End of this package
% --------------------------
diff --git a/Master/texmf-dist/source/latex/rubik/rubikcube.ins b/Master/texmf-dist/source/latex/rubik/rubikcube.ins
index a50acb88fd4..80a62849b26 100644
--- a/Master/texmf-dist/source/latex/rubik/rubikcube.ins
+++ b/Master/texmf-dist/source/latex/rubik/rubikcube.ins
@@ -5,21 +5,7 @@
%% Authors: RWD Nickalls (dick@nickalls.org)
%% and Apostolos Syropoulos (asyropoulos@yahoo.com)
%%
-%% VERSION 3.0 September 25, 2015
-%% Copyright 2015 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: <http://www.latex-project.org/lppl.txt>
-%%
-%% This work consists of the files listed in the README file.
-%%
-%% This file will generate fast loadable files and documentation
-%% driver files from the doc files in this work when run through
-%% LaTeX.
-%%
+%%
%% --------------- start of docstrip commands ------------------
%%
\def\batchfile{rubikcube.ins}
@@ -31,8 +17,9 @@
Authors: RWD Nickalls (dick@nickalls.org)
and Apostolos Syropoulos (asyropoulos@yahoo.com)
- Copyright 2015 RWD Nickalls and A Syropoulos
+ Copyright 03 March 2017 RWD Nickalls and A Syropoulos
+ VERSION 4.0
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
diff --git a/Master/texmf-dist/source/latex/rubik/rubikexamples.bat b/Master/texmf-dist/source/latex/rubik/rubikexamples.bat
new file mode 100644
index 00000000000..b16f8146e4c
--- /dev/null
+++ b/Master/texmf-dist/source/latex/rubik/rubikexamples.bat
@@ -0,0 +1,3 @@
+ pdflatex --shell-escape rubikexamples.tex
+
+
diff --git a/Master/texmf-dist/source/latex/rubik/rubikpatterns.dtx b/Master/texmf-dist/source/latex/rubik/rubikpatterns.dtx
new file mode 100644
index 00000000000..a6711d471ea
--- /dev/null
+++ b/Master/texmf-dist/source/latex/rubik/rubikpatterns.dtx
@@ -0,0 +1,540 @@
+% \iffalse meta-comment
+%
+% rubikpatterns.dtx
+%
+% version 4.0
+%
+% Authors: RWD Nickalls (dick@nickalls.org)
+% and Apostolos Syropoulos (asyropoulos@yahoo.com)
+%
+% Copyright 03 March 2017 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 rubikpatterns 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{rubikpatterns.sty}{\usepackage{rubikpatterns}}{%
+ \GenericWarning{rubikpatterns.dtx}{Package file rubikpatterns.sty not found.
+ Documentation will be messed up!^^J
+ (Generate rubikpatterns.sty by (La)TeXing rubikpatterns.ins, and then^^J
+ process rubikpatterns.dtx again)^^J}\stop
+}%
+%
+\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{rubikpatterns.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+%
+%
+%%% \CheckSum{187}
+%
+%%% \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 \textsc{rubikpatterns} package}
+%
+% \author{
+% RWD Nickalls (dick@nickalls.org) \\
+% A Syropoulos (asyropoulos@yahoo.com)
+% }
+% \date{This file describes version \RPfileversion\ (\RPfiledate)\\
+% \texttt{www.ctan.org/pkg/rubik}}
+% \maketitle
+%
+% \begin{abstract}
+% The \rubikpatterns\ package is a small data-base of well-known named
+% Rubik patterns and associated rotation sequences, for use in conjunction
+% with the \textsc{rubikcube} and \textsc{rubikrotation} packages. It is part
+% of the Rubik `bundle'.
+% \end{abstract}
+%
+%
+% \tableofcontents
+%
+% \pagebreak
+%
+% \section{Introduction}
+%
+% The \textsc{rubikpatterns} package is a small a data-base of well-known Rubik
+% rotation sequences for use in conjunction with the \textsc{rubikcube}
+% and \textsc{rubikrotation} packages.
+% These sequences, which are well-known and widely available, were sourced from the Rubik-related
+% websites of Reid M and Kociemba H (see References for URLs).
+%
+%
+%
+% \subsection{Installation}
+%
+% Place the file \texttt{rubikpatterns.zip} into a temporary directory, and unzip it.
+% This will generate the following files:
+%\begin{quote}
+% \begin{verbatim}
+% rubikpatterns.ins
+% rubikpatterns.dtx
+% rubikpatterns.pdf --this document
+% rubikpatternsLIST.tex
+% rubikpatternsLIST.pdf
+%\end{verbatim}
+%\end{quote}
+% The package documentation is the file \texttt{rubikpatterns.pdf}.
+% The style option \texttt{rubikpatterns.sty} is generated by running (pdf)\LaTeX\ on
+% the file \texttt{rubikpatterns.ins} as follows:
+%\begin{quote}
+%\begin{verbatim}
+% pdflatex rubikpatterns.ins
+%\end{verbatim}
+%\end{quote}
+% The documentation file (\texttt{rubikpatterns.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 rubikpatterns.dtx
+% pdflatex rubikpatterns.dtx
+% makeindex -s gind.ist rubikpatterns
+% makeindex -s gglo.ist -o rubikpatterns.gls rubikpatterns.glo
+% pdflatex rubikpatterns.dtx
+% pdflatex rubikpatterns.dtx
+%\end{verbatim}
+%\end{quote}
+%
+%
+%
+% \subsubsection{Placing the files}
+% \label{sec:placingfiles}
+%
+% 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/rubik/}
+%{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubik/}
+%
+%\medskip
+%
+%\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.
+%
+%
+%
+% \subsection{Usage}
+% \label{sec:usage}
+% Load the packages \textsc{rubikcube},
+% \textsc{rubikrotation} and \textsc{rubikpatterns} in the \TeX\ file preamble \textit{after} loading
+% the TikZ package; for example, as follows:
+%\begin{quote}
+% \begin{verbatim}
+% \usepackage{tikz}
+% \usepackage{rubikcube,rubikrotation,rubikpatterns}
+%\end{verbatim}
+%\end{quote}
+% Since the sequence macros made available by this package are accessed using commands
+% provided by the \textsc{rubikcube} and \textsc{rubikrotation} packages, please read the
+% documentation of these packages.
+%
+%
+%
+% \section{Rubik patterns}
+%
+% A Rubik pattern is the configuration generated by a sequence of rotations
+% (or `moves') from some initial starting configuration (typically a `solved'
+% configuration). For example, `sixspot' is a well known pattern generated
+% from a solved Rubik cube by the rotation sequence
+% \texttt{U,Dp,R,Lp,F,Bp,U,Dp}, as follows:
+%
+% \bigskip
+%
+% \noindent\begin{minipage}{\textwidth}
+% \centering
+% \ifpdf
+% \includegraphics[height=3cm]{rubikpatterns-doc-figA.pdf}
+% \else
+% \fi
+% \end{minipage}
+%
+% \bigskip
+%
+% {\noindent}The code for the above image is as follows:
+%
+%\begin{verbatim}
+% \noindent\hfil%
+% \RubikCubeSolvedWB%
+% \ShowCube{2.4cm}{0.6}{\DrawRubikCubeRU}%
+% \RubikRotation{\SixSpot}%
+% \quad\SequenceBraceA{sixspot}{\ShowSequence{}{\Rubik}{\SequenceLong}}\quad%
+% \ShowCube{2.4cm}{0.6}{\DrawRubikCubeRU}%
+% \hfil%
+%\end{verbatim}
+%
+% \bigskip
+%
+% Note that the appearance of a pattern generated by a given
+% rotation sequence is, of course, sensitive to (a)~the particular colour
+% configuration of the solved cube used, and (b)~the initial orientation of
+% the Rubik cube.
+%
+%
+% Consequently the appearance generated by a given sequence
+% may appear slightly different from
+% that on some websites, although the colour configuration (pattern's \textit{geometry})
+% will, of course, be the same (isomorphic). You may therefore need
+% to adjust the pre- (and possibly the post-) x,y,z rotations in
+% order to obtain a particular configuration as displayed elsewhere.
+%
+%
+% \subsection{Sequence macros}
+%
+% Each of the rotation sequences of `patterns' made available by the
+% \textsc{rubikpatterns} package is defined in the file \texttt{rubikpatterns.sty}
+% in the following compact macro form.
+% For~example, the rotation sequence associated with the pattern known
+% as `SixSpot' (shown in the figure above) is defined as follows:
+%\begin{verbatim}
+%\newcommand{\SixSpot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>}
+%\newcommand{\sixspot}{\SixSpot}
+%\end{verbatim}
+% The macro name is \verb!\SixSpot! (the lower-case version \verb!\sixspot! can also be used).
+% Note that the second argument which
+% includes the rotation sequence, also includes the pattern name in
+% square brackets \verb![SixSpot]! as the first element in the sequence.
+% Additional metadata (held by the macro \verb!\SequenceInfo!) is appended
+% in angle brackets (separated by a comma) as follows: \verb!<(8q*, 8f*)>!.
+% For details see the \textsc{rubikrotation} package documentation.
+%
+%
+%
+% \subsection{List of macros}
+%
+% The following is a list of the macro names of all the Rubik patterrns supplied by
+% the \textsc{rubikpatterns} package. Note that for convenience each macro-name listed
+% has an equivalent lower-case version. See the companion file \texttt{rubikpatternsLIST.pdf}
+% for a detailed list showing each pattern and its associated
+% sequence\,\footnote{We show all these images in a separate
+% file (\texttt{rubikpatternsLIST.pdf}) purely because generating them requires
+% using the \LaTeX\ command-line option \texttt{--shell-escape} in conjunction
+% with the \textsc{rubikrotation} package.}.
+%
+% All the pattern names encoded here (as macros) are well-known and widely available.
+% However, some pattern names have been slightly modified
+% in order to avoid spaces and to keep them as similar to the original as possible.
+% On finding different sequences which generate the same pattern, then the
+% shortest sequence has been selected (they can be readily distinguished by their metadata).
+%
+% Finally, we note that there is a serious need for a standardised one-word nomenclature
+% in order to avoid confusion, and to facilitate computerisation and an electronic database.
+% Such a notation also needs to accommodate those sequence variations which generate the same pattern.
+% We welcome suggestions and/or help for improvement.
+
+%
+%\begin{verbatim}
+% \PonsAsinorum
+% \CheckerboardsThree
+% \CheckerboardsSix
+% \Stripes
+% \CubeInCube
+% \CubeInCubeInCube
+% \ChristmasCross
+% \PlummersCross
+% \Anaconda
+% \Python
+% \BlackMamba
+% \GreenMamba
+% \FemaleRattlesnake
+% \MaleRattlesnake
+% \FemaleBoa
+% \MaleBoa
+% \FourSpot
+% \SixSpot
+% \OrthogonalBars
+% \SixTs
+% \SixTwoOne
+% \ExchangedPeaks
+% \TwoTwistedPeaks
+% \FourTwistedPeaks
+% \ExchangedChickenFeet
+% \TwistedChickenFeet
+% \ExchangedRings
+% \TwistedRings
+% \EdgeHexagonTwo
+% \EdgeHexagonThree
+% \TomParksPattern
+% \RonsCubeInCube
+% \TwistedDuckFeet
+% \ExchangedDuckFeet
+% \Superflip
+%\end{verbatim}
+%
+% Note that the particular superflip sequence made available by this package
+% (shown in \texttt{rubikpatternsLIST.pdf}) is due to Reid (1995), and is detailed
+% on the Kociemba webpage \texttt{http://www.kociemba.org/math/oh.htm}. Indeed, this was the
+% first sequence to define the `20-move' (HTM) upper boundary for solving a Rubik cube
+% (see Rokicki \textit{et~al.}, 2013).
+%
+% The superflip configuration is also significant since it is its own inverse.
+% For example, the following two \verb!\RubikRotation! commands will generate the same
+% configuration (starting from a solved cube):
+%\begin{verbatim}
+% \RubikRotation{\superflip}
+% \RubikRotation{\superflip,<inverse>}
+%\end{verbatim}
+% This property is shown as one of the examples in the Rubik bundle file \texttt{rubikexamples.pdf}.
+%
+%
+%
+% \section{Change history}
+%
+% \begin{itemize}
+%
+% \item Version 4.0 (March 2017)
+%
+% --- First release of this package.
+%
+% \end{itemize}
+%
+%
+%
+% \section{References}
+% \label{sec:references}
+%
+%\begin{itemize}
+%
+% \item Fridrich website (Fridrich J).
+% See the `Pretty patterns' webpage \url{http://www.ws.binghamton.edu/fridrich/ptrns.html}
+%
+% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm}
+% {\newline}---for superflip see: \url{http://www.kociemba.org/math/oh.htm}
+%
+% \item Randelshofer website (Randelshofer W). Pretty patterns.
+% \url{http://www.randelshofer.ch/rubik/patterns/U080.01.html}
+%
+% \item Reid M. \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html}
+%
+% \item Reid M. (1995). Superflip requires 20 face turns. (January 1995)
+% \url{http://www.math.ucf.edu/~reid/Rubik/CubeLovers/}
+% (see Section~\ref{sec:superflip})
+% {\newline}[cited from Rokicki \textit{et~al.}, 2013].
+% {\newline}(Note: easier to use is the following html indexed version of the
+% archive of the Cube-Lovers usenet group (1982--1997)
+% \url{http://www.math.rwth-aachen.de/~Martin.Schoenert/Cube-Lovers/})
+%
+% \item Rokicki T, Kociemba H, Davidson M and Dethridge J (2013). The diameter of the Rubik's
+% cube is twenty. \textit{SIAM.\ J.\ Discrete Math.}, \textbf{27}, 1082--1105.
+% \url{http://tomas.rokicki.com/rubik20.pdf}
+%
+%\end{itemize}
+%
+%
+%
+%
+% ^^A ==================================================
+% \StopEventually{\PrintIndex}
+%
+%
+%
+% \section[The code]{The code (\texttt{rubikpatterns.sty})}
+%
+%
+% \subsection{Package heading}
+% \label{sec:CodePackageHeading}
+%
+% \begin{macrocode}
+%<*rubikpatterns>
+\def\RPfileversion{4.0}%
+\def\RPfiledate{2017/03/03}%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{rubikpatterns}[\RPfiledate\space (v\RPfileversion)]
+% \end{macrocode}
+%
+%
+% \begin{macro}{\rubikpatterns}
+% First we create a suitable logo
+% \begin{macrocode}
+\newcommand{\rubikpatterns}{\textsc{rubikpatterns}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Patterns}
+% \label{sec:patternscode}
+%
+%
+%
+%
+% \subsubsection{Superflip}
+% \label{sec:superflip}
+%
+% This particular superflip sequence is from the Kociemba website (his Oh webpage).
+% It is due to Reid (1995).
+% \begin{macrocode}
+\newcommand{\Superflip}{[Superflip],Dp,R2,Fp,D2,F2,U2,Lp,R,Dp,R2,B,F,Rp,%
+U2,Lp,F2,Rp,U2,Rp,Up,<(20f*)>}%
+\newcommand{\superflip}{\Superflip}
+% \end{macrocode}
+%
+%
+% \subsubsection{Reid data}
+%
+% These named sequences are derived from the Reid website.
+% \begin{macrocode}
+\newcommand{\PonsAsinorum}{[PonsAsinorum],F2,B2,R2,L2,U2,D2,<(12q*, 6f*)>}%
+\newcommand{\ponsasinorum}{\PonsAsinorum}%
+\newcommand{\CheckerboardsThree}%
+{[CheckerboardsThree],F,B2,Rp,D2,B,R,U,Dp,R,Lp,Dp,Fp,R2,D,F2,Bp,<(20q*, 16f*), order 3>}%
+\newcommand{\checkerboardsthree}{\CheckerboardsThree}%
+\newcommand{\CheckerboardsSix}%
+{[CheckerboardsSix],R2,L2,U,B,L2,Dp,F,B2,R,Lp,Fp,B,R,D,F2,Lp,Up,<(17f*, 22q), order 6>}%
+\newcommand{\checkerboardssix}{\CheckerboardsSix}%
+\newcommand{\Stripes}{[Stripes],F,U,F,R,L2,B,Dp,R,D2,L,Dp,B,R2,L,F,U,F,<(20q*, 17f*)>}%
+\newcommand{\stripes}{\Stripes}%
+\newcommand{\CubeInCube}{[CubeInCube],F,L,F,Up,R,U,F2,L2,Up,Lp,B,Dp,Bp,L2,U,<(18q*, 15f*)>}%
+\newcommand{\cubeincube}{\CubeInCube}%
+\newcommand{\CubeInCubeInCube}%
+{[CubeInCubeInCube],Fp,U,Bp,Rp,U,F2,U2,Fp,Up,F,U2,D,Bp,Dp,R2,B2,Up,<(17f*, 22q)>}%
+\newcommand{\cubeincubeincube}{\CubeInCubeInCube}%
+\newcommand{\ChristmasCross}{[ChristmansCross],U,F,Bp,L2,U2,L2,Fp,B,U2,L2,U,<(16q*, 11f*)>}%
+\newcommand{\christmascross}{\ChristmansCross}%
+\newcommand{\PlummersCross}%
+{[PlummersCross],R2,Lp,D,F2,Rp,Dp,Rp,L,Up,D,R,D,B2,Rp,U,D2,<(20q*, 16f*)>}%
+\newcommand{\plummerscross}{\PlummersCross}%
+\newcommand{\Anaconda}{[Anaconda],L,U,Bp,Up,R,Lp,B,Rp,F,Bp,D,R,Dp,Fp,<(14q*, 14f*)>}%
+\newcommand{\anaconda}{\Anaconda}%
+\newcommand{\Python}{[Python],F2,Rp,Bp,U,Rp,L,Fp,L,Fp,B,Dp,R,B,L2,<(16q*, 14f*)>}%
+\newcommand{\python}{\Python}%
+\newcommand{\BlackMamba}{[BlackMamba],R,D,L,Fp,R,Lp,D,Rp,U,Dp,B,Up,Rp,Dp,<(14q*, 14f*)>}%
+\newcommand{\blackmamba}{\BlackMamba}%
+\newcommand{\GreenMamba}{[GreenMamba],R,D,R,F,Rp,Fp,B,D,Rp,Up,Bp,U,D2,<(14q*, 13f*)>}%
+\newcommand{\greenmamba}{\GreenMamba}%
+\newcommand{\FemaleRattlesnake}%
+{[FemaleRattlesnake],U2,Dp,L2,D,B,U,Bp,Rp,L2,U2,F,Up,F,R,<(18q*, 14f*)>}%
+\newcommand{\femalerattlesnake}{\FemaleRattlesnake}%
+\newcommand{\MaleRattlesnake}%
+{[MaleRattlesnake],Rp,Fp,U,Fp,U2,R,L2,B,Up,Bp,Dp,L2,U2,D,<(18q*, 14f*)>}%
+\newcommand{\malerattlesnake}{\MaleRattlesnake}%
+\newcommand{\FemaleBoa}{[FemaleBoa],R,Up,R2,U2,F,D2,R2,Up,Dp,R,Dp,Fp,<(16q*, 12f*)>}%
+\newcommand{\femaleboa}{\FemaleBoa}%
+\newcommand{\MaleBoa}{[MaleBoa],F,D,Rp,U,D,R2,D2,Fp,U2,R2,U,Rp,<(16q*, 12f*)>}%
+\newcommand{\maleboa}{\MaleBoa}%
+\newcommand{\FourSpot}{[FourSpot],F2,B2,U,Dp,R2,L2,U,Dp,<(12q*, 8f*)>}%
+\newcommand{\fourspot}{\FourSpot}%
+\newcommand{\SixSpot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>}%
+\newcommand{\sixspot}{\SixSpot}%
+\newcommand{\OrthogonalBars}%
+{[OrthogonalBars],F,Rp,U,L,Fp,Lp,F,Up,R,U,Lp,Up,L,Fp,<(14q*, 14f*)>}%
+\newcommand{\orthogonalbars}{\OrthogonalBars}%
+\newcommand{\SixTs}{[SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*, 9f*)>}%
+\newcommand{\sixts}{\SixTs}%
+\newcommand{\SixTwoOne}{[SixTwoOne],U,B2,D2,L,Bp,Lp,Up,Lp,B,D2,B2,<(15q*, 11f*)>}%
+\newcommand{\sixtwoone}{\SixTwoOne}%
+\newcommand{\ExchangedPeaks}%
+{[ExchangedPeaks],F2,R2,D,R2,U,D,F2,Dp,Rp,Dp,F,L2,Fp,D,R,Up,<(16f*, 21q)>}%
+\newcommand{\exchangedpeaks}{\ExchangedPeaks}%
+\newcommand{\TwoTwistedPeaks}%
+{[TwoTwistedPeaks],F,D2,B,R,Bp,Lp,F,Dp,L2,F2,R,Fp,Rp,F2,Lp,Fp,<(16f*, 20q)>}%
+\newcommand{\twotwistedpeaks}{\TwoTwistedPeaks}%
+\newcommand{\FourTwistedPeaks}%
+{[FourTwistedPeaks],Up,D,B,Rp,F,R,Bp,Lp,Fp,B,L,F,Rp,Bp,R,Fp,Up,D,<(18q*, 18f*)>}%
+\newcommand{\fourtwistedpeaks}{\FourTwistedPeaks}%
+\newcommand{\ExchangedChickenFeet}%
+{[ExchangedChickenFeet],F,Lp,Dp,Bp,L,F,U,Fp,Dp,F,L2,Bp,Rp,U,L2,Dp,F,<(19q*, 17f*)>}%
+\newcommand{\exchangedchickenfeet}{\ExchangedChickenFeet}%
+\newcommand{\TwistedChickenFeet}%
+{[TwistedChickenFeet],F,Lp,D,Fp,Up,B,U,F,Up,F,Rp,F2,L,Up,Rp,D2,<(18q*, 16f*)>}%
+\newcommand{\twistedchickenfeet}{\TwistedChickenFeet}%
+\newcommand{\ExchangedRings}%
+{[ExchangedRings],F,U,Dp,Lp,B2,L,Up,D,F,U,R2,L2,Up,L2,F2,<(15f*, 20q)>}%
+\newcommand{\exchangedrings}{\ExchangedRings}%
+\newcommand{\TwistedRings}%
+{[TwistedRings],F,D,Fp,D2,Lp,Bp,U,L,D,R,U,Lp,Fp,U,L,U2,<(18q*, 16f*)>}%
+\newcommand{\twistedrings}{\TwistedRings}%
+\newcommand{\EdgeHexagonTwo}%
+{[EdgeHexagonTwo],U,B2,Up,Fp,Up,D,Lp,D2,L,U,Dp,F,Dp,L2,B2,Dp,<(20q*, 16f*) order2>}%
+\newcommand{\edgehexagontwo}{\EdgeHexagonTwo}%
+\newcommand{\EdgeHexagonThree}%
+{[EdgeHexagonThree],F,L,B,U,L,F2,B2,Rp,F2,B2,Up,Bp,Lp,Fp,<(14f*, 18q) order 3>}%
+\newcommand{\edgehexagonthree}{\EdgeHexagonThree}%
+\newcommand{\TomParksPattern}%
+{[TomParksPattern],L,U,F2,R,Lp,U2,Bp,U,D,B2,L,F,Bp,Rp,L,Fp,R,<(20q*, 17f*)>}%
+\newcommand{\tomparkspattern}{\TomParksPattern}%
+\newcommand{\RonsCubeInCube}%
+{[RonsCubeInCube],L2,D2,Lp,D2,B2,L2,B2,Lp,D2,L2,B2,Lp,B2,<(13f*, 23q)>}%
+\newcommand{\ronscubeincube}{\RonsCubeInCube}%
+\newcommand{\TwistedDuckFeet}%
+{[TwistedDuckFeet],F,Rp,B,R,U,Fp,Lp,Fp,U2,Lp,Up,D2,B,Dp,F,Bp,U2,<(20q*, 17f*)>}%
+\newcommand{\twistedduckfeet}{\TwistedDuckFeet}%
+\newcommand{\ExchangedDuckFeet}%
+{[ExchangedDuckFeet],U,F,R2,Fp,Dp,R,U,B2,U2,Fp,R2,F,D,B2,R,Bp,<(21q*, 16f*)>}%
+\newcommand{\exchangedduckfeet}{\ExchangedDuckFeet}%
+% \end{macrocode}
+% --------------------------
+% End of this package
+% --------------------------
+% \begin{macrocode}
+%</rubikpatterns>
+% \end{macrocode}
+%
+%
+%
+%
+% \Finale
+%
+\endinput
+
+
+
+
+
diff --git a/Master/texmf-dist/source/latex/rubik/rubikpatterns.ins b/Master/texmf-dist/source/latex/rubik/rubikpatterns.ins
new file mode 100644
index 00000000000..9260827909b
--- /dev/null
+++ b/Master/texmf-dist/source/latex/rubik/rubikpatterns.ins
@@ -0,0 +1,65 @@
+%% rubikpatterns.ins
+%%
+%% version 4.0
+%%
+%% --- automatic overwriting of .sty is disabled-------
+%% =========================================================
+%%
+%% --------------- start of docstrip commands ------------------
+%%
+\def\batchfile{rubikpatterns.ins}
+\input docstrip.tex
+
+\preamble
+
+-----------------------------------------------------------------
+ Authors: RWD Nickalls (dick@nickalls.org)
+ and Apostolos Syropoulos (asyropoulos@yahoo.com)
+
+ Copyright March 03, 2017 RWD Nickalls and A Syropoulos
+
+ VERSION 4.0
+
+ 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: <http://www.latex-project.org/lppl.txt>
+
+ This work consists of the files listed in the README file.
+-----------------------------------------------------------------
+
+ This is a LaTeX/TikZ package for drawing Rubik cubes
+ Please report errors or suggestions for improvement to
+
+ RWD Nickalls (dick@nickalls.org)
+ Apostolos Syropoulos (asyropoulos@yahoo.com)
+
+ This package requires the basic TikZ package to be loaded already
+------------------------------------------------------------------
+\endpreamble
+
+\keepsilent %%disables most of the screen output
+%% \askforoverwritefalse %%enables automatic overwriting of .sty
+\generate{\file{rubikpatterns.sty}{\from{rubikpatterns.dtx}{rubikpatterns}}}
+
+%%now write a screen message for the user
+\obeyspaces
+\Msg{*******************************************************}
+\Msg{* *}
+\Msg{* To finish the installation you have to move the *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{* *}
+\Msg{* rubikpatterns.sty *}
+\Msg{* *}
+\Msg{* To produce the documentation run the file *}
+\Msg{* rubikpatterns.dtx through LaTeX. *}
+\Msg{* For an index, process any filename.idx file by *}
+\Msg{* makeindex -s gind.ist filename *}
+\Msg{* For list of changes, process any filename.glo file *}
+\Msg{* makeindex -s gglo.ist -o filename.gls filename.glo *}
+\Msg{* *}
+\Msg{* Happy TeXing! *}
+\Msg{*******************************************************}
+
+\endbatchfile
+%%------------EOF---------------
diff --git a/Master/texmf-dist/source/latex/rubik/rubikpatternsLIST.bat b/Master/texmf-dist/source/latex/rubik/rubikpatternsLIST.bat
new file mode 100644
index 00000000000..a8e9b92cd13
--- /dev/null
+++ b/Master/texmf-dist/source/latex/rubik/rubikpatternsLIST.bat
@@ -0,0 +1,3 @@
+ pdflatex --shell-escape rubikpatternsLIST.tex
+
+
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
index 57302ac37a7..2b554ef7128 100644
--- a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
+++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
@@ -1,12 +1,12 @@
% \iffalse meta-comment
% rubikrotation.dtx
%
-% version 3.0
+% version 4.0
%
-% Authors: RWD Nickalls (dick@nickalls.org)
+% Authors: RWD Nickalls (dick@nickalls.org)
% and Apostolos Syropoulos (asyropoulos@yahoo.com)
-% Copyright 25 September 2015 RWD Nickalls + A Syropoulos
+% Copyright 03 March 2017 RWD Nickalls + A Syropoulos
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
@@ -58,7 +58,7 @@
%
%
%
-% \CheckSum{310}
+%%% \CheckSum{322}
%
%%% \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
@@ -78,7 +78,9 @@
%
%
%
-% \title{The \rubikrotation\ package}
+% \title{%
+% \ifpdf\pdfbookmark[1]{Title}{Title}\else\fi%
+% The \rubikrotation\ package}
%
% \author{
% RWD Nickalls (dick@nickalls.org) \\
@@ -91,49 +93,49 @@
% \begin{abstract}
% 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
+% 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 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).
+% The \rubikrotation\ package also provides commands for saving the cube state
+% to a file (\cmd{\SaveRubikState}), and for displaying any
+% errors (\cmd{\ShowRubikErrors}).
% \end{abstract}
-%
+%
+%
% \begin{minipage}{11cm}
% \centering
% \ifpdf
-% \includegraphics[width=10cm]{Rubikrot-doc-figD.pdf}
+% \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} package.
% It consists of a style option (\texttt{rubikrotation.sty}), a
-% Perl script (\texttt{rubikrotation.pl}) and some examples.
+% 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, this
-% package requires the use of the \texttt{--shell-escape} switch to allow
-% command-line control of the Perl script, which is really the `engine' of this package.
+% 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 (with MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl'
+% 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 (Mandriva using
-% {\TeX}Live), and on a Solaris platform (OpenIndiana).
+% environment of Unix/Linux systems.}), on a Linux platform (Debian v8.2.0,
+% {\TeX}Live 2016, and Perl v5.20.2), and on a Solaris platform (OpenIndiana).
%
% The following commands are made available by \texttt{rubikrotation.sty}:
% \begin{quote}
@@ -142,6 +144,10 @@
% \SaveRubikState
% \CheckRubikState
% \ShowRubikErrors
+% \SequenceName
+% \SequenceInfo
+% \SequenceShort
+% \SequenceLong
%\end{verbatim}
% \end{quote}
%
@@ -164,21 +170,15 @@
% 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
+% 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}
-% 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 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:
@@ -189,7 +189,7 @@
%\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}
+% 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}
@@ -232,7 +232,7 @@
% file is named \texttt{rubikrotation.cfg}.
%
%\medskip
-%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this file
+%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this manual file
% (\texttt{rubikrotation.1}) would be typically located in the
% directory \verb!/usr/share/man/man1!.
%
@@ -251,7 +251,7 @@
%\end{quote}
% which should generate something like the following:
% \begin{verbatim}
-% This is rubikrotation version 3.0
+% This is rubikrotation version 4.0
% Usage: rubikrotation [-h] -i <input file> [-o <out file>]
% where,
% [-h] gives this help listing
@@ -264,27 +264,31 @@
%
% \section{Usage}
% \label{sec:usage}
-% Load the packages \texttt{rubikcube.sty}
-% 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:
+% Load the packages \texttt{rubikcube.sty},
+% \texttt{rubikrotation.sty} and \texttt{rubikpatterns.sty} in the \TeX\ file
+% preamble \textit{after} loading the TikZ package (all the Rubik packages
+% require the TikZ package); for example, as follows:
%\begin{quote}
% \begin{verbatim}
% \usepackage{tikz}
-% \usepackage{rubikcube,rubikrotation}
+% \usepackage{rubikcube,rubikrotation,rubikpatterns}
%\end{verbatim}
%\end{quote}
-% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line switch
+% 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 enable the \TeX\ `write18' facility (so it can run the Perl script)
-% it is necessary to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch
-% as follows:
+% 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
+% pdflatex --shell-escape filename.tex
%\end{verbatim}
%\end{quote}
% In practice, it is probably most convenient to run this command via a
@@ -298,34 +302,18 @@
% acroread filename.pdf &
%\end{verbatim}
%\end{quote}
-%
-%
-% \subsection{Test file}
-%
-% 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-rot.tex (shows 8 worked examples)
-%\end{verbatim}
-%\end{quote}
-% This file needs to be run using \texttt{--shell-escape} switch; for example:
-%\begin{quote}
-% \begin{verbatim}
-% pdflatex --shell-escape example-rot.tex
-%\end{verbatim}
-%\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:
+% If the \LaTeX\ engine is Lua\LaTeX, e.g.,
%\begin{quote}
% \begin{verbatim}
-% bash example-rot.sh
+% lualatex --shell-escape filename.tex
%\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.
+%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}
@@ -350,9 +338,9 @@
% 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,
+% For~the \rubikrotation\ package there are two particular macros we may wish to adjust.
+% 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~default definitions in \texttt{rubikrotation.sty} (which assume the Perl
% script is executable), are as follows: (they are detailed in
@@ -364,8 +352,8 @@
% -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
+% 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. The following examples
% illustrate how the configuration-file may be used.
%
@@ -374,7 +362,8 @@
% 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:
+% (it \textit{must} be named exactly \texttt{rubikrotation.cfg}) and contains just
+% the following line:
%\begin{quote}
%\begin{verbatim}
%\renewcommand{\rubikperlname}{rubikrotationR77}
@@ -387,7 +376,8 @@
% 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:
+% 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}
@@ -395,8 +385,11 @@
% -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.
+%{\noindent}Remember to make sure the PATH associated with the command is also correct.
+%
+%
+%{\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
@@ -422,7 +415,7 @@
% \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
+% 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}
@@ -430,72 +423,257 @@
% (see the notes on this command below).
%
%
-% \subsection[RubikRotation command]{\cmd{\RubikRotation} command}
-% \label{sec:rubikrotationcmd}
+%
+%
+% \subsection[RubikRotation]{\cmd{\RubikRotation} command}
+% \label{sec:rubikrotationcmd}
%
% \DescribeMacro{\RubikRotation}
-% 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.
+% 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).
+%
+%
+% 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}
-% \RubikCubeSolved % sets up the colours for a solved cube state
-% \RubikRotation{R2,L,U,D}
-% \begin{tikzpicture}[scale=0.7]
-% \DrawRubikCubeRU
-% \end{tikzpicture}%
+% \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}
-% The \cmd{\RubikRotation} command results in \LaTeX\ first writing
+%
+%
+% \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 any error messages) to the file \texttt{rubikstateNEW.dat},
-% 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:
+% 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}
-% \RubikRotation[3]{x,R,U}
-% \RubikRotation{x,R,U,x,R,U,x,R,U}
+% \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}
+% \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.
+% 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, we can use the name `sixspot' for a macro denoting the rotation sequence
+% 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 refs Section~\ref{sec:references}\,], as follows:
+% Reid website)[\,see refs 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}
+% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>}
%\end{verbatim}
%\end{quote}
-% With this new \cmd{\sixspot} command we are now able to generate the graphic (sixspot cube)
+% 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}{6cm}
+% \begin{minipage}{7cm}
% \begin{verbatim}
+% \usepackage{rubikcube,rubikrotation}
+% \usepackage{rubikpatterns}
+% ...
% \RubikCubeSolved
% \RubikRotation{\sixspot}
% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU}
@@ -504,7 +682,7 @@
% \begin{minipage}{3.4cm}
% \centering
% \ifpdf
-% \includegraphics[height=3cm]{Rubikrot-doc-figA.pdf}
+% \includegraphics[height=3cm]{rubikrot-doc-figA.pdf}
% \else
% \fi
% \end{minipage}
@@ -515,87 +693,75 @@
% and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!.
%
%
-% \subsubsection{Arguments prefixed with *, [, ]}
+% \subsubsection{Arguments in square brackets }
% \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.
+% 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 label the `sixspot' configuration mentioned above,
+% 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}
+% \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 feature in the \cmd{\sixspot} command, as follows,
+% 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}
+% \newcommand{\sixspot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp}
%\end{verbatim}
%\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,
+% 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{x2,y,\sixspot}
+% \RubikRotation{\sixspot,x2,y}
%\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 ...
-% ...rotation x OK (= rrR + rrSr + rrLp)
-% ...rotation x OK (= rrR + rrSr + rrLp)
-% ...rotation y OK (= rrU + rrSu + rrDp)
-% ...[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
+% ...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}
-% In this way, several named rotation sequences can be easily distinguished
-% in the log file from adjacent rotation sequences.
+% 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.
%
-% 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.
+% 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}
%
@@ -604,7 +770,8 @@
% 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$,
+% 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
@@ -613,7 +780,7 @@
% \begin{minipage}{11cm}
% \centering
% \ifpdf
-% \includegraphics[width=10cm]{Rubikrot-doc-figC.pdf}
+% \includegraphics[width=10cm]{rubikrot-doc-figC.pdf}
% \else
% \fi
% \end{minipage}
@@ -623,30 +790,31 @@
%
% The \cmd{\RubikRotation} command can also be used to scramble the
% cube using a random sequence of rotations. If the first argument
-% is the lowercase word `random' \textsc{and} the second argument
+% is the lower-case 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; otherwise a default value
% of 50 is used (for example, if the second argument is not an integer).
% 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
+% 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 will scramble a solved cube using a
+% 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 cube.
+% a semi-flat (SF) cube.
%
% \begin{minipage}{3.4cm}
% \centering
% \ifpdf
-% \includegraphics[height=4cm]{Rubikrot-doc-figB.pdf}
+% \includegraphics[height=4cm]{rubikrot-doc-figB.pdf}
% \else
% \fi
% \end{minipage}
@@ -655,7 +823,7 @@
%\begin{verbatim}
% \RubikCubeSolved%
% \RubikRotation{random,120}%
-% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeFlat}
+% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeSF}
%\end{verbatim}
% \end{minipage}
%
@@ -691,7 +859,7 @@
%\begin{quote}
%\begin{verbatim}
% \RubikCubeSolved%
-% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}%
+% \RubikRotation{U,Dp,R,Lp,F,Bp,U,Dp}%
% \SaveRubikState{sixspot.tex}%
%\end{verbatim}
%\end{quote}
@@ -709,12 +877,12 @@
% \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:
+% 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}{\DrawRubikCubeFlat}
+%\ShowCube{7cm}{0.7}{\DrawRubikCubeSF}
%\end{verbatim}
%\end{quote}
%
@@ -724,7 +892,7 @@
% \DescribeMacro{\CheckRubikState}
% Since it is easy to inadvertently define an invalid Rubik cube
% (e.g.,~enter an invalid number of, say, yellow facelets), this command
-% checks the current colour state of all the cubies
+% 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~6.
% The results are written to the the \texttt{.log} file, and displayed under
@@ -736,7 +904,9 @@
% \CheckRubikState%
%\end{verbatim}
%\end{quote}
-% Note that such a check is implemented automatically with each \cmd{\RubikRotation} command.
+% Note (1)~that such a check is implemented automatically with each \cmd{\RubikRotation}
+% command, and (2)~this is actually only a very superficial check---simply counting the number
+% of cubies of each colour.
%
%
%
@@ -758,6 +928,7 @@
% 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}
%
%
@@ -780,21 +951,22 @@
%
%
% \section{General overview}
-% \label{generaloverview}
-% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps
-% are implemented.
-% \begin{itemize}
+% \label{generaloverview}
%
+% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps
+% are implemented.
+% \begin{itemize}
%
% \item[1.] A check is made to see if \texttt{fancyvrb.sty} is loaded: if not
-% then this package is loaded if it is available (this package is required
-% for inputting the file \texttt{rubikstateERRORS.dat}).
+% 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' file being used by \LaTeX).
+% \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.
@@ -804,14 +976,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}).
+% \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 would be as follows:
+% \texttt{rubikstate.dat} file will be written as follows:
%\begin{quote}
% \begin{verbatim}
% % filename: rubikstate.dat
@@ -826,12 +998,12 @@
% rotation,U,D,L,R
%\end{verbatim}
%\end{quote}
-% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the line \texttt{rotation,U,D,L,R}
+% 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:
+% would be the string ``\texttt{rotation,random,45}'', as follows:
%\begin{quote}
% \begin{verbatim}
% % filename: rubikstate.dat
@@ -846,29 +1018,31 @@
%\end{verbatim}
%\end{quote}
% A \cmd{\CheckRubikState} command triggers the same sequence of events except
-% no `rotation' line is written.
+% 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 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$,
+% 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
+% 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.
+% 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 \cmd{\Draw...} command
-% of some form is reached and the final rubikstate is drawn in a TikZ picture
-% environment.
+% (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{\ShowRubikErrors} command,
% then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed
@@ -911,13 +1085,22 @@
% \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.
+% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package, v3.0.
% \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}\,]
%
+% \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}
%
%
@@ -925,6 +1108,27 @@
% \section{Change history}
%
% \begin{itemize}
+%
+% \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
@@ -932,7 +1136,7 @@
% \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}
+% --- 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}).
%
@@ -940,7 +1144,8 @@
% 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.
+% --- 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 filenames
% those specified in the command-line of the CALLing program. This now allows the
@@ -964,7 +1169,7 @@
%
%
%
-% \section{The code (\texttt{rubikrotation.sty})}
+% \section[The code]{The code (\texttt{rubikrotation.sty})}
%
% {\noindent}In the following, the term `Perl script' denotes the script
% \texttt{rubikrotation.pl}. Useful information regarding the
@@ -973,11 +1178,12 @@
% Abrahams \textit{et.~al} (1990).
%
% \subsection{Package heading}
+% \label{sec:CodePackageHeading}
%
% \begin{macrocode}
%<*rubikrotation>
-\def\RRfileversion{3.0}%
-\def\RRfiledate{2015/09/25}%
+\def\RRfileversion{4.0}%
+\def\RRfiledate{2017/03/03}%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)]
% \end{macrocode}
@@ -994,7 +1200,7 @@
%
%
%
-% {\noindent}The \rubikrotation\ package requires access to the fancyvrb package
+% {\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:showrubikerrors}).
% \begin{macrocode}
@@ -1004,6 +1210,24 @@
\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}
@@ -1059,30 +1283,30 @@
\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
-% (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
+% 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 from the file \texttt{rubikstateNEW.dat}.
+% 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} command following the \LaTeX\ backslash
-% command in order to generate the mandatory space between it and the first
-% command-line argument).
+% 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
@@ -1094,7 +1318,7 @@
%
% 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.
+% macros and \textit{before} creating the \texttt{rubikstateERRORS.dat} file.
% \begin{macrocode}
\typeout{---checking for config file (rubikrotation.cfg)...}
\IfFileExists{rubikrotation.cfg}{%
@@ -1139,7 +1363,7 @@
\newwrite\outfile%
\immediate\openout\outfile=rubikstateERRORS.dat%
\@print{\@comment rubikstateERRORS.dat}%
-\@print{\@comment ---(RR.sty v\RRfileversion): comments output by Perl script}%
+\@print{\@comment --------------------}%
\immediate\closeout\outfile%
% \end{macrocode}
%
@@ -1184,7 +1408,7 @@
% 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
+% 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.
@@ -1256,10 +1480,12 @@
% 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
+% 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 an optional argument facility we use two macros
+% 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:
@@ -1286,8 +1512,9 @@
% the command to write the main argument to the output data file.
% \begin{macrocode}
\newcommand{\RubikRotation}[2][1]{%
+ \typeout{---TeX process (rubikrotation.sty)-------}%
\typeout{---NEW rotation command------------------}%
- \typeout{---command = RubikRotation{#1}}%
+ \typeout{---command = RubikRotation[#1]{#2}}%
\typeout{---writing current Rubik state to file rubikstate.dat}%
\@openstatefile% open data file
\@print{\@comment filename: rubikstate.dat}%
@@ -1299,14 +1526,20 @@
\@countingloop{\ourRRcounter} in 1:{#1}{%
\immediate\write\outfile{rotation,#2}}%
\@closestatefile% close data file
- \typeout{---running Perl script (rubikrotation)}%
+ \typeout{---CALLing Perl script (rubikrotation.pl)}%
\immediate\write18{\rubikperlcmd}%
- \typeout{---inputting NEW datafile (written by Perl script)}%
+ \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{ShowRubikErrors command}
@@ -1314,11 +1547,13 @@
%
% \begin{macro}{\ShowRubikErrors}
% This command inputs the file \texttt{rubikstateERRORS.dat}.
+% Also made a more convenient synonym = \cmd{\ShowErrors}.
% \begin{macrocode}
\newcommand{\ShowRubikErrors}{%
\typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}%
\VerbatimInput{rubikstateERRORS.dat}%
}
+\newcommand{\ShowErrors}{\ShowRubikErrors}
% \end{macrocode}
% \end{macro}
%
@@ -1340,9 +1575,9 @@
\@print{\@comment filename: rubikstate.dat}%
\@printrubikstate%
\@closestatefile% close data file
- \typeout{---running Perl script (rubikrotation)}%
+ \typeout{---running Perl script (rubikrotation.pl)}%
\immediate\write18{\rubikperlcmd}%
- \typeout{---inputting NEW datafile (written by Perl script)}%
+ \typeout{---inputting NEW datafile (data written by Perl script)}%
\input{rubikstateNEW.dat}%
\typeout{-----------------------------------------}%
}
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.ins b/Master/texmf-dist/source/latex/rubik/rubikrotation.ins
index 99384f15aa4..0c2aed56982 100644
--- a/Master/texmf-dist/source/latex/rubik/rubikrotation.ins
+++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.ins
@@ -1,26 +1,9 @@
%% rubikrotation.ins
%%
-%% version 3.0
+%% version 4.0
%%
%% --- automatic overwriting of .sty is disabled-------
%% =========================================================
-%% Authors: RWD Nickalls (dick@nickalls.org)
-%% and
-%% Apostolos Syropoulos (asyropoulos@yahoo.com)
-%%
-%% 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
-%% version 1.3c of this license or (at your option) any
-%% later version: <http://www.latex-project.org/lppl.txt>
-%%
-%% This work consists of the files listed in the README file.
-%%
-%% This file will generate fast loadable files and documentation
-%% driver files from the doc files in this work when run through
-%% LaTeX.
%%
%% --------------- start of docstrip commands ------------------
%%
@@ -33,8 +16,9 @@
Authors: RWD Nickalls (dick@nickalls.org)
and Apostolos Syropoulos (asyropoulos@yahoo.com)
- Copyright 25 September 2015 RWD Nickalls and A Syropoulos
+ Copyright 03 March 2017 RWD Nickalls and A Syropoulos
+ VERSION 4.0
This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either