summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
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/latex/rubik/rubikrotation.dtx
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/latex/rubik/rubikrotation.dtx')
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikrotation.dtx715
1 files changed, 475 insertions, 240 deletions
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{-----------------------------------------}%
}