Debian Codegraph @

texmf-dist/source/latex/rubik/rubikrotation.dtx

raw
1 % \iffalse meta-comment
2 % rubikrotation.dtx
3 %
4 % version 5.0
5 %
6 %
7 % Authors: RWD Nickalls ([email protected])
8 % and Apostolos Syropoulos ([email protected])
9 %
10 % Copyright 25 February 2018 RWD Nickalls + A Syropoulos
11 %
12 % This work may be distributed and/or modified under the
13 % conditions of the LaTeX Project Public License, either
14 % version 1.3c of this license or (at your option) any
15 % later version. The latest version of this licence is in
16 %
17 % http://www.latex-project.org/lppl.txt
18 %
19 %<*readme>
20 %
21 % The rubikrotation package provides a collection of LaTeX commands and macros
22 % for the typesetting of Rubik cube configurations and rotation
23 % sequences using the TikZ graphic language.
24 %
25 % Please report errors or suggestions for improvement to
26 %
27 % Dick Nickalls or Apostolos Syropoulos
28 %
29 % This package requires the basic TikZ package to be loaded already
30 %</readme>
31 %
32 %<*driver>
33 \listfiles
34 \documentclass{ltxdoc}
35 \IfFileExists{rubikrotation.sty}{\usepackage{rubikrotation}}{%
36 \GenericWarning{rubikrotation.dtx}{Package file rubikrotation.sty not found.
37 Documentation will be messed up!^^J
38 (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J
39 process rubikrotation.dtx again)^^J}\stop
40 }%
41 \pagestyle{myheadings}
42 \markright{\texttt{rubikrotation} \ \ (Rubik bundle v5.0, 2018) \ \ \texttt{www.ctan.org/pkg/rubik}}
43 \usepackage{ifpdf}
44 \usepackage{url,path} %% for references and paths
45 \usepackage{graphicx} %% for the two pdf figs
46 \usepackage{hypdoc} %% for pdf bookmarks + hyperref documenting of packages
47 %%\OnlyDescription
48 \EnableCrossrefs
49 \PageIndex
50 \CodelineIndex
51 \CodelineNumbered
52 \RecordChanges
53 \setcounter{StandardModuleDepth}{1}
54 \begin{document}
55 \DocInput{rubikrotation.dtx}
56 \PrintChanges
57 \PrintIndex
58 \end{document}
59 %</driver>
60 % \fi
61 %
62 %
63 %
64 %%% \CheckSum{332}
65 %
66 %%% \CharacterTable
67 %% {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
68 %% 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
69 %% Digits \0\1\2\3\4\5\6\7\8\9
70 %% Exclamation \! Double quote \" Hash (number) \#
71 %% Dollar \$ Percent \% Ampersand \&
72 %% Acute accent \' Left paren \( Right paren \)
73 %% Asterisk \* Plus \+ Comma \,
74 %% Minus \- Point \. Solidus \/
75 %% Colon \: Semicolon \; Less than \<
76 %% Equals \= Greater than \> Question mark \?
77 %% Commercial at \@ Left bracket \[ Backslash \\
78 %% Right bracket \] Circumflex \^ Underscore \_
79 %% Grave accent \` Left brace \{ Vertical bar \|
80 %% Right brace \} Tilde \~}
81 %
82 %
83 %
84 % \title{%
85 % \ifpdf\pdfbookmark[1]{Title}{Title}\else\fi%
86 % The \rubikrotation\ package}
87 %
88 % \author{
89 % RWD Nickalls ([email protected]) \\
90 % A Syropoulos ([email protected])
91 % }
92 % \date{This file describes version \RRfileversion\ (\RRfiledate)\\
93 % \texttt{www.ctan.org/pkg/rubik}}
94 % \maketitle
95 %
96 % \begin{abstract}
97 % The \rubikrotation\ package is a dynamic extension for the
98 % \textsc{rubikcube} package (both are part of the Rubik `bundle').
99 % This package provides the \cmd{\RubikRotation} command which
100 % processes a sequence of Rubik rotation moves on-the-fly (using the Perl script
101 % \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration).
102 % The \rubikrotation\ package also provides commands for saving the cube state
103 % to a file (\cmd{\SaveRubikState}), and for displaying any
104 % errors (\cmd{\ShowErrors}).
105 % \end{abstract}
106 %
107 %
108 % \begin{minipage}{11cm}
109 % \centering
110 % \ifpdf
111 % \strut\hspace{6mm}\includegraphics[width=10cm]{rubikrot-doc-figD.pdf}
112 % \else
113 % \fi
114 % \end{minipage}
115 %
116 %
117 % \vspace{-1\baselineskip}
118 %
119 % \tableofcontents
120 %
121 % \pagebreak
122 %
123 % \section{Introduction}
124 %
125 % The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube}
126 % and \textsc{rubiktwocube} packages.
127 % It consists of a style option (\texttt{rubikrotation.sty}), a
128 % Perl script (\texttt{rubikrotation.pl}).
129 %
130 % The primary role of the \rubikrotation\ package is to implement a sequence of
131 % Rubik rotation moves on-the-fly using the \cmd{\RubikRotation} command.
132 % Consequently the \rubikrotation\ package requires access to the \TeX\ \texttt{write18}
133 % facility, which is enabled by using the \texttt{--shell-escape} command-line switch.
134 % This allows command-line control of the Perl script, which is really the `engine' of
135 % this package.
136 %
137 % The \rubikrotation\ package has been road-tested on a Microsoft
138 % platform (MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl'
139 % (\texttt{http://strawberryperl.com}) is a free Perl
140 % environment for MS Windows, designed to be as close as possible to the Perl
141 % environment of Unix/Linux systems.}), on a Linux platform (Debian v8.2.0,
142 % {\TeX}Live 2017, and Perl v5.20.2), and on a Solaris platform (OpenIndiana).
143 %
144 % The following commands are made available by \texttt{rubikrotation.sty}:
145 % \begin{quote}
146 % \begin{verbatim}
147 % \RubikRotation[]{}
148 % \SaveRubikState
149 % \CheckState
150 % \ShowErrors
151 % \SequenceName
152 % \SequenceInfo
153 % \SequenceShort
154 % \SequenceLong
155 %\end{verbatim}
156 % \end{quote}
157 % Note that the \textsc{rubiktwocube} package makes available the (equivalent)
158 % \verb!\TwoRotation[]{}! and \verb!\SaveTwoState! commands.
159 %
160 % \section{Requirements}
161 %
162 % The \rubikrotation\ package requires the TikZ and the \textsc{rubikcube} packages.
163 %
164 %
165 % \section{Installation}
166 %
167 % \subsection{Generating the files}
168 %
169 % Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it.
170 % This will generate the following files:
171 %\begin{quote}
172 % \begin{verbatim}
173 % rubikrotation.ins
174 % rubikrotation.dtx
175 % rubikrotation.pdf --this document
176 % rubikrotation.pl --Perl script
177 % rubikrotationPL.pdf --documentation of rubikrotation.pl
178 % rubikrotation.1 --manual file for rubikrotation.pl (`man' file)
179 % rubikrot-doc-figA.pdf
180 % rubikrot-doc-figB.pdf
181 % rubikrot-doc-figC.pdf
182 % rubikrot-doc-figD.pdf
183 %\end{verbatim}
184 %\end{quote}
185 % The main package documentation is the file \texttt{rubikrotation.pdf}.
186 % The documentation of the Perl program \texttt{rubikrotation.pl} is the file \texttt{rubikrotationPL.pdf}
187 %
188 % The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on
189 % the file \texttt{rubikrotation.ins} as follows:
190 %\begin{quote}
191 %\begin{verbatim}
192 % pdflatex rubikrotation.ins
193 %\end{verbatim}
194 %\end{quote}
195 % The documentation file (\texttt{rubikrotation.pdf}) is then generated using the following
196 % sequence of steps\,\footnote{Since the documentation includes a complicated indexing
197 % system as well as an index and hyperef links (the package \texttt{hypdoc}
198 % is used), then a lot of pdflatex runs are required. Prior to the first run it is
199 % a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}:
200 %\begin{quote}
201 % \begin{verbatim}
202 % pdflatex rubikrotation.dtx
203 % pdflatex rubikrotation.dtx
204 % makeindex -s gind.ist rubikrotation
205 % makeindex -s gglo.ist -o rubikrotation.gls rubikrotation.glo
206 % pdflatex rubikrotation.dtx
207 % pdflatex rubikrotation.dtx
208 %\end{verbatim}
209 %\end{quote}
210 %
211 %
212 %
213 % \subsection{Placing the files}
214 % \label{sec:placingfiles}
215 %
216 % Place the files either in a working directory, or where your system
217 % will find them, e.g.,~in the `\textsc{path}'. The \texttt{/texmf-local/} directory tree
218 % is often a good place; for example, on a Linux platform with a
219 % standard \TeX\ Directory Structure (TDS), then:
220 %
221 %\medskip
222 %{\noindent}*.sty $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/}
223 %{\newline}*.cfg $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/}
224 %{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubik/}
225 %{\newline}*.pl $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/scripts/rubik/}
226 %
227 %\medskip
228 %{\noindent}\textsc{perl script}:\ \ Make the perl script executable
229 % (\texttt{chmod +x rubikrotation.pl}), and then
230 % rename the file as `rubikrotation' (i.e.,~with no file extension), and then place
231 % the executable script in the `\textsc{path}', or possibly, directly into your
232 % {\TeX}Live binary directory, e.g.,~\path!/user/local/texlive/YYYY/bin/i386-linux!.
233 %
234 % Sometimes the setting up of a simple one or two-line plain-text
235 % configuration-file may be useful or even necessary, depending on your system
236 % (see Section~\ref{sec:configfile} below). Such a file (if one exists) will
237 % automatically be read by \texttt{rubikrotation.sty} providing the
238 % file is named \texttt{rubikrotation.cfg}.
239 %
240 %\medskip
241 %{\noindent}\textsc{the `man' file}:\ \ On a Linux platform the manual file
242 % (\texttt{rubikrotation.1}) is typically located in
243 % either \verb!/usr/local/man/man1! or \verb!/usr/local/share/man/man1!.
244 % \TeX{Live} typically places such files in the directory
245 % \verb!/texmf-dist/doc/man/man1!.
246 %
247 %\medskip
248 %{\noindent}\textsc{file database}:\ \ Finally, (depending on your system) update the
249 % \TeX\ file database.
250 % For example, on a Linux platform this is achieved using the \texttt{texhash} command,
251 % or by using the {\TeX}Live Manager (\texttt{tlmgr}).
252 %
253 %\medskip
254 %{\noindent}\textsc{quick test}:\ \ To test that your system can now run the perl
255 % script, just type at the command-line
256 %\begin{quote}
257 % \begin{verbatim}
258 % rubikrotation -h
259 %\end{verbatim}
260 %\end{quote}
261 % which should generate something like the following:
262 % \begin{verbatim}
263 % This is rubikrotation version ...
264 % Usage: rubikrotation [-h] -i <input file> [-o <out file>]
265 % where,
266 % [-h|--help] gives this help listing
267 % [-v|--version] gives version
268 % [-i] creates specified input file
269 % [-o] creates specified output file
270 % For documentation see: rubikrotation.pdf,
271 % rubikrotationPL.pdf and rubikcube.pdf
272 %\end{verbatim}
273 %
274 %
275 % \section{Usage}
276 % \label{sec:usage}
277 % Load the packages \texttt{rubikcube.sty},
278 % \texttt{rubikrotation.sty}, \texttt{rubikpatterns.sty}
279 % and \texttt{rubiktwocube.sty} in the \TeX\ file
280 % preamble \textit{after} loading the TikZ package (all the Rubik packages
281 % require the TikZ package). Load the \texttt{rubikcube.sty} \textit{before} the other
282 % Rubik bundle packages; for example, as follows:
283 %\begin{quote}
284 % \begin{verbatim}
285 % \usepackage{tikz}
286 % \usepackage{rubikcube,rubikrotation,rubikpatterns,rubiktwocube}
287 %\end{verbatim}
288 %\end{quote}
289 % and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line option
290 % (see the following section).
291 %
292 %
293 %
294 % \subsection{Enabling the \TeX\ `shell' facility}
295 % \label{sec:shellescape}
296 %
297 % In order to access the \TeX\ \cmd{\write18} syntax (so we can access system commands,
298 % and hence run the Perl script),
299 % it is necessary to invoke the \LaTeX\ engine (e.g.,~(pdf)\LaTeX\ or Lua\LaTeX)
300 % using the \texttt{--shell-escape} command-line option; for example:
301 %\begin{quote}
302 % \begin{verbatim}
303 % pdflatex --shell-escape filename.tex
304 %\end{verbatim}
305 %\end{quote}
306 % In practice, it is probably most convenient to run this command via a
307 % bash/batch file. For example, on a Linux platform the following bash file
308 % will run the file, show any errors, and open the \textsc{pdf} using AcrobatReader.
309 %\begin{quote}
310 % \begin{verbatim}
311 % pdflatex --shell-escape filename.tex
312 % echo "...checking error file"
313 % grep ERROR ./rubikstateERRORS.dat
314 % acroread filename.pdf &
315 %\end{verbatim}
316 %\end{quote}
317 % If the \LaTeX\ engine is Lua\LaTeX, e.g.,
318 %\begin{quote}
319 % \begin{verbatim}
320 % lualatex --shell-escape filename.tex
321 %\end{verbatim}
322 %\end{quote}
323 %then \texttt{rubikrotation.sty} will automatically load
324 % the recently developed \textsf{shellesc} package in order to facilitate system access to Perl
325 % (see Section~\ref{sec:CodePackageHeading}). See \textit{\LaTeX\ News}, issue~24,
326 % Feb~2016 for further details of the \textsf{shellesc} package.
327 % Consequently, if you intend to use Lua\LaTeX\ then you will need to ensure your system
328 % has access to the \textsf{shellesc} package (it can always be downloaded from CTAN directly).
329 %
330 %
331 % \subsection{Configuration-file}
332 % \label{sec:configfile}
333 %
334 % It is important to realise that the default action of \texttt{rubikrotation.sty} is to
335 % access the Perl script as an executable file. This is because the~default definitions
336 % in \texttt{rubikrotation.sty} are as follows: (they are detailed in
337 % Section~\ref{sec:usefulcommands})
338 %\begin{quote}
339 %\begin{verbatim}
340 % \newcommand{\rubikperlname}{rubikrotation}
341 % \newcommand{\rubikperlcmd}{\rubikperlname\space%
342 % -i rubikstate.dat -o rubikstateNEW.dat}
343 %\end{verbatim}
344 %\end{quote}
345 % Note the need here (in the second macro) to use \cmd{\space} on the end of
346 % (\cmd{\rubikperlname}) in order to force a following
347 % space---i.e.,~before the first command-line argument.
348 %
349 % If the Perl script has not been made executable, or if you wish to alter how
350 % the \textsc{rubikrotation} package accesses the Perl script,
351 % then you need to create a plain-text configuration file in order to redefine one
352 % or both of the above commands, as described below.
353 %
354 % A plain-text configuration-file with the name \texttt{rubikrotation.cfg}
355 % (if one exists) will automatically be read by \texttt{rubikrotation.sty}.
356 % The \rubikrotation\ package's facility to use a configuration-file allows the
357 % user to change not only (a)~the filename of the Perl script (\texttt{rubikrotation.pl}),
358 % but also (b)~the command-line code used by \texttt{rubikrotation.sty} for calling the
359 % Perl script. This~sort of fine-tuning can be very useful, and sometimes may
360 % even be necessary (depending on your system) for running the Perl script.
361 %
362 % For example, on some systems it maybe preferable to use a different \textsc{path},
363 % file-name and/or a different command-line code to call the script.
364 % Such~a configuration-file can also facilitate testing a new Perl script having
365 % a different name and location.
366 %
367 % \DescribeMacro{\rubikperlname}
368 % \DescribeMacro{\rubikperlcmd}
369 % The configuration-file is essentially a convenient software vehicle for feeding
370 % additional \LaTeX\ code to the style option \texttt{rubikrotation.sty}, and hence
371 % allows the contents of some commands to be easily adjusted and/or fine-tuned.
372 % For~the \rubikrotation\ package there are two particular macros we may wish to adjust
373 % (see above).
374 % The~first is that holding the filename of the Perl script, namely
375 % \cmd{\rubikperlname}. The second is that holding the command-line call,
376 % namely \cmd{\rubikperlcmd}.
377 % The following examples illustrate how the configuration-file may be used.
378 %
379 % \medskip
380 % {\noindent}\textsc{example~1}:\ \ Suppose we wish to test out
381 % a slightly modified Perl script
382 % with the working (executable) name \texttt{rubikrotationR77}. In this case we
383 % simply create, in the local working directory, a plain-text configuration-file
384 % (it \textit{must} be named exactly \texttt{rubikrotation.cfg}) containing just
385 % the following line:
386 %\begin{quote}
387 %\begin{verbatim}
388 %\renewcommand{\rubikperlname}{rubikrotationR77}
389 %\end{verbatim}
390 %\end{quote}
391 %
392 % \medskip
393 % {\noindent}\textsc{example~2}:\ \ Alternatively, suppose we wish to test out
394 % a new Perl script with the (non-executable) name \texttt{rubikrotationR55.pl}.
395 % Now, in this particular case we will need to run the script using a
396 % slightly different command, namely,
397 % {\linebreak}\texttt{perl rubikrotationR55.pl ...}, and consequently we
398 % need to implement \textit{both} these changes (of name and command) in
399 % the configuration-file, as follows:
400 %\begin{quote}
401 %\begin{verbatim}
402 %\renewcommand{\rubikperlname}{rubikrotationR55.pl}
403 %\renewcommand{\rubikperlcmd}{perl \rubikperlname\space\%
404 % -i rubikstate.dat -o rubikstateNEW.dat}
405 %\end{verbatim}
406 %\end{quote}
407 %{\noindent}Remember to make sure the PATH associated with the command is also correct.
408 %
409 % \medskip
410 %{\noindent\textsc{placing the configuration-file}:\ \ The simplest arrangement is
411 % just to include the \texttt{.cfg} file in the working directory.
412 % Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/}
413 % directory tree (say, in \path!/usr/local/texlive/texmf-local/tex/latex/rubik/!),
414 % but in this case one would then have to be careful to specify the
415 % correct PATH for everything in order to enable your system to find all the
416 % various components etc.
417 %
418 % Note that you can, of course, have several \texttt{.cfg} files, since the system will
419 % read only one such file (the first one it finds starting with the current working
420 % directory). Consequently, it may be useful to have one \texttt{.cfg} file in
421 % your \texttt{/texmf-local/} dir (for running the standard Rubik package),
422 % and another (different) \texttt{.cfg} file in your `test' directory.
423 %
424 %
425 % \section{Commands}
426 %
427 % The \textit{only} `Rubik bundle' commands which \textit{must} be used inside a TikZ picture
428 % environment are the \cmd{\Draw...} commands (these are all provided by
429 % the \textsc{rubikcube} package), although most commands can be placed
430 % inside a TikZ environment if you wish.
431 %
432 % Using commands which influence the Rubik colour state
433 % (e.g.,~\cmd{\RubikFace..}, \cmd{\RubikCubeSolvedWY} etc.) outside the \texttt{tikzpicture},
434 % \texttt{minipage} or \texttt{figure} environments
435 % generally offers maximum flexibility, since the effects of such commands when
436 % used inside these environments remain `local' to the environment, and are not
437 % therefore accessible outside that \textit{particular} environment
438 % (see also Section~4.1 in the \textsc{rubikcube} documentation).
439 %
440 % Conversely, the only \rubikrotation\ command which should \textit{not}
441 % be used inside a TikZ environment is the \cmd{\ShowErrors} command
442 % (see the notes on this command below).
443 %
444 %
445 %
446 %
447 % \subsection[RubikRotation]{\cmd{\RubikRotation} command}
448 % \label{sec:rubikrotationcmd}
449 %
450 % \DescribeMacro{\RubikRotation}
451 % The \cmd{\RubikRotation}\oarg{integer}\marg{comma-separated sequence}
452 % command processes a sequence of rotation codes, and returns
453 % the final state. The inverse sequence can also be
454 % implemented (see \textbf{Inverse} below). Note that the equivalent \cmd{\TwoRotation}
455 % command (see the \textsc{rubiktwocube} package) behaves in the same way as the
456 % \cmd{\RubikRotation} command in all respects.
457 %
458 %
459 % The first (optional) argument \oarg{integer} of the \cmd{\RubikRotation} command is the number
460 % of times the whole command itself should be repeated; for example
461 % as follows: \verb!\RubikRotation[2]{...}!.
462 %
463 % The second (mandatory) argument consists of a comma-separated sequence
464 % of rotation codes, e.g.,~\texttt{U, D2}, which may be encoded as a macro. In addition, there
465 % may be additional comma-separated macros and optional \verb![name]!,
466 % `repeat blocks' and `info blocks' (see below).
467 % The general structure of the second argument is as follows:
468 % \verb!\RubikRotation{[name],...,\macro,...,(repeat)n,...,<info>}!.
469 % These elements are now described in detail.
470 %
471 %
472 %
473 % \textbf{Square brackets}: \ This is an optional `sequence name' facility.
474 % The contents of square brackets are not processed
475 % as rotations, and can therefore be used as a `name' of the sequence, e.g.,~\verb![CrossSeq]!,
476 % or as a tag, to be visible in the log file. The contents must \textit{not} include commas, but
477 % can have other separators, e.g.,~spaces, semicolons etc. Importantly, the contents of the
478 % first square bracket will be designated the sequence name and will be held as the
479 % macro \cmd{\SequenceName}. Square brackets can also be used in repeat blocks (see below).
480 % Square brackets must be separated by a comma from adjacent codes.
481 %
482 %
483 % \textbf{Repeat block}: \ This is an optional comma-separated sequence of rotation
484 % codes which is to be repeated a specified number of times. It must be delimited
485 % by balanced curved brackets, and an optional terminal integer $n$ (repeat number)
486 % can be used. For example, \verb!(F,B3)2,! where the `2' indicates that the rotation
487 % sequence \verb!F,B3! is to be processed twice. If the repeat number is omitted
488 % then $n=1$ is assumed. Repeat blocks must be separated by a comma from adjacent codes,
489 % and can include balanced square brackets (see below).
490 %
491 %
492 % \textbf{Info block}: \
493 % This is an optional block of meta information, and must be
494 % delimited by balanced angle-brackets \verb!<..>!. An info-block typically carries
495 % information regarding the sequence itself; typically, something
496 % like \verb!<(20f*) //C2(a)>!. If an infoblock includes the keyword `inverse' then
497 % the program will implement the inverse sequence of rotations (see below).
498 % An info-block must be separated by a comma from the adjacent codes.
499 % The contents of all info blocks will be held collectively as the macro \cmd{\SequenceInfo}.
500 %
501 %
502 % \textbf{Inverse sequence}: \
503 % The (mathematically) inverse sequence of the given sequence can be implemented by including
504 % the keyword `inverse' (or INVERSE) in an infoblock,
505 % as follows \verb!\RubikRotation{<inverse>, ... }!. The keyword can be either in its
506 % own separate infoblock, or inside a larger infoblock. The program simply checks for the
507 % string `inverse', which can be either lower-case or upper-case. The implemented sequence
508 % can be checked by looking at (or printing) the contents of the macro
509 % \cmd{\SequenceLong} (see section on \textit{Sequence strings} below). Note that the macro
510 % \cmd{\SequenceLong} is also shown (expanded) in the log file.
511 %
512 %
513 % \subsubsection{Examples}
514 %
515 % Some examples of the use of the \cmd{\RubikRotation} command are as follows; the commas are important and brackets must
516 % be balanced and not nested:
517 %\begin{quote}
518 % \begin{verbatim}
519 % \RubikRotation[2]{x,R2,U}
520 % \RubikRotation{\sixspot}
521 % \RubikRotation{<inverse>,[myseqB],U,D,L,R2,(M,U)3,D2}
522 % \RubikRotation{[K32466],U,F,U2,F,L2,B,U2,F,Lp,Rp,F2,D,R2,U2,L2,B,Fp,
523 % L,F2,D,<(20f*) //Oh{I}>}
524 %\end{verbatim}
525 %\end{quote}
526 %
527 % \noindent\textbf{Inverse sequence}
528 %
529 % Inverting a sequence involves (a)~reversing the order, and (b)~inverting each element.
530 % Thus, the inverse of the sequence \verb!(Up,D,L2,Rp)! is \verb!(R,Lp,Lp,Dp,U)!.
531 % But~\verb!(Lp,Lp)! $\equiv$ \verb!L2!, and so the inverse
532 % of \verb!(Up,D,L2,Rp)! would generally be expressed as \verb!(R,L2,Dp,U)!.
533 % However, since the macro \cmd{\SequenceLong} records the individual elements as they are processed,
534 % when a sequence is inverted notational compressions such as \verb!Lp,Lp! $\rightarrow$ \verb!L2!
535 % are not made.
536 % For example, processing the command \verb!\RubikRotation{<inverse>,Up,D,L2,Rp}! results in the macro
537 % \cmd{\SequenceLong} being displayed in the subsequent \texttt{rubikstateNEW.dat} file as
538 %\begin{quote}
539 % \begin{verbatim}
540 % \renewcommand\SequenceLong{R,Lp,Lp,Dp,U}%
541 %\end{verbatim}
542 %\end{quote}
543 % A more extensive example is given at the end of Section~\ref{sec:sequencestrings}.
544 %
545 %
546 % \medskip\noindent\textbf{Repetitions}
547 %
548 % Repetitions can be achieved in various ways. First, all the rotations in the second argument
549 % can be repeated multiple times, say $n$ times, by
550 % using the optional \verb![n]! argument of the \cmd{\RubikRotation[]\{\}} command;
551 % i.e.,~the whole of the mandatory argument of the \cmd{\RubikRotation} command is then
552 % executed $n$ times.
553 %
554 % Second, a sub-sequence of rotations can be repeated within the main
555 % argument multiple times, by delimiting such groups with curved brackets
556 % and a trailing integer (i.e.,~in a repeat-block), as described above.
557 % If no integer is given, then $n=1$ is assumed, and hence curved brackets can also be used
558 % simply to highlight particular sequences.
559 % For example, the following five commands are equivalent:
560 %\begin{quote}
561 % \begin{verbatim}
562 % \RubikRotation[3]{x,R2,U}
563 % \RubikRotation{(x,R2,U)3}
564 % \RubikRotation{(x,R2,U)2,x,R2,U}
565 % \RubikRotation{x,R2,U,x,R2,U,x,R2,U}
566 % \RubikRotation{(x,R2,U),(x,R2,U),(x,R2,U)}
567 %\end{verbatim}
568 %\end{quote}
569 %
570 %
571 % \medskip\noindent\textbf{Macros}
572 %
573 % Note also that macros representing a rotation sequence can also appear as part of the main argument.
574 % So, extending the previous example, if we were to define \verb!\newcommand{\ShortSeq}{x,R2,U}!, then
575 % the following three commands would also be equivalent to the five previous ones:
576 %\begin{quote}
577 % \begin{verbatim}
578 % \RubikRotation[3]{\ShortSeq}
579 % \RubikRotation{(\ShortSeq)3}
580 % \RubikRotation{(x,R2,U),\ShortSeq,\ShortSeq}
581 %\end{verbatim}
582 %\end{quote}
583 %
584 %
585 % \medskip\noindent\textbf{Process overview}
586 %
587 % The \cmd{\RubikRotation} command results in \LaTeX\ first writing
588 % the current Rubik state to a text file (\texttt{rubikstate.dat}),
589 % and then calling the Perl script \texttt{rubikrotation.pl}. The Perl
590 % script then reads the current Rubik state from the (\texttt{rubikstate.dat})
591 % file, performs all the rotations, and then writes the new Rubik state,
592 % and the four \cmd{\Sequence...} macros (see below), and any error messages, all to the
593 % file \texttt{rubikstateNEW.dat},
594 % which is then input on-the-fly by the \texttt{.tex} file. This new Rubik state
595 % can then be used either as the input for another \cmd{\RubikRotation} command, or used
596 % to generate a graphic image of the cube. The \cmd{\Sequence...} macros can then
597 % be used for typesetting the sequence of rotations in various formats.
598 %
599 %
600 % \subsubsection{Sequence strings}
601 % \label{sec:sequencestrings}
602 %
603 % \DescribeMacro{\SequenceName}
604 % \DescribeMacro{\SequenceInfo}
605 % \DescribeMacro{\SequenceShort}
606 % \DescribeMacro{\SequenceLong}
607 % The sequence of rotation codes used as the main argument for the \cmd{\RubikRotation}
608 % command is also returned in the form of four macros, namely \cmd{\SequenceName} (contains the
609 % `name' of the sequence if a \texttt{[name]} exists), \cmd{\SequenceInfo} (contains any sequence
610 % meta data in `info-blocks'), \cmd{\SequenceShort} (contains the original
611 % sequence of rotation codes), and \cmd{\SequenceLong} (contains the expanded or `Long' form of the
612 % original sequence---i.e.,~in which any `short' rotation codes (e.g.,~\texttt{R2, L3}) in the original
613 % sequence have been expanded into their separate codes---e.g.,~\texttt{R, R, L, L, L} etc.).
614 %
615 % For example, if we wanted to see the effect of the sequence associated with the `SixTs'
616 % cube configuration
617 % \verb![SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>!
618 % on a solved Rubik cube (where `SixTs' is the `name' of the sequence),
619 % we could use the following commands:
620 %\begin{quote}
621 % \begin{verbatim}
622 % \RubikCubeSolved % sets up the colours for a solved cube state
623 % \RubikRotation{[SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>}
624 % \ShowCube{2.8cm}{0.7}{\DrawRubikCubeRU}
625 %\end{verbatim}
626 %\end{quote}
627 % Note (a)~contents of a square bracket [..] are not processed as rotations, (b)~the contents
628 % of the first square bracket in a sequence is taken to be the `name' of the sequence
629 % (see Section~\ref{sec:prefixedargument} for more details).
630 % In this example the four \cmd{\Sequence..} macros described above would now hold
631 % the following strings:
632 %\begin{quote}
633 % \cmd{\SequenceName} = SixTs
634 %{\newline} \cmd{\SequenceInfo} = (14q*,14f*)
635 %{\newline} \cmd{\SequenceShort} = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B
636 %{\newline} \cmd{\SequenceLong} = F,F,R,R,U,U,Fp,B,D,D,L,L,F,B
637 %\end{quote}
638 %
639 % As another example, we now show how to implement the inverse of the above \verb!SixTs!
640 % sequence, by including the key word `inverse' in an infoblock, and, more conveniently,
641 % using the macro \verb!\sixts! from the \textsc{rubikpatterns} package, as follows:
642 %\begin{quote}
643 % \begin{verbatim}
644 % \RubikRotation{<inverse>,\sixts}
645 %\end{verbatim}
646 %\end{quote}
647 % In this case, the log file would then show the associated \cmd{\Sequence..} macros as follows:
648 %\begin{quote}
649 % \begin{verbatim}
650 %...SequenceName = SixTs
651 %...SequenceInfo = inverse; (14q*; 9f*)
652 %...SequenceShort = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B
653 %...SequenceLong = Bp,Fp,Lp,Lp,Dp,Dp,Bp,F,Up,Up,Rp,Rp,Fp,Fp
654 %\end{verbatim}
655 %\end{quote}
656 % showing that the macro \cmd{\SequenceShort} holds the \verb!\sixts! sequence, while
657 % the macro \cmd{\SequenceLong} holds the inverse sequence which was actually implemented.
658 %
659 % For further details regarding the use of these \cmd{\Sequence..} macros for typesetting
660 % the various components of a sequence, and why the \cmd{\SequenceLong} command is
661 % particularly useful, see Section~10 in the \textsc{rubikcube} documentation
662 % (the \cmd{\ShowSequence} command).
663 %
664 %
665 %
666 % \subsubsection{Sequences as macros}
667 % \label{sec:seq-as-macros}
668 %
669 % Macros which are arguments of the \TeX\ \cmd{\write} command are expanded
670 % on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see references Section~\ref{sec:references}\,].
671 % Consequently we are able to use a sequence-defining macro as an argument for
672 % the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows
673 % one to store lots of different rotation sequences by name alone. Note that
674 % \texttt{rubikpatterns.sty} (part of the Rubik bundle) is a collection/database
675 % of many such well-known named sequences.
676 %
677 % For example, by installing the \textsc{rubikpatterns} package we are able to use the
678 % name `sixspot' for a macro denoting the rotation sequence
679 % which generates the well known `sixspot' configuration (see the `patterns' page on the
680 % Reid website)[\,see references Section~\ref{sec:references}\,]. The `sixspot' sequence is
681 % defined as follows:
682 %\begin{quote}
683 % \begin{verbatim}
684 % \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>}
685 %\end{verbatim}
686 %\end{quote}
687 % Armed with the \cmd{\sixspot} macro we are now able to generate the graphic (sixspot cube)
688 % very easily using the following code---this time we demonstrate the use of the more convenient
689 % \cmd{\ShowCube} command (which includes the \texttt{tikzpicture} environment):
690 %
691 % \medskip
692 %
693 % \begin{minipage}{7cm}
694 % \begin{verbatim}
695 % \usepackage{rubikcube,rubikrotation}
696 % \usepackage{rubikpatterns}
697 % ...
698 % \RubikCubeSolved
699 % \RubikRotation{\sixspot}
700 % \ShowCube{3cm}{0.7}{\DrawRubikCubeRU}
701 %\end{verbatim}
702 % \end{minipage}
703 % \begin{minipage}{3.4cm}
704 % \centering
705 % \ifpdf
706 % \includegraphics[height=3cm]{rubikrot-doc-figA.pdf}
707 % \else
708 % \fi
709 % \end{minipage}
710 %
711 % \medskip
712 % Providing such macros (when used as arguments) are comma separated (as the rotation codes
713 % must be), then the \cmd{\RubikRotation} command can accommodate both rotation codes
714 % and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!.
715 %
716 %
717 % \subsubsection{Arguments in square brackets }
718 % \label{sec:prefixedargument}
719 %
720 % The contents of a square bracket are not processed as rotations, but are simply
721 % interpreted as an inactive `string'. This feature therefore
722 % allows the contents to be used as a label, which can be very useful.
723 % Note the contents of square brackets must not include commas, but spaces and semicolons
724 % are allowed.
725 %
726 % For example, we can use this facility to `name' the `SixSpot' configuration mentioned above,
727 % as follows:
728 %\begin{quote}
729 % \begin{verbatim}
730 % \RubikRotation{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp}
731 %\end{verbatim}
732 %\end{quote}
733 % In practice, it is quite useful to go one step further and include
734 % the [\,] label-name feature in the \cmd{\sixspot} command, as follows,
735 %\begin{quote}
736 % \begin{verbatim}
737 % \newcommand{\sixspot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp}
738 %\end{verbatim}
739 %\end{quote}
740 % Note that using the \texttt{[name]} facility has the great advantage of making the
741 % label-name visible in the log-file.
742 % For example, the following command, which uses the rotations \textbf{x2},
743 % and \textbf{y} to rotate the Rubik cube after applying
744 % the `sixspot' sequence of rotations:
745 %\begin{quote}
746 % \begin{verbatim}
747 % \RubikRotation{\sixspot,x2,y}
748 %\end{verbatim}
749 %\end{quote}
750 % will then be represented in the log file as
751 %\begin{quote}
752 % \begin{verbatim}
753 % ...dataline = rotation,[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*; 8f*)>,x2,y
754 % ...[SixSpot] is a label OK
755 % ...rotation U, OK
756 % ...rotation Dp, OK
757 % ...rotation R, OK
758 % ...rotation Lp, OK
759 % ...rotation F, OK
760 % ...rotation Bp, OK
761 % ...rotation U, OK
762 % ...rotation Dp, OK
763 % ...Expanding x2 ...
764 % ...rotation x, OK (= x = R + Sr + Lp)
765 % ...rotation x, OK (= x = R + Sr + Lp)
766 % ...rotation y, OK (= y = U + Su + Dp)
767 % ...writing new Rubik state to file rubikstateNEW.dat
768 % ...SequenceName = SixSpot
769 % ...SequenceInfo = (8q*; 8f*)
770 % ...SequenceShort = [SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,x2,y
771 % ...SequenceLong = U,Dp,R,Lp,F,Bp,U,Dp,x,x,y
772 %\end{verbatim}
773 %\end{quote}
774 % Note that the \verb!\sixspot! macro, as held in the \textsc{rubikpatterns} package, includes a terminal
775 % infoblock holding the `SequenceInfo' as indicated in the above example.
776 %
777 % Also, note that the square bracket feature allows for several named rotation sequences
778 % to be easily distinguished in the log file from adjacent rotation sequences.
779 % This feature is also useful when typesetting a sequence of rotation codes, since the first
780 % element will then appear in the form \verb![name]!, obviating the need to typeset the
781 % name of the sequence separately.
782 %
783 % See also the \cmd{\ShowSequence} command (in the \textsc{rubikcube} package)
784 % for a convenient way of displaying a sequence of rotations in various formats.
785 %
786 %
787 % \subsubsection{Groups}
788 %
789 % The \cmd{\RubikRotation} command is a convenient tool for
790 % illustrating how Rubik rotations and sequences of rotations are elements
791 % of groups and subgroups.
792 % For~example, using the \rubikrotation\ package it is easy to
793 % show that three cycles of the `sixspot' sequence return the Rubik cube to its
794 % original state. More formally this is equivalent to
795 % $($\cmd{\sixspot}$)3 \equiv e$\,\footnote{$e$ is the `identity' element},
796 % and can be nicely illustrated by implementing the following pseudocode:
797 %\begin{verbatim}
798 % \RubikCubeSolved . \RubikRotation[3]{\sixspot} = \RubikCubeSolved
799 %\end{verbatim}
800 %
801 % \begin{minipage}{11cm}
802 % \centering
803 % \ifpdf
804 % \includegraphics[width=10cm]{rubikrot-doc-figC.pdf}
805 % \else
806 % \fi
807 % \end{minipage}
808 %
809 %
810 % \subsubsection{Random rotations}
811 %
812 % The \cmd{\RubikRotation} command can also be used to scramble the
813 % cube using a random sequence of rotations. If the first argument
814 % is the word `random' \textsc{and} the second argument
815 % is an integer $n$, ($1\leq n \leq 200$), then a random sequence
816 % of $n$ rotations will be performed.
817 % If $n > 200$ then the currently set maximum value $n=200$ will be used.
818 %
819 % As a safety feature the maximum $n$ can be changed only by editing the
820 % set value of the Perl variable \verb!$maxn! in the Perl script
821 % \texttt{rubikrotation.pl}, where we currently have
822 % (see the `random' subroutine in the document \texttt{rubikrotationPL.pdf})
823 %\begin{quote}
824 %\begin{verbatim}
825 % my $maxn=200;
826 %\end{verbatim}
827 %\end{quote}
828 %
829 % For example, the following commands scramble a solved cube using a
830 % sequence of 120 random rotations, and display the state in the form of
831 % a semi-flat (SF) cube.
832 %
833
834 % \begin{minipage}{3.4cm}
835 % \centering
836 % \ifpdf
837 % \includegraphics[height=4cm]{rubikrot-doc-figB.pdf}
838 % \else
839 % \fi
840 % \end{minipage}
841 % \begin{minipage}{6cm}
842 % \vspace{1.6cm}
843 %\begin{verbatim}
844 % \RubikCubeSolved%
845 % \RubikRotation{random,120}%
846 % \ShowCube{5.5cm}{0.5}{\DrawRubikCubeSF}
847 %\end{verbatim}
848 % \end{minipage}
849 %
850 % Note that in this particular example (above), only
851 % the \cmd{\Draw..} command is inside the TikZ picture environment (i.e.,~inside
852 % the \cmd{\ShowCube} command). Note also that when Rubik
853 % commands are outside a TikZ picture environment, they should have a
854 % trailing \% to stop additional white space being included.
855 %
856 % \medskip
857 %
858 % The randomisation procedure is as follows: all the possible rotations are first allocated
859 % a different cardinal number (positive integer) and collected into an array.
860 % Then a sequence of $n$ randomised numbers is generated and mapped to
861 % the array to generate the associated sequence of random rotations.
862 % The sequence used is detailed in the \texttt{.log} file.
863 %
864 %
865 % \subsection[SaveRubikState]{\cmd{\SaveRubikState} command}
866 % \label{saverubikstate}
867 %
868 % \DescribeMacro{\SaveRubikState}
869 % The command \cmd{\SaveRubikState}\marg{filename} saves the state (configuration)
870 % of the Rubik cube to the file \marg{filename} in the standard \cmd{\RubikFace...}
871 % format so that it can be read by \LaTeX. Consequently such a file can then be input
872 % so it can be drawn or processed in the usual way. The output file is `closed' immediately
873 % following the `write' in order to allow it to be available for input later by the same
874 % file if required.
875 %
876 % For example, the following commands would save the so-called `sixspot' configuration
877 % (generated by the rotations \textbf{U, Dp, R, Lp, F, Bp, U, Dp})
878 % to the file \verb!sixspot.tex!.
879 %\begin{quote}
880 %\begin{verbatim}
881 % \RubikCubeSolved%
882 % \RubikRotation{U,Dp,R,Lp,F,Bp,U,Dp}%
883 % \SaveRubikState{sixspot.tex}%
884 %\end{verbatim}
885 %\end{quote}
886 % The form of the file \verb!sixspot.tex! will then be as follows---the
887 % filename (commented out) is automatically written to the top of the
888 % file for convenience.
889 %\begin{quote}
890 %\begin{verbatim}
891 % % filename: sixspot.tex
892 % \RubikFaceUp{O}{O}{O}{O}{W}{O}{O}{O}{O}%
893 % \RubikFaceDown{R}{R}{R}{R}{Y}{R}{R}{R}{R}%
894 % \RubikFaceLeft{Y}{Y}{Y}{Y}{B}{Y}{Y}{Y}{Y}%
895 % \RubikFaceRight{W}{W}{W}{W}{G}{W}{W}{W}{W}%
896 % \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}%
897 % \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}%
898 %\end{verbatim}
899 %\end{quote}
900 % We can therefore access and draw this configuration in a Semi-Flat format
901 % later, when required, simply by inputting the file as follows:
902 %\begin{quote}
903 %\begin{verbatim}
904 %\input{sixspot.tex}
905 %\ShowCube{7cm}{0.7}{\DrawRubikCubeSF}
906 %\end{verbatim}
907 %\end{quote}
908 %
909 %
910 % \subsection[CheckState]{\cmd{\CheckState} command}
911 % \label{sec:checkstate}
912 %
913 % \DescribeMacro{\CheckState}
914 % Since it is easy to inadvertently define an invalid Rubik cube
915 % (e.g.,~enter an invalid number of, say, yellow facelets), this command
916 % simply checks the current colour state of all the cubies
917 % of a 3x3x3 Rubik cube, and shows the number of facelets of each colour.
918 % An ERROR: code is issued if the number of facelets having a given colour
919 % exceeds~9 for a 3x3x3 cube (Rubik cube), or exceeds 4 for a 2x2x2 cube (Two cube).
920 % The results are written to the the \texttt{.log} file, and displayed at the point
921 % the \cmd{\ShowErrors} command is used (for code see Section~\ref{sec:checkstatecode}).
922 %
923 % One can check the current Rubik state (for errors) by issuing the command
924 %\begin{quote}
925 %\begin{verbatim}
926 % \CheckState%
927 %\end{verbatim}
928 %\end{quote}
929 % Note (1)~that such a check is implemented automatically with each \cmd{\RubikRotation} and
930 % \cmd{\TwoRotation} command, and (2)~and makes only a very superficial check---simply counting the number
931 % of cubies of each colour.
932 %
933 % Note that the \cmd{\CheckState} command replaces the earlier \cmd{\CheckRubikState}, but
934 % we retain the old command for backwards compatibility (for the moment).
935 %
936 %
937 % \subsection[ShowErrors]{\cmd{\ShowErrors} command}
938 % \label{sec:showerrors}
939 %
940 %
941 % \DescribeMacro{\ShowErrors}
942 % Any errors which arise can be made visible using the
943 % command \cmd{\ShowErrors}.
944 % This command places a copy of the `error' file (\texttt{rubikstateERRORS.dat})
945 % underneath the graphic image so you can see any errors if there are any (note that
946 % details of all errors are are written by default to the \texttt{.log} file)
947 % (for code see Section~\ref{sec:showerrorscode}).
948 %
949 % Consequently, the \cmd{\ShowErrors} command must be placed \textit{after} a TikZ picture
950 % environment---it cannot be used inside a TikZ environment. In fact this command
951 % is probably best placed at the end of the document where it will reveal all
952 % rotation errors generated while processing the whole document.
953 % Once the document is free of errors this command can be removed or just commented out.
954 % The file \texttt{rubikexamples.pdf} shows an example of the use of this command.
955 %
956 % Note that the \cmd{\ShowErrors} command replaces the original \cmd{\ShowRubikErrors} command,
957 % which will be retained for backward compatibility.
958 %
959 %
960 % \section{Files generated}
961 %
962 %
963 % Whenever the \cmd{\RubikRotation} or \cmd{\CheckRubikState} commands are used,
964 % three small temporary plain-text files for holding data are generated as
965 % follows (they are refreshed with each \LaTeX\ run, and are not actively deleted).
966 % \begin{itemize}
967 % \item \LaTeX\ writes Rubik state data to the file \texttt{rubikstate.dat}.
968 %
969 % \item The Perl script \texttt{rubikrotation.pl} reads the file
970 % \texttt{rubikstate.dat} and then writes
971 % the new rubik state to the file \texttt{rubikstateNEW.dat}.
972 %
973 % \item The Perl script \texttt{rubikrotation.pl} also writes error data
974 % to the file \texttt{rubikstateERRORS.dat}. A copy of this file is displayed
975 % under the graphic image when the command
976 % \cmd{\ShowErrors} is used after the TikZ picture environment.
977 %
978 % \end{itemize}
979 %
980 %
981 % \section{General overview}
982 % \label{generaloverview}
983 %
984 % When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps
985 % are implemented (see Section~\ref{sec:thecode}):
986 % \begin{itemize}
987 %
988 % \item[1.] A check is made to see if \texttt{fancyvrb.sty} is loaded: if not
989 % then this package is loaded (this package supplies the command \cmd{\VerbatimInput} which
990 % is required for inputting the file \texttt{rubikstateERRORS.dat} in verbatim form).
991 %
992 % \item[2.] A check is made to see if a configuration-file (\texttt{rubikrotation.cfg})
993 % exists: if so then this file is input.
994 %
995 % \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists),
996 % otherwise the file is created (this prevents an `old' version of the file being
997 % used by \LaTeX).
998 %
999 % \item[4.] The plain-text file \texttt{rubikstateERRORS.dat} is created.
1000 % This file collects error messages generated by the Perl script.
1001 %
1002 % \end{itemize}
1003 %
1004 %
1005 % When a \cmd{\RubikRotation} command is processed
1006 % (see Section~\ref{sec:rubikrotationcode}, line~102), it first writes the current
1007 % colour configuration of each face (the `rubik state') to the temporary file
1008 % \texttt{rubikstate.dat} (this will be read by the Perl script \texttt{rubikrotation.pl}).
1009 % The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}'
1010 % as well as a copy of the string of Rubik rotations.
1011 % It~then calls the Perl script \texttt{rubikrotation.pl}.
1012 %
1013 % For example, if we use the command \cmd{\RubikCubeSolved}
1014 % followed by the command \verb!\RubikRotation[2]{U,D,L,R}!, then the associated
1015 % \texttt{rubikstate.dat} file will be written as follows:
1016 %\begin{quote}
1017 % \begin{verbatim}
1018 % % filename: rubikstate.dat
1019 % cubesize,three
1020 % up,W,W,W,W,W,W,W,W,W
1021 % down,Y,Y,Y,Y,Y,Y,Y,Y,Y
1022 % left,B,B,B,B,B,B,B,B,B
1023 % right,G,G,G,G,G,G,G,G,G
1024 % front,O,O,O,O,O,O,O,O,O
1025 % back,R,R,R,R,R,R,R,R,R
1026 % checkstate
1027 % rotation,U,D,L,R
1028 % rotation,U,D,L,R
1029 %\end{verbatim}
1030 %\end{quote}
1031 % Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the string ``\texttt{rotation,U,D,L,R}''
1032 % being written twice to the \texttt{rubikstate.dat} file, as shown above.
1033 %
1034 % Alternatively, if we used the command
1035 % \verb!\RubikRotation{random, 45}! then the last line written to the file
1036 % would be the string ``\texttt{rotation,random,45}'', as follows:
1037 %\begin{quote}
1038 % \begin{verbatim}
1039 % % filename: rubikstate.dat
1040 % cubesize,three
1041 % up,W,W,W,W,W,W,W,W,W
1042 % down,Y,Y,Y,Y,Y,Y,Y,Y,Y
1043 % left,B,B,B,B,B,B,B,B,B
1044 % right,G,G,G,G,G,G,G,G,G
1045 % front,O,O,O,O,O,O,O,O,O
1046 % back,R,R,R,R,R,R,R,R,R
1047 % checkstate
1048 % rotation,random,45
1049 %\end{verbatim}
1050 %\end{quote}
1051 % A \cmd{\CheckState} command triggers the same sequence of events except
1052 % that no ``\texttt{rotation,....}'' line is written.
1053 %
1054 % The action of the Perl script \texttt{rubikrotation.pl} is controlled by
1055 % the keywords (first argument of
1056 % each line) associated with each line of the file \texttt{rubikstate.dat}.
1057 % When control passes from \LaTeX\ to Perl, the script \texttt{rubikrotation.pl} starts
1058 % by loading the current rubikstate (prompted by the keywords `\texttt{up}', `\texttt{down}',
1059 % `\texttt{left}', `\texttt{right}', `\texttt{front}', `\texttt{back}'), and performing
1060 % a syntax check---significant syntax errors at this stage
1061 % will cause the program to issue appropriate error messages and then terminate cleanly.
1062 % Next, the Perl script performs some basic cube checks
1063 % (prompted by the key word `\texttt{checkstate}'), and then the program processes
1064 % the sequence of Rubik rotations (prompted by the keyword
1065 % `\texttt{rotation}'). If, instead, the second argument of the `\texttt{rotation,...}' string
1066 % is the keyword `\texttt{random}', and provided this is followed by a valid integer, say $n$,
1067 % then the Perl script performs a sequence of $n$ random rotations.
1068 % Finally, the Perl script writes the final rubikstate to the text file
1069 % \texttt{rubikstateNEW.dat}. All error messages are written to the
1070 % text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log-file.
1071 % The Perl script now closes all open files and terminates.
1072 %
1073 % Control then passes back to \LaTeX\ (still in \texttt{rubikrotation.sty} processing
1074 % the \cmd{\RubikRotation} command---see Section~\ref{sec:rubikrotationcode}, line~115);
1075 % its next action is to input the file
1076 % \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands
1077 % (in the \texttt{.tex} file) then this cycle repeats accordingly.
1078 % Eventually a \cmd{\Draw...} command is reached (in the \texttt{.tex} file) and
1079 % the final rubikstate is drawn in a TikZ picture environment.
1080 %
1081 % If the TikZ picture environment is followed by a \cmd{\ShowErrors} command,
1082 % then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed
1083 % immediately under the graphic. Once the graphic is error-free, then the
1084 % \cmd{\ShowErrors} command can be removed or commented out.
1085 %
1086 % Alternatively, when processing a long document, it can be useful to place
1087 % a \cmd{\ShowErrors} command at the end of the document, where it will list
1088 % all errors which occurred. Once any errors have been fixed, this command can be
1089 % removed or commented out.
1090 %
1091 % Note that if a \textsc{bash} file is used to coordinate the process then it is often
1092 % convenient to use the Linux \texttt{grep} utility to alert the user to any run-time errors,
1093 % by using \texttt{grep} to scan the \texttt{rubikstateERRORS.dat} file at the end of
1094 % the run; for example, as follows:
1095 %\begin{quote}
1096 %\begin{verbatim}
1097 % pdflatex --shell-escape myfile.tex
1098 % echo "...checking error file"
1099 % grep ERROR ./rubikstateERRORS.dat
1100 %\end{verbatim}
1101 %\end{quote}
1102 %
1103 %
1104 %
1105 %
1106 % \section{Change history}
1107 %
1108 % \begin{itemize}
1109 %
1110 % \item Version 5.0 (February 2018)
1111 %
1112 % --- minor bugfixes and better syntax checking in the Perl program.
1113 % The cube size being processed (ie 3x3x3 or 2x2x2) is now detected by the program.
1114 %
1115 % --- the command \cmd{\CheckState} replaces the earlier
1116 % \cmd{\CheckRubikState} command in order
1117 % to avoid confusion, now that we are able to process both the 3x3x3 cube (Rubik cube)
1118 % and also the 2x2x2 cube (Two cube)
1119 % (see Sections~\ref{sec:checkstate} and \ref{sec:checkstatecode} (code)).
1120 % The original command is retained (for now) for backward compatibility.
1121 % \verb!\CheckRubikState! $\rightarrow$ \verb!\CheckState!
1122 %
1123 % --- the command \cmd{\ShowErrors} replaces the earlier
1124 % \cmd{\ShowRubikErrors} command in order
1125 % to avoid confusion now, that we are able to process both the 3x3x3 cube (Rubik cube)
1126 % and also the 2x2x2 cube (Two cube)
1127 % (see Sections~\ref{sec:showerrors} and \ref{sec:showerrorscode} (code)).
1128 % The original command is retained (for now) for
1129 % backward compatibility. \verb!\ShowRubikErrors! $\rightarrow$ \verb!\ShowErrors!
1130 %
1131 %
1132 %
1133 %
1134 %
1135 % \item Version 4.0 (March 2017)
1136 %
1137 % --- The \cmd{\RubikRotation} command has been enhanced to allow its argument to include
1138 % so-called repeat-blocks (rotation-sequences which can be repeated multiple times), and
1139 % info-blocks for holding sequence metadata (see Section~\ref{sec:rubikrotationcmd}).
1140 % Syntax checking of the \cmd{\RubikRotation} argument is much improved
1141 % (see \texttt{rubikrotationPL.pdf} for details of the Perl script).
1142 %
1143 % --- Four new macros which hold derived data (see Section~\ref{sec:rubikrotationcmd}).
1144 % \begin{quote}
1145 % \cmd{\SequenceName}
1146 % \newline\cmd{\SequenceInfo}
1147 % \newline\cmd{\SequenceShort}
1148 % \newline\cmd{\SequenceLong}
1149 % \end{quote}
1150 %
1151 % --- Better syntax checking of the \cmd{\RubikRotation} argument by the Perl program \texttt{rubikrotation.pl}.
1152 %
1153 %
1154 %
1155 % \item Version 3.0 (25 September 2015)
1156 %
1157 % --- The \cmd{\RubikRotation} command now actions multiple instances of its argument
1158 % as determined by an optional `repeat' \oarg{integer}. For example the command
1159 % \cmd{\RubikRotation[3]\{R,x\}} is equivalent to the command \cmd{\RubikRotation\{R,x,R,x,R,x\}}
1160 % (see Sections~\ref{sec:rubikrotationcmd} and \ref{sec:rubikrotationcode}).
1161 %
1162 % --- If a comma separated element used as an argument for the \cmd{\RubikRotation}
1163 % command is prefixed with either a * or [ or ] character then it is not actioned
1164 % as a rotation (see Section~\ref{sec:prefixedargument}).
1165 %
1166 % --- The Perl script \texttt{rubikrotation.pl} now has command-line switches,
1167 % including \texttt{-h} to show some `help' and `usage' information
1168 % (see Section~\ref{sec:placingfiles}).
1169 %
1170 % --- A `man' file (manual file) for the Perl script \texttt{rubikrotation.pl} is now
1171 % included in the package.
1172 %
1173 % --- The Perl script \texttt{rubikrotation.pl} now uses as input and output file-names
1174 % those specified in the command-line of the CALLing program. This now allows the
1175 % script \texttt{rubikrotation.pl} to be used as a stand-alone tool (see the
1176 % \texttt{rubikrotation} `man' file for details).
1177 %
1178 % --- The documentation for the Perl script \texttt{rubikrotation.pl} is in the
1179 % accompanying file \texttt{rubikrotationPL.pdf}.
1180 %
1181 % --- Fixed typos, index and minor errors in the documentation.
1182 %
1183 %
1184 % \item Version 2.0 (5 February, 2014)
1185 %
1186 % --- First release.
1187 %
1188 % \end{itemize}
1189 %
1190 %
1191 %
1192 %
1193 %
1194 % \section{References}
1195 % \label{sec:references}
1196 %
1197 %\begin{itemize}
1198 %
1199 % \item Abrahams PW, Berry K and Hargreaves KA (1990). \textit{\TeX\ for the impatient}
1200 % (Addison-Wesley Publishing Company), page~292.
1201 % {\newline}Available from: \url{http://www.ctan.org/pkg/impatient}
1202 % {\newline}[\,re:~\cmd{\rubikpercentchar} and \cmd{\@comment} in Section~\ref{sec:abrahams}\,]
1203 %
1204 %
1205 % \item Eijkhout V (1992). \textit{\TeX\ by topic: a {\TeX}nician's reference}.
1206 % (Addison-Wesley Publishing Company), pages~232 \&~238.
1207 % {\newline}Available from: \url{https://bitbucket.org/VictorEijkhout/tex-by-topic/}
1208 % [\,re:~\cmd{\string} in Section~\ref{sec:eijkhout}\,]
1209 % [\,re:~\cmd{\write} in Section~\ref{sec:seq-as-macros}\,]
1210 %
1211 %
1212 % \item Feuers\"{a}nger C (2015). Notes on programming in \TeX.
1213 % {\newline}(revision: 1.12.1-32-gc90572c; 2015/07/29)
1214 % \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf}
1215 % {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,]
1216 %
1217 % \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm}
1218 %
1219 % \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package, v3.0.
1220 % \newline\url{http://www.ctan.org/pkg/rubik},
1221 %
1222 %
1223 % \item Randelshofer website (Randelshofer W). \url{http://www.randelshofer.ch/rubik/}
1224 % \ [\,re:~sequences and supersetENG notation\,]
1225 %
1226 %
1227 % \item Reid website (Reid M). \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html}
1228 % \ [\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,]
1229 %
1230 %
1231 % \item Tellechea C and Segletes SB (2016). The \textsf{listofitems} package, v1.2
1232 % \newline\url{http://www.ctan.org/pkg/listofitems}
1233 %
1234 %\end{itemize}
1235 %
1236 %
1237 %
1238 %
1239 %
1240 % ^^A ==================================================
1241 % \StopEventually{\PrintIndex}
1242 %
1243 %
1244 %
1245 % \section[The code]{The code (\texttt{rubikrotation.sty})}
1246 % \label{sec:thecode}
1247 %
1248 % {\noindent}In the following, the term `Perl script' denotes the script
1249 % \texttt{rubikrotation.pl}. Useful information regarding the
1250 % \TeX\ \cmd{\write} command is given in Eijkhout (1992), \S\,30.2.3 (page~238).
1251 % For the means of including a `\%' character in the token list of \cmd{\write} see
1252 % Abrahams \textit{et.~al} (1990).
1253 %
1254 % \subsection{Package heading}
1255 % \label{sec:CodePackageHeading}
1256 %
1257 % \begin{macrocode}
1258 %<*rubikrotation>
1259 \def\RRfileversion{5.0}%
1260 \def\RRfiledate{2018/02/25}% 25 February 2018
1261 \NeedsTeXFormat{LaTeX2e}
1262 \ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)]
1263 % \end{macrocode}
1264 %
1265 %
1266 % {\noindent}The package requires \texttt{rubikcube.sty}. However \texttt{rubikcube.sty}
1267 % is not automatically loaded (for the moment at least) since this makes it difficult
1268 % to errorcheck new versions.
1269 % \begin{macrocode}
1270 \@ifpackageloaded{rubikcube}{}{%
1271 \typeout{---rubikrotation requires the rubikcube package.}%
1272 }%
1273 % \end{macrocode}
1274 %
1275 %
1276 %
1277 % {\noindent}The \rubikrotation\ package requires access to the \textsf{fancyvrb} package
1278 % for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying
1279 % the error file (see Section~\ref{sec:showerrors}).
1280 % \begin{macrocode}
1281 \@ifpackageloaded{fancyvrb}{}{%
1282 \typeout{---rubikrotation requires the fancyvrb package%
1283 for VerbatimInput{} command.}%
1284 \RequirePackage{fancyvrb}}
1285 % \end{macrocode}
1286 %
1287 %
1288 % {\noindent}For the \cmd{\write18} syntax to work with
1289 % Lua\TeX\ (so we can access system commands) we require
1290 % the recent \textsf{shellesc} package, which we load using the
1291 % \textsf{ifluatex} conditional (see Section~\ref{sec:shellescape}).
1292 % \begin{macrocode}
1293 \@ifpackageloaded{ifluatex}{}{%
1294 \typeout{---rubikrotation requires the ifluatex package.}%
1295 \RequirePackage{ifluatex}}
1296 \ifluatex%
1297 \@ifpackageloaded{shellesc}{}{%
1298 \typeout{---rubikrotation requires the shellesc package
1299 to run using Lua\LaTeX.}%
1300 \RequirePackage{shellesc}}
1301 \fi%
1302 % \end{macrocode}
1303 %
1304 %
1305 % \medskip
1306 %
1307 % \subsection{Some useful commands}
1308 % \label{sec:usefulcommands}
1309 %
1310 % \begin{macro}{\rubikrotation}
1311 % First we create a suitable logo
1312 % \begin{macrocode}
1313 \newcommand{\rubikrotation}{\textsc{rubikrotation}}
1314 \newcommand{\Rubikrotation}{\textsc{Rubikrotation}}
1315 % \end{macrocode}
1316 % \end{macro}
1317 %
1318 %
1319 %
1320 % \begin{macro}{\@print}
1321 % We need a simple print command to facilitate writing output to a file.
1322 % \begin{macrocode}
1323 \newcommand{\@print}[1]{\immediate\write\outfile{#1}}
1324 % \end{macrocode}
1325 % \end{macro}
1326 %
1327 %
1328 %
1329 % \begin{macro}{\@comment}
1330 % \begin{macro}{\@commentone}
1331 % We also require access to the `\%' character so we can (a)~write comments to
1332 % files, including the log file, and (b)~place a trailing `\%' in a line of code
1333 % written to a file.
1334 %
1335 % To achieve this we define the `\%' character as \cmd{\rubikpercentchar}
1336 % (modified from: Abrahams PW, Berry K and Hargreaves KA (1990), p~292)
1337 % [see refs Section~\ref{sec:references}]\label{sec:abrahams},
1338 % and also two `comment' commands which implement it. This `workaround'
1339 % is necessary because \TeX\ does not allow the use of the \cmd{\%} command
1340 % for placing a `\%' character in the token list of \cmd{\write}.
1341 % See Abrahams \textit{et.~al} (1990) for details.
1342 % \begin{macrocode}
1343 {\catcode`\%=12 \global\def\rubikpercentchar{%}}%
1344 \newcommand{\@comment}{\rubikpercentchar\rubikpercentchar\space}%
1345 \newcommand{\@commentone}{\rubikpercentchar}%
1346 % \end{macrocode}
1347 % \end{macro}
1348 % \end{macro}
1349 %
1350 %
1351 %
1352 % \begin{macro}{\rubikperlname}
1353 % This holds the name of the Perl script. A configuration-file
1354 % (\verb!rubikrotation.cfg!) can be used to change the default name of the
1355 % Perl script using a renewcommand (see Section~\ref{sec:configfile}).
1356 % \begin{macrocode}
1357 \newcommand{\rubikperlname}{rubikrotation}
1358 % \end{macrocode}
1359 % \end{macro}
1360 % Note that here we are assuming that the script is an executable file.
1361 %
1362 % \begin{macro}{\rubikperlcmd}
1363 % This holds the command-line code for calling the Perl script
1364 % Note that the command-line requires a mandatory input filename preceded
1365 % by the \texttt{-i}~switch. An optional output filename (preceded by the
1366 % \texttt{-o}~switch) may be used, otherwise the default output filename of
1367 % \texttt{rubik-OUT.dat} will be used.
1368 %
1369 % Note that it is very important that we do actually specify an
1370 % output filename (for receiving data from the Perl script). This is because
1371 % (a)~The Perl script \texttt{rubikrotation.pl} is currently configured to read its
1372 % output filename as an argument from the command-line (so it can be flexibly
1373 % used as a stand-alone script for processing a given Rubik state through a
1374 % sequence of rotations), and (b)~\texttt{rubikrotation.sty} is currently
1375 % configured to read its input (i.e.,~data generated by the Perl script)
1376 % from the file \texttt{rubikstateNEW.dat}.
1377 % \begin{macrocode}
1378 \newcommand{\rubikperlcmd}{\rubikperlname\space%
1379 -i rubikstate.dat -o rubikstateNEW.dat}
1380 % \end{macrocode}
1381 % Remember to use the \cmd{\space} macro following the \cmd{\rubikperlname} macro
1382 % in order to generate the mandatory space before the first
1383 % command-line argument.
1384 %
1385 % A plain-text configuration-file \verb!rubikrotation.cfg! can be used to
1386 % change the default command-line code using a renewcommand
1387 % (see Section~\ref{sec:configfile}).
1388 % \end{macro}
1389 %
1390 %
1391 % \subsection{Configuration file}
1392 %
1393 % If a configuration file exists (\texttt{rubikrotation.cfg}) then input it here,
1394 % i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd}
1395 % macros and \textit{before} creating the \texttt{rubikstateERRORS.dat} file.
1396 % \begin{macrocode}
1397 \typeout{---checking for config file (rubikrotation.cfg)...}
1398 \IfFileExists{rubikrotation.cfg}{%
1399 \input{rubikrotation.cfg}%
1400 }{\typeout{---no config file available}%
1401 }%
1402 % \end{macrocode}
1403 %
1404 %
1405 % \subsection{Clean file rubikstateNEW.dat}
1406 %
1407 % {\noindent}We need to clean out any existing (old) rubikstateNEW.dat file,
1408 % since if the TeX shell command-line switch is accidentally not used then the Perl script
1409 % \texttt{rubikrotation.pl} will not be CALLed, and hence this file will not be renewed
1410 % (i.e.,~an `old' image may be used).
1411 % \begin{macrocode}
1412 \typeout{---cleaning file rubikstateNEW.dat}%
1413 \newwrite\outfile%
1414 \immediate\openout\outfile=rubikstateNEW.dat%
1415 \@print{\@comment rubikstateNEW.dat}%
1416 \immediate\closeout\outfile%
1417 % \end{macrocode}
1418 %
1419 %
1420 % \subsection{rubikstateERRORS.dat}
1421 %
1422 % {\noindent}We first open the file \texttt{rubikstateERRORS.dat} which is used
1423 % by the Perl script \texttt{rubikrotation.pl} for writing its error-messages to.
1424 % This file is displayed by the command
1425 % \cmd{\ShowErrors}.
1426 %
1427 % \textsc{important note}: this file is created fresh each time LaTeX is run,
1428 % and hence the Perl script only appends data to it during the \LaTeX\ run,
1429 % so this file just grows until either it is destroyed or recreated---this is
1430 % a useful feature since the file accumulates all error messages as the
1431 % \texttt{.tex} file is processed.
1432 % We can't make the Perl script create the file since the Perl script is only
1433 % CALLed if we use a \cmd{\RubikRotation} or \cmd{\CheckRubikState}
1434 % command (which we may not\,!)---so it has to be created here.
1435 % \begin{macrocode}
1436 \typeout{---creating file rubikstateERRORS.dat}%
1437 \newwrite\outfile%
1438 \immediate\openout\outfile=rubikstateERRORS.dat%
1439 \@print{\@comment ShowErrors (rubikstateERRORS.dat)}%
1440 \@print{\@comment ---------------------------------}%
1441 \immediate\closeout\outfile%
1442 % \end{macrocode}
1443 %
1444 %
1445 % \subsection{Setting up file-access for new files}
1446 %
1447 % Having set up all the primary files, we now need to set up a newwrite for
1448 % all subsequent file openings (e.g.,~for \texttt{rubikstate.dat} and saving
1449 % to arbitrary file-names by the \cmd{\SaveRubikState} command). Otherwise, we
1450 % can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use
1451 % \texttt{openout7} when opening and writing to files. We will implement new
1452 % openings using the command \verb!\@openstatefile! (see below).
1453 % \begin{macrocode}
1454 \typeout{---setting up newwrite for rubikrotation.sty to use...}%
1455 \newwrite\outfile%
1456 % \end{macrocode}
1457 %
1458 %
1459 % \begin{macro}{\@openstatefile}
1460 % \begin{macro}{\@closestatefile}
1461 % We also need commands for easy file opening and closing
1462 % for new instances of the file \texttt{rubikstate.dat} etc.
1463 % Note that for this we are therefore using the same outfile number as set up
1464 % by the \verb!\newwrite...! above.
1465 % \begin{macrocode}
1466 \newcommand{\@openstatefile}{\immediate\openout\outfile=rubikstate.dat}
1467 \newcommand{\@closestatefile}{\immediate\closeout\outfile}
1468 % \end{macrocode}
1469 % \end{macro}
1470 % \end{macro}
1471 %
1472 %
1473 % \subsection{Saving the Rubik state}
1474 %
1475 % \begin{macro}{\@printrubikstate}
1476 % This internal command writes the Rubik configuration to
1477 % the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command
1478 % (see Sections~\ref{saverubikstate} and \ref{generaloverview}).
1479 % The file \texttt{rubikstate.dat} is read by the Perl script, and represents
1480 % the state on which the new \cmd{\RubikRotation} command acts.
1481 % Note that we include the line \texttt{cubesize,three} to inform the Perl script
1482 % that the cube is a 3x3x3 cube (this is used in the `random' subroutine).
1483 %
1484 % The actual state (colour state) is simply an ordered sequence of the faces and the colours
1485 % associated with each facelet of a face. The colour associated with a particular facelet
1486 % is held by the variable for that facelet. For example, the top-left facelet associated with
1487 % the \textsc{front} face is held in the variable \cmd{\Flt} (see Section~\ref{saverubikstate}).
1488 % Further relevant documentation is in the \textsc{rubikcube} package.
1489 % \begin{macrocode}
1490 \newcommand{\@printrubikstate}{%
1491 \@print{cubesize,three}%
1492 \@print{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}%
1493 \@print{down,\Dlt,\Dmt,\Drt,\Dlm,\Dmm,\Drm,\Dlb,\Dmb,\Drb}%
1494 \@print{left,\Llt,\Lmt,\Lrt,\Llm,\Lmm,\Lrm,\Llb,\Lmb,\Lrb}%
1495 \@print{right,\Rlt,\Rmt,\Rrt,\Rlm,\Rmm,\Rrm,\Rlb,\Rmb,\Rrb}%
1496 \@print{front,\Flt,\Fmt,\Frt,\Flm,\Fmm,\Frm,\Flb,\Fmb,\Frb}%
1497 \@print{back,\Blt,\Bmt,\Brt,\Blm,\Bmm,\Brm,\Blb,\Bmb,\Brb}%
1498 }
1499 % \end{macrocode}
1500 % \end{macro}
1501 %
1502 %
1503 % \subsection{SaveRubikState command}
1504 % \label{sec:eijkhout}
1505 %
1506 % \begin{macro}{\SaveRubikState}
1507 % The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state
1508 % to a named file in the format of a Rubik command (so it can then be processed
1509 % by \LaTeX). Note that in order to actually write a LaTeX
1510 % command to a file without a trailing space one must prefix the command with the
1511 % \cmd{\string} command (see Eijkhout (1992), p~238)
1512 % [see refs Section~\ref{sec:references}]\label{sec:eijkhout}.
1513 %
1514 % Note that this macro uses the internal commands \cmd{\@comment} (`\%\%'),
1515 % \cmd{\@commentone} (`\%') and \cmd{\@print}. \#1 is the output filename.
1516 % We use several \cmd{\typeout} commands to write to the log file.
1517 % An example of one of the lines of code we are trying to output to the
1518 %\texttt{rubikstateNEW.dat} file is as follows:
1519 % {\newline}\verb!\RubikFaceUp{W}{W}{G}{W}{W}{G}{B}{B}{Y}%!
1520 % \begin{macrocode}
1521 \newcommand{\SaveRubikState}[1]{%
1522 \typeout{---NEW save command------------------}%
1523 \typeout{---command = SaveRubikState{#1}}%
1524 \typeout{---saving Rubik state data to file #1}%
1525 \immediate\openout\outfile=#1%
1526 \@print{\@comment filename: #1\@commentone}%
1527 \@print{\string\RubikFaceUp%
1528 {\Ult}{\Umt}{\Urt}{\Ulm}{\Umm}{\Urm}{\Ulb}{\Umb}{\Urb}\@commentone}%
1529 \@print{\string\RubikFaceDown%
1530 {\Dlt}{\Dmt}{\Drt}{\Dlm}{\Dmm}{\Drm}{\Dlb}{\Dmb}{\Drb}\@commentone}%
1531 \@print{\string\RubikFaceLeft%
1532 {\Llt}{\Lmt}{\Lrt}{\Llm}{\Lmm}{\Lrm}{\Llb}{\Lmb}{\Lrb}\@commentone}%
1533 \@print{\string\RubikFaceRight%
1534 {\Rlt}{\Rmt}{\Rrt}{\Rlm}{\Rmm}{\Rrm}{\Rlb}{\Rmb}{\Rrb}\@commentone}%
1535 \@print{\string\RubikFaceFront%
1536 {\Flt}{\Fmt}{\Frt}{\Flm}{\Fmm}{\Frm}{\Flb}{\Fmb}{\Frb}\@commentone}%
1537 \@print{\string\RubikFaceBack%
1538 {\Blt}{\Bmt}{\Brt}{\Blm}{\Bmm}{\Brm}{\Blb}{\Bmb}{\Brb}\@commentone}%
1539 \immediate\closeout\outfile%
1540 \typeout{-----------------------------------------}%
1541 }%
1542 % \end{macrocode}
1543 % \end{macro}
1544 %
1545 %
1546 % \subsection{RubikRotation command}
1547 % \label{sec:rubikrotationcode}
1548 %
1549 % \begin{macro}{\RubikRotation}
1550 % The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence}
1551 % command (a)~writes the current Rubik state to the file \texttt{rubikstate.dat},
1552 % (b)~writes the rotation sequence (either once or multiple times depending
1553 % on the value of the optional integer argument), and then (c)~CALLs the
1554 % Perl script \texttt{rubikrotation.pl}. It~also writes comments to the
1555 % data file and also to the log file.
1556 %
1557 % The way we allow the user to (optionally) process the main argument multiple
1558 % times is simply by writing the associated output command multiple
1559 % times to the output data-file. Consequently, we require the \cmd{\RubikRotation}
1560 % command to allow a square-bracket optional
1561 % argument (a non-negative integer) to specify the number of such repeats.
1562 % In order to implement this optional argument facility we use two macros
1563 % (countingloop and loopcounter) detailed by Feuers\"{a}nger (2015)
1564 % [\,see refs Section~\ref{sec:references}\,]\label{sec:feuersanger},
1565 % as follows:
1566 % \begin{macrocode}
1567 %% Two macros detailed by Feuersaenger (2015)
1568 \long\def\@countingloop#1 in #2:#3#4{%
1569 #1=#2 %
1570 \@loopcounter{#1}{#3}{#4}%
1571 }
1572 %%--------------------------
1573 \long\def\@loopcounter#1#2#3{%
1574 #3%
1575 \ifnum#1=#2 %
1576 \let\next=\relax%
1577 \else
1578 \advance#1 by1 %
1579 \def\next{\@loopcounter{#1}{#2}{#3}}%
1580 \fi
1581 \next
1582 }
1583 % \end{macrocode}
1584 % Having defined the above two macros we can now implement an optional
1585 % argument (a repeat number) indicating the number of times we want
1586 % the command to write the main argument to the output data file.
1587 % \begin{macrocode}
1588 \newcommand{\RubikRotation}[2][1]{%
1589 \typeout{---TeX process---------------------------}%
1590 \typeout{---script = rubikrotation.sty v\RRfileversion\space (\RRfiledate)}%
1591 \typeout{---NEW rotation command}%
1592 \typeout{---command = RubikRotation[#1]{#2}}%
1593 \typeout{---writing current cube state to file rubikstate.dat}%
1594 \@openstatefile% open data file
1595 \@print{\@comment filename: rubikstate.dat}%
1596 \@print{\@comment written by rubikrotation.sty%
1597 =v\RRfileversion\space (\RRfiledate)}%
1598 \@printrubikstate%
1599 %% countingloop code from Feuersaenger (2015)
1600 \newcount\ourRRcounter%
1601 \@countingloop{\ourRRcounter} in 1:{#1}{%
1602 \immediate\write\outfile{rotation,#2}}%
1603 \@closestatefile% close data file
1604 \typeout{---CALLing Perl script (rubikrotation.pl)}%
1605 \immediate\write18{\rubikperlcmd}%
1606 \typeout{---inputting NEW datafile (data written by Perl script)}%
1607 \input{rubikstateNEW.dat}%
1608 \typeout{-----------------------------------------}%
1609 }
1610 % \end{macrocode}
1611 % \end{macro}
1612 % Note that the new \cmd{\ShellEscape} command implemented by the recent
1613 % \textsf{shellesc} package is equivalent to \cmd{\immediate}\cmd{\write18} (see above),
1614 % and so we probably ought to use \cmd{\ShellEscape} instead in future (and hence load
1615 % \textsf{shellesc} automatically). At present, however, we leave the user to make
1616 % sure that the \textsf{shellesc} package is actually available on their system.
1617 %
1618 %
1619 %
1620 % \subsection{ShowErrors command}
1621 % \label{sec:showerrorscode}
1622 %
1623 % \begin{macro}{\ShowErrors}
1624 % This command inputs the file \texttt{rubikstateERRORS.dat}
1625 % (output by the Perl program).
1626 % \begin{macrocode}
1627 \newcommand{\ShowErrors}{%
1628 \typeout{---ShowErrors: inputting file rubikstateERRORS.dat}%
1629 \VerbatimInput{rubikstateERRORS.dat}%
1630 }
1631 % \end{macrocode}
1632 % Since this command replaces the original command = \cmd{\ShowRubikErrors}, we will
1633 % retain the original command for backward compatibility (for the moment at least).
1634 % \begin{macrocode}
1635 \newcommand{\ShowRubikErrors}{\ShowErrors}
1636 % \end{macrocode}
1637 % \end{macro}
1638 %
1639 %
1640 % \subsection{CheckState command}
1641 % \label{sec:checkstatecode}
1642 %
1643 % \begin{macro}{\CheckState}
1644 % This command triggers the Perl script to implement
1645 % some simple error checking of the Rubik configuration (state).
1646 % This command (a)~writes the current Rubik state to the file
1647 % \texttt{rubikstate.dat}, (b)~writes the keyword `checkstate' to the
1648 % same file, and then (c)~CALLs the Perl script.
1649 % It also writes comments to the data file and also to the log file.
1650 %
1651 % Note (1)~that the command \cmd{\@printrubikstate} actually writes the
1652 % current state to the file \texttt{rubikstate.dat}, (2)~the keyword `checkstate'
1653 % triggers the Perl program to do a simple numerical check on the number
1654 % of facelets with each colour.
1655 %
1656 % Note also that the \cmd{\CheckState} command replaces the earlier
1657 % \cmd{\CheckRubikState}, but we retain the old command for backwards
1658 % compatibility (for the moment).
1659 % \begin{macrocode}
1660 \newcommand{\CheckState}{%
1661 \typeout{---NEW check command------------------}%
1662 \typeout{---command = CheckState}%
1663 \typeout{---writing current cube state to file rubikstate.dat}%
1664 \@openstatefile% opens data file
1665 \@print{\@comment filename: rubikstate.dat}%
1666 \@printrubikstate%
1667 \immediate\write\outfile{checkstate}%
1668 \@closestatefile% close data file
1669 \typeout{---running Perl script (rubikrotation.pl)}%
1670 \immediate\write18{\rubikperlcmd}%
1671 \typeout{---inputting NEW datafile (data written by Perl script)}%
1672 \input{rubikstateNEW.dat}%
1673 \typeout{-----------------------------------------}%
1674 }
1675 \newcommand{\CheckRubikState}{\CheckState}
1676 % \end{macrocode}
1677 % \end{macro}
1678 %
1679 %
1680 % --------------------------
1681 % End of this package
1682 % --------------------------
1683 % \begin{macrocode}
1684 %</rubikrotation>
1685 % \end{macrocode}
1686 %
1687 %
1688 %
1689 %
1690 % \Finale
1691 %
1692 \endinput
1693
1694
1695
1696
1697