% \iffalse meta-comment % rubikrotation.dtx % % version 3.0 % % Authors: RWD Nickalls (dick@nickalls.org) % and Apostolos Syropoulos (asyropoulos@yahoo.com) % Copyright 25 September 2015 RWD Nickalls + A Syropoulos % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either % version 1.3c of this license or (at your option) any % later version. The latest version of this licence is in % % http://www.latex-project.org/lppl.txt % %<*readme> % % The rubikrotation package provides a collection of LaTeX commands and macros % for the typesetting of Rubik cube configurations and rotation % sequences using the TikZ graphic language. % % Please report errors or suggestions for improvement to % % Dick Nickalls or Apostolos Syropoulos % % This package requires the basic TikZ package to be loaded already % % %<*driver> \listfiles \documentclass{ltxdoc} \IfFileExists{rubikrotation.sty}{\usepackage{rubikrotation}}{% \GenericWarning{rubikrotation.dtx}{Package file rubikrotation.sty not found. Documentation will be messed up!^^J (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J process rubikrotation.dtx again)^^J}\stop }% \usepackage{ifpdf} \usepackage{url,path} %% for references and paths \usepackage{graphicx} %% for the two pdf figs \usepackage{hypdoc} %% for pdf bookmarks + hyperref documenting of packages %%\OnlyDescription \EnableCrossrefs \PageIndex \CodelineIndex \CodelineNumbered \RecordChanges \setcounter{StandardModuleDepth}{1} \begin{document} \DocInput{rubikrotation.dtx} \PrintChanges \PrintIndex \end{document} % % \fi % % % % \CheckSum{310} % %%% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z %% Digits \0\1\2\3\4\5\6\7\8\9 %% Exclamation \! Double quote \" Hash (number) \# %% Dollar \$ Percent \% Ampersand \& %% Acute accent \' Left paren \( Right paren \) %% Asterisk \* Plus \+ Comma \, %% Minus \- Point \. Solidus \/ %% Colon \: Semicolon \; Less than \< %% Equals \= Greater than \> Question mark \? %% Commercial at \@ Left bracket \[ Backslash \\ %% Right bracket \] Circumflex \^ Underscore \_ %% Grave accent \` Left brace \{ Vertical bar \| %% Right brace \} Tilde \~} % % % % \title{The \rubikrotation\ package} % % \author{ % RWD Nickalls (dick@nickalls.org) \\ % A Syropoulos (asyropoulos@yahoo.com) % } % \date{This file describes version \RRfileversion\ (\RRfiledate)\\ % \texttt{www.ctan.org/pkg/rubik}} % \maketitle % % \begin{abstract} % The \rubikrotation\ package is a dynamic extension for the % \textsc{rubikcube} package (both are part of the Rubik `bundle'). % The package provides the \cmd{\RubikRotation} command which % processes a sequence of Rubik rotation moves on-the-fly (using the Perl script % \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration). % The \rubikrotation\ package also provides a command for implementing some basic % checking of the Rubik cube state (\cmd{\CheckRubikState}), and one % for displaying any errors (\cmd{\ShowRubikErrors}). % % The \rubikrotation\ package requires access to the \TeX\ \texttt{write18} % facility, which is enabled by using the \texttt{--shell-escape} command-line switch. % The~\rubikrotation\ package has been road-tested on a Microsoft % platform (with MiKTeX and Strawberry Perl), on a Linux platform % (Mandriva using {\TeX}Live), and on a Solaris platform (OpenIndiana). % \end{abstract} % % \begin{minipage}{11cm} % \centering % \ifpdf % \includegraphics[width=10cm]{Rubikrot-doc-figD.pdf} % \else % \fi % \end{minipage} % % \vspace{-1\baselineskip} % % \tableofcontents % % \section{Introduction} % % The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} package. % It consists of a style option (\texttt{rubikrotation.sty}), a % Perl script (\texttt{rubikrotation.pl}) and some examples. % % 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. % % The \rubikrotation\ package has been road-tested on a Microsoft % platform (with MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl' % (\texttt{http://strawberryperl.com}) is a free Perl % environment for MS Windows, designed to be as close as possible to the Perl % environment of Unix/Linux systems.}), on a Linux platform (Mandriva using % {\TeX}Live), and on a Solaris platform (OpenIndiana). % % The following commands are made available by \texttt{rubikrotation.sty}: % \begin{quote} % \begin{verbatim} % \RubikRotation[]{} % \SaveRubikState % \CheckRubikState % \ShowRubikErrors %\end{verbatim} % \end{quote} % % % \section{Requirements} % % The \rubikrotation\ package requires the TikZ and the \textsc{rubikcube} packages. % % % \section{Installation} % % \subsection{Generating the files} % % Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it. % This will generate the following files: %\begin{quote} % \begin{verbatim} % rubikrotation.ins % rubikrotation.dtx % rubikrotation.pdf --this document % rubikrotation.pl --Perl script % rubikrotationPL.pdf --documentation of rubikrotation.pl % rubikrotation.1 --the man file % Rubikrot-doc-figA.pdf % Rubikrot-doc-figB.pdf % Rubikrot-doc-figC.pdf % Rubikrot-doc-figD.pdf % examples.tex % examples.pdf % examples.sh % examples.bat %\end{verbatim} %\end{quote} % Note that the package includes an `examples' file (\texttt{examples.tex}) % as well as associated \texttt{.sh} (Linux) and \texttt{.bat} (Microsoft) batch % files which can be used to facilitate processing the file. % The main package documentation is the file \texttt{rubikrotation.pdf}. % % The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on % the file \texttt{rubikrotation.ins} as follows: %\begin{quote} %\begin{verbatim} % pdflatex rubikrotation.ins %\end{verbatim} %\end{quote} % The documentation file (\texttt{rubikrotation.pdf}) is then generated using the following % sequence of steps\,\footnote{Since the documentation includes a complicated indexing % system as well a \textsc{pdf} index and hyperef links (the package \texttt{hypdoc} % is used), then a lot of pdflatex runs are required. Prior to the first run it is % a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}: %\begin{quote} % \begin{verbatim} % pdflatex rubikrotation.dtx % pdflatex rubikrotation.dtx % makeindex -s gind.ist rubikrotation % makeindex -s gglo.ist -o rubikrotation.gls rubikrotation.glo % pdflatex rubikrotation.dtx % pdflatex rubikrotation.dtx %\end{verbatim} %\end{quote} % % % % \subsection{Placing the files} % \label{sec:placingfiles} % % Place the files either in a working directory, or where your system % will find them, e.g.,~in your \texttt{/texmf-local/} directory tree. % For example, on a Linux platform with a standard \TeX\ Directory Structure (TDS), then: % %\medskip %{\noindent}*.sty $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} %{\newline}*.cfg $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} %{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubik/} %{\newline}*.pl $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/scripts/rubik/} % %\medskip %{\noindent}\textsc{perl script}:\ \ Make the perl script executable % (\texttt{chmod +x rubikrotation.pl}), and then % rename the file as `rubikrotation' (i.e.,~with no file extension), and then place % the executable script into your current TeXLive binary directory, % e.g.,~\path!/user/local/texlive/YYYY/bin/i386-linux!. % % Sometimes the setting up of a simple one or two-line plain-text % configuration-file may be useful or even necessary, depending on your system % (see Section~\ref{sec:configfile} below). Such a file (if one exists) will % automatically be read by \texttt{rubikrotation.sty} providing the % file is named \texttt{rubikrotation.cfg}. % %\medskip %{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this file % (\texttt{rubikrotation.1}) would be typically located in the % directory \verb!/usr/share/man/man1!. % %\medskip %{\noindent}\textsc{file database}:\ \ Finally, (depending on your system) update the % \TeX\ file database. % For example, on a Linux platform this is achieved using the \texttt{texhash} command. % %\medskip %{\noindent}\textsc{quick test}:\ \ To test that your system can now run the perl % script, just type at the command-line %\begin{quote} % \begin{verbatim} % rubikrotation -h %\end{verbatim} %\end{quote} % which should generate something like the following: % \begin{verbatim} % This is rubikrotation version 3.0 % Usage: rubikrotation [-h] -i [-o ] % where, % [-h] gives this help listing % [-i] creates specified input file % [-o] creates specified output file % For documentation see: rubikrotation.pdf, % rubikrotationPL.pdf and rubikcube.pdf %\end{verbatim} % % % \section{Usage} % \label{sec:usage} % Load the packages \texttt{rubikcube.sty} % and \texttt{rubikrotation.sty} in the \TeX\ file preamble \textit{after} loading % the TikZ package (both Rubik packages require the TikZ package), for example, as follows: %\begin{quote} % \begin{verbatim} % \usepackage{tikz} % \usepackage{rubikcube,rubikrotation} %\end{verbatim} %\end{quote} % and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line switch % (see the following section). % % % \subsection{Enabling the \TeX\ `shell' facility} % % In order to enable the \TeX\ `write18' facility (so it can run the Perl script) % it is necessary to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch % as follows: %\begin{quote} % \begin{verbatim} % pdflatex --shell-escape filename.tex %\end{verbatim} %\end{quote} % In practice, it is probably most convenient to run this command via a % bash/batch file. For example, on a Linux platform the following bash file % will run the file, show any errors, and open the \textsc{pdf} using AcrobatReader. %\begin{quote} % \begin{verbatim} % pdflatex --shell-escape filename.tex % echo "...checking error file" % grep ERROR ./rubikstateERRORS.dat % acroread filename.pdf & %\end{verbatim} %\end{quote} % % % \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: %\begin{quote} % \begin{verbatim} % bash example-rot.sh %\end{verbatim} %\end{quote} % If processing this file gives unexpected results (e.g.,~the cubes appear not to % have experienced any rotations) check-out the associated log file to see if % the operating system had any difficulties finding files etc. % % % \subsection{Configuration-file} % \label{sec:configfile} % % A plain-text configuration-file with the name \texttt{rubikrotation.cfg} % (if one exists) will automatically be read by \texttt{rubikrotation.sty}. % The \rubikrotation\ package's facility to use a configuration-file allows the % user to change not only (a)~the filename of the Perl script (\texttt{rubikrotation.pl}), % but also (b)~the command-line code used by \texttt{rubikrotation.sty} for calling the % Perl script. This~sort of fine-tuning can be very useful, and sometimes may % even be necessary (depending on your system) for running the Perl script. % % For example, on some systems it maybe preferable to use a different \textsc{path}, % file-name and/or a different command-line code to call the script. % Such~a configuration-file can also facilitate testing a new Perl script having % a different name and location. % % % \DescribeMacro{\rubikperlname} % \DescribeMacro{\rubikperlcmd} % The configuration-file is essentially a convenient software vehicle for feeding % additional \LaTeX\ code to the style option \texttt{rubikrotation.sty}, and hence % allows the contents of some commands to be easily adjusted and/or fine-tuned. % For~the \rubikrotation\ package there are two particular commands we may wish to adjust. % The~first is that defining the filename of the Perl script, namely % \cmd{\rubikperlname}. The second is that defining the command-line call, % namely \cmd{\rubikperlcmd}. % The~default definitions in \texttt{rubikrotation.sty} (which assume the Perl % script is executable), are as follows: (they are detailed in % Section~\ref{sec:usefulcommands}) %\begin{quote} %\begin{verbatim} % \newcommand{\rubikperlname}{rubikrotation} % \newcommand{\rubikperlcmd}{\rubikperlname\space% % -i rubikstate.dat -o rubikstateNEW.dat} %\end{verbatim} %\end{quote} % Note the need here to use the \cmd{\space} command on the end of the backslash % command (\cmd{\rubikperlname}) in order to force a following % space---i.e.,~before the first command-line argument. The following examples % illustrate how the configuration-file may be used. % % \medskip % {\noindent}\textsc{example~1}:\ \ Suppose we wish to test out % a slightly modified Perl script % with the working (executable) name \texttt{rubikrotationR77}. In this case we % simply create, in the local working directory, a plain-text configuration-file % (called \texttt{rubikrotation.cfg}) which contains just the following line: %\begin{quote} %\begin{verbatim} %\renewcommand{\rubikperlname}{rubikrotationR77} %\end{verbatim} %\end{quote} % % \medskip % {\noindent}\textsc{example~2}:\ \ Alternatively, suppose we wish to test out % a new Perl script with the (non-executable) name \texttt{rubikrotationR55.pl}. % Now, in this particular case we will need to run the script using a % slightly different command, namely, % {\linebreak}\texttt{perl rubikrotationR55.pl ...}, and consequently we % need to implement both these changes in the configuration-file, as follows: %\begin{quote} %\begin{verbatim} %\renewcommand{\rubikperlname}{rubikrotationR55.pl} %\renewcommand{\rubikperlcmd}{perl \rubikperlname\space\% % -i rubikstate.dat -o rubikstateNEW.dat} %\end{verbatim} %\end{quote} %{\noindent}\textsc{placing the configuration-file}:\ \ The simplest arrangement is % just to include the \texttt{.cfg} file in the working `test' directory. % Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/} % directory tree (say, in \path!/usr/local/texlive/texmf-local/tex/latex/rubik/!), % but in this case one would then have to be careful to specify the % correct PATH for everything in order to enable your system to find all the % various components etc. % % Note that you can, of course, have several \texttt{.cfg} files, since the system will % read only one such file (the first one it finds starting with the current working % directory). Consequently, it may be useful to have one \texttt{.cfg} file in % your \texttt{/texmf-local/} dir (for running the standard Rubik package), % and another (different) \texttt{.cfg} file in your `test' directory. % % % \section{Commands} % % The \textit{only} `Rubik bundle' commands which \textit{must} be used inside a TikZ picture % environment are the \cmd{\Draw...} commands (these are all provided by % the \textsc{rubikcube} package), although most commands can be placed % inside a TikZ environment if you wish. % % However, using commands which influence the Rubik colour state % (e.g.,~the \cmd{\RubikRotation} command) outside the \texttt{tikzpicture}, % \texttt{minipage} or \texttt{figure} environments % generally offers maximum flexibility, since the effects of such commands when % used inside these environments remain `local' to the environment, and are not % therefore accessable outside that \textit{particular} environment % (see also Section~4.1 in the \textsc{rubikcube} documentation). % % Conversely, the only \rubikrotation\ command which should \textit{not} % be used inside a TikZ environment is the \cmd{\ShowRubikErrors} command % (see the notes on this command below). % % % \subsection[RubikRotation command]{\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. %\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}% %\end{verbatim} %\end{quote} % The \cmd{\RubikRotation} command results in \LaTeX\ first writing % the current Rubik state to a text file (\texttt{rubikstate.dat}), % and then calling the Perl 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: %\begin{quote} % \begin{verbatim} % \RubikRotation[3]{x,R,U} % \RubikRotation{x,R,U,x,R,U,x,R,U} %\end{verbatim} %\end{quote} % % \subsubsection{Sequences as macros} % \label{sec:seq-as-macros} % % Macros which are arguments of the \TeX\ \cmd{\write} command are expanded % on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see refs Section~\ref{sec:references}\,]. % Consequently we are able to use a sequence-defining macro as an argument for % the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows % one to store lots of different rotation sequences by name alone. % % For example, we can use the name `sixspot' for a macro denoting the rotation sequence % which generates the well known `sixspot' configuration (see the `patterns' page on the % Reid website)[\,see refs Section~\ref{sec:references}\,], as follows: %\begin{quote} % \begin{verbatim} % \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp} %\end{verbatim} %\end{quote} % With this new \cmd{\sixspot} command we are now able to generate the graphic (sixspot cube) % very easily using the following code---this time we demonstrate the use of the more convenient % \cmd{\ShowCube} command (which includes the \texttt{tikzpicture} environment): % % \medskip % % \begin{minipage}{6cm} % \begin{verbatim} % \RubikCubeSolved % \RubikRotation{\sixspot} % \ShowCube{3cm}{0.7}{\DrawRubikCubeRU} %\end{verbatim} % \end{minipage} % \begin{minipage}{3.4cm} % \centering % \ifpdf % \includegraphics[height=3cm]{Rubikrot-doc-figA.pdf} % \else % \fi % \end{minipage} % % \medskip % Providing such macros (when used as arguments) are comma separated (as the rotation codes % must be), then the \cmd{\RubikRotation} command can accommodate both rotation codes % and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!. % % % \subsubsection{Arguments prefixed with *, [, ]} % \label{sec:prefixedargument} % % If any of the comma separated arguments is prefixed with either *, [ or ] they are % interpreted as an inactive `string', and not as a rotation. This feature therefore % allows a string argument to be used as a label, which can be very useful. % % For example, we can use this facility to label the `sixspot' configuration mentioned above, % as follows: %\begin{quote} % \begin{verbatim} % \RubikRotation{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp} %\end{verbatim} %\end{quote} % In practice, it is quite useful to go one step further and include % the [\,] label feature in the \cmd{\sixspot} command, as follows, %\begin{quote} % \begin{verbatim} % \newcommand{\sixspot}{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp} %\end{verbatim} %\end{quote} % since this has the great advantage of making the label-name visible in the log file. % For example, the following command, which uses the rotations \textbf{x}, \textbf{x} % and \textbf{y} to initially rotate the `solved' cube before applying % the `sixspot' sequence of rotations, %\begin{quote} % \begin{verbatim} % \RubikRotation{x2,y,\sixspot} %\end{verbatim} %\end{quote} % will then be represented in the log file as %\begin{quote} % \begin{verbatim} % ...command=rotation,x2,y,[sixspot],U,Dp,R,Lp,F,Bp,U,Dp % ...arguments passed to `rotation' sub = x2 y [sixspot] U Dp R Lp F ... % ...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 %\end{verbatim} %\end{quote} % In this way, several named rotation sequences can 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. % % \subsubsection{Groups} % % The \cmd{\RubikRotation} command is a convenient tool for % illustrating how Rubik rotations and sequences of rotations are elements % of groups and subgroups. % For~example, using the \rubikrotation\ package it is easy to % show that three cycles of the `sixspot' sequence return the Rubik cube to its % original state. More formally this is equivalent to $($\cmd{\sixspot}$)3 \equiv 0$, % and can be nicely illustrated by implementing the following pseudocode: %\begin{verbatim} % \RubikCubeSolved . \RubikRotation[3]{\sixspot} = \RubikCubeSolved %\end{verbatim} % % \begin{minipage}{11cm} % \centering % \ifpdf % \includegraphics[width=10cm]{Rubikrot-doc-figC.pdf} % \else % \fi % \end{minipage} % % % \subsubsection{Random rotations} % % 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 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 %\begin{quote} %\begin{verbatim} % my $maxn=200; %\end{verbatim} %\end{quote} % % For example, the following commands will scramble a solved cube using a % sequence of 120 random rotations, and display the state in the form of % a semi-flat cube. % % \begin{minipage}{3.4cm} % \centering % \ifpdf % \includegraphics[height=4cm]{Rubikrot-doc-figB.pdf} % \else % \fi % \end{minipage} % \begin{minipage}{6cm} % \vspace{1.6cm} %\begin{verbatim} % \RubikCubeSolved% % \RubikRotation{random,120}% % \ShowCube{5.5cm}{0.5}{\DrawRubikCubeFlat} %\end{verbatim} % \end{minipage} % % Note that in this particular example (above), only % the \cmd{\Draw..} command is inside the TikZ picture environment (i.e.,~inside % the \cmd{\ShowCube} command). Note also that when Rubik % commands are outside a TikZ picture environment, they should have a % trailing \% to stop additional white space being included. % % \medskip % % The randomisation procedure is as follows: all the possible rotations are first allocated % a different cardinal number (positive integer) and collected into an array. % Then a sequence of $n$ randomised numbers is generated and mapped to % the array to generate the associated sequence of random rotations. % The sequence used is detailed in the \texttt{.log} file. % % % \subsection[SaveRubikState]{\cmd{\SaveRubikState} command} % \label{saverubikstate} % % \DescribeMacro{\SaveRubikState} % The command \cmd{\SaveRubikState}\marg{filename} saves the state (configuration) % of the Rubik cube to the file \marg{filename} in the standard \cmd{\RubikFace...} % format so that it can be read by \LaTeX. Consequently such a file can then be input % so it can be drawn or processed in the usual way. The output file is `closed' immediately % following the `write' in order to allow it to be available for input later by the same % file if required. % % For example, the following commands would save the so-called `sixspot' configuration % (generated by the rotations \textbf{U, Dp, R, Lp, F, Bp, U, Dp}) % to the file \verb!sixspot.tex!. %\begin{quote} %\begin{verbatim} % \RubikCubeSolved% % \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}% % \SaveRubikState{sixspot.tex}% %\end{verbatim} %\end{quote} % The form of the file \verb!sixspot.tex! will then be as follows---the % filename (commented out) is automatically written to the top of the % file for convenience. %\begin{quote} %\begin{verbatim} % % filename: sixspot.tex % \RubikFaceUp{O}{O}{O}{O}{W}{O}{O}{O}{O}% % \RubikFaceDown{R}{R}{R}{R}{Y}{R}{R}{R}{R}% % \RubikFaceLeft{Y}{Y}{Y}{Y}{B}{Y}{Y}{Y}{Y}% % \RubikFaceRight{W}{W}{W}{W}{G}{W}{W}{W}{W}% % \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}% % \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}% %\end{verbatim} %\end{quote} % We can therefore access and draw this configuration later, when required, % simply by inputting the file as follows: %\begin{quote} %\begin{verbatim} %\input{sixspot.tex} %\ShowCube{7cm}{0.7}{\DrawRubikCubeFlat} %\end{verbatim} %\end{quote} % % % \subsection[CheckRubikState]{\cmd{\CheckRubikState} command} % % \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 % of a 3x3x3 Rubik cube, and shows the number of facelets of each colour. % An ERROR: code is issued if the number of facelets having a given colour exceeds~6. % The results are written to the the \texttt{.log} file, and displayed under % the graphic if the \cmd{\ShowRubikErrors} command is used. % % One can check the current Rubik state (for errors) by issuing the command %\begin{quote} %\begin{verbatim} % \CheckRubikState% %\end{verbatim} %\end{quote} % Note that such a check is implemented automatically with each \cmd{\RubikRotation} command. % % % % % \subsection[ShowRubikErrors]{\cmd{\ShowRubikErrors} command} % % \DescribeMacro{\ShowRubikErrors} % Any errors which arise can be made visible using the % command \cmd{\ShowRubikErrors}. % This command places a copy of the `error' file (\texttt{rubikstateERRORS.dat}) % underneath the graphic image so you can see any errors if there are any---all this % detail can also be found in the \texttt{.log} file. % % Consequently, this command must be placed \textit{after} a TikZ picture % environment---it cannot be used inside a TikZ environment. In fact this command % is probably best placed at the end of the document (if there are several such % environments), where it will reveal all rotation errors generated while % processing the whole document. % Once the document is free of errors this command can be removed or just commented out. % Run the test file \texttt{example-rot.tex} to see an example of the use of this command. % % \section{Files generated} % % % Whenever the \cmd{\RubikRotation} or \cmd{\CheckRubikState} commands are used, % three small temporary plain-text files for holding data are generated as % follows (they are refreshed with each \LaTeX\ run, and are not actively deleted). % \begin{itemize} % \item \LaTeX\ writes Rubik state data to the file \texttt{rubikstate.dat}. % % \item The Perl script \texttt{rubikrotation.pl} reads the file % \texttt{rubikstate.dat} and then writes % the new rubik state to the file \texttt{rubikstateNEW.dat}. % % \item The Perl script \texttt{rubikrotation.pl} also writes error data % to the file \texttt{rubikstateERRORS.dat}. A copy of this file is displayed % under the graphic image when the command % \cmd{\ShowRubikErrors} is used after the TikZ picture environment. % % \end{itemize} % % % \section{General overview} % \label{generaloverview} % When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps % are implemented. % \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}). % % \item[2.] A check is made to see if a configuration-file (\texttt{rubikrotation.cfg}) % exists: if so then this file is input. % % \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists): % otherwise the file is created (this prevents an `old' file being used by \LaTeX). % % \item[4.] The plain-text file \texttt{rubikstateERRORS.dat} is created. % This file collects error messages generated by the Perl script. % % \end{itemize} % % % When a \cmd{\RubikRotation} command is processed it first writes the current % colour configuration of each face (the `rubik state') to the temporary file % \texttt{rubikstate.dat} (to be read by the Perl script \texttt{rubikrotation.pl}). % The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}' % as well as a copy of the string of Rubik rotations. % It~then calls the Perl script \texttt{rubikrotation.pl}. % % 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: %\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat % up,W,W,W,W,W,W,W,W,W % down,Y,Y,Y,Y,Y,Y,Y,Y,Y % left,B,B,B,B,B,B,B,B,B % right,G,G,G,G,G,G,G,G,G % front,O,O,O,O,O,O,O,O,O % back,R,R,R,R,R,R,R,R,R % checkstate % rotation,U,D,L,R % 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} % being written twice to the \texttt{rubikstate.dat} file, as shown above. % % Alternatively, if we used the command % \verb!\RubikRotation{random, 45}! then the last line written to the file % would be the string `\texttt{rotation,random,45}', as follows: %\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat % up,W,W,W,W,W,W,W,W,W % down,Y,Y,Y,Y,Y,Y,Y,Y,Y % left,B,B,B,B,B,B,B,B,B % right,G,G,G,G,G,G,G,G,G % front,O,O,O,O,O,O,O,O,O % back,R,R,R,R,R,R,R,R,R % checkstate % rotation,random,45 %\end{verbatim} %\end{quote} % A \cmd{\CheckRubikState} command triggers the same sequence of events except % no `rotation' line is written. % % The action of the Perl 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$, % then the Perl script performs a sequence of $n$ random rotations. % Finally, the Perl script writes the final `rubikstate' to the text file % \texttt{rubikstateNEW.dat}. All error messages are written to the % text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log file. % % Control then reverts to \LaTeX\ which then inputs the file % \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands % then this cycle repeats accordingly. Eventually a \cmd{\Draw...} command % of some form is reached and the final rubikstate is drawn in a TikZ picture % environment. % % If the TikZ picture environment is followed by a \cmd{\ShowRubikErrors} command, % then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed % immediately under the graphic. Once the graphic is error-free, then the % \cmd{\ShowRubikErrors} command can be removed or commented out. % % Note that if a \textsc{bash} file is used to coordinate the process then it is often % convenient to use the linux \texttt{grep} utility to alert the user to any run-time errors, % by using \texttt{grep} to scan the \texttt{rubikstateERRORS.dat} file at the end of % the run; for example, as follows: %\begin{quote} %\begin{verbatim} % pdflatex --shell-escape myfile.tex % echo "...checking error file" % grep ERROR ./rubikstateERRORS.dat %\end{verbatim} %\end{quote} % % % \section{References} % \label{sec:references} % %\begin{itemize} % % \item Abrahams PW, Berry K and Hargreaves KA (1990). \textit{\TeX\ for the impatient} % (Addison-Wesley Publishing Company), page~292. % {\newline}Available from: \url{http://www.ctan.org/pkg/impatient} % {\newline}[\,re:~\cmd{\rubikpercentchar} and \cmd{\@comment} in Section~\ref{sec:abrahams}\,] % % % \item Eijkhout V (1992). \textit{\TeX\ by topic: a {\TeX}nician's reference}. % (Addison-Wesley Publishing Company), pages~232 \&~238. % {\newline}Available from: \url{https://bitbucket.org/VictorEijkhout/tex-by-topic/} % [\,re:~\cmd{\string} in Section~\ref{sec:eijkhout}\,] % [\,re:~\cmd{\write} in Section~\ref{sec:seq-as-macros}\,] % % % \item Feuers\"{a}nger C (2015). Notes on programming in \TeX. % {\newline}(revision: 1.12.1-32-gc90572c; 2015/07/29) % \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf} % {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,] % % % \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package. % \newline\url{http://www.ctan.org/pkg/rubik}, % % \item Reid M. \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html} % {\newline}[\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,] % %\end{itemize} % % % % \section{Change history} % % \begin{itemize} % \item Version 3.0 (25 September 2015) % % --- The \cmd{\RubikRotation} command now actions multiple instances of its argument % as determined by an optional `repeat' \oarg{integer}. For example the command % \cmd{\RubikRotation[3]\{R,x\}} is equivalent to the command \cmd{\RubikRotation\{R,x,R,x,R,x\}} % (see Sections~\ref{sec:rubikrotationcmd} and \ref{sec:rubikrotationcode}). % % --- If a comma separated element used as an argument for the \cmd{\RubkRotation} % command is prefixed with either a * or [ or ] character then it is not actioned % as a rotation (see Section~\ref{sec:prefixedargument}). % % --- The Perl script \texttt{rubikrotation.pl} now has command-line switches, % including \texttt{-h} to show some `help' and `usage' information % (see Section~\ref{sec:placingfiles}). % % --- A `man' file for the Perl script \texttt{rubikrotation.pl} is now included in the package. % % --- The Perl script \texttt{rubikrotation.pl} now uses as input and output filenames % those specified in the command-line of the CALLing program. This now allows the % script \texttt{rubikrotation.pl} to be used as a stand-alone tool (see the % \texttt{rubikrotation} `man' file for details). % % --- The documentation for the Perl script \texttt{rubikrotation.pl} is in the % accompanying file \texttt{rubikrotationPL.pdf}. % % --- Fixed typos, index and minor errors in the documentation. % % % \item Version 2.0 (5 February, 2014) % % --- First release. % % \end{itemize} % % ^^A ================================================== % \StopEventually{\PrintIndex} % % % % \section{The code (\texttt{rubikrotation.sty})} % % {\noindent}In the following, the term `Perl script' denotes the script % \texttt{rubikrotation.pl}. Useful information regarding the % \TeX\ \cmd{\write} command is given in Eijkhout (1992), \S\,30.2.3 (page~238). % For the means of including a `\%' character in the token list of \cmd{\write} see % Abrahams \textit{et.~al} (1990). % % \subsection{Package heading} % % \begin{macrocode} %<*rubikrotation> \def\RRfileversion{3.0}% \def\RRfiledate{2015/09/25}% \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)] % \end{macrocode} % % % {\noindent}The package requires \texttt{rubikcube.sty}. However \texttt{rubikcube.sty} % is not automatically loaded (for the moment at least) since this makes it difficult % to errorcheck new versions. % \begin{macrocode} \@ifpackageloaded{rubikcube}{}{% \typeout{---rubikrotation requires the rubikcube package.}% }% % \end{macrocode} % % % % {\noindent}The \rubikrotation\ package requires access to the fancyvrb package % for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying % the error file (see Section~\ref{sec:showrubikerrors}). % \begin{macrocode} \@ifpackageloaded{fancyvrb}{}{% \typeout{---rubikrotation requires the fancyvrb package% for VerbatimInput{} command.}% \RequirePackage{fancyvrb}} % \end{macrocode} % % \medskip % % \subsection{Some useful commands} % \label{sec:usefulcommands} % % \begin{macro}{\rubikrotation} % First we create a suitable logo % \begin{macrocode} \newcommand{\rubikrotation}{\textsc{rubikrotation}} \newcommand{\Rubikrotation}{\textsc{Rubikrotation}} % \end{macrocode} % \end{macro} % % % % \begin{macro}{\@print} % We need a simple print command to facilitate writing output to a file. % \begin{macrocode} \newcommand{\@print}[1]{\immediate\write\outfile{#1}} % \end{macrocode} % \end{macro} % % % % \begin{macro}{\@comment} % \begin{macro}{\@commentone} % We also require access to the `\%' character so we can (a)~write comments to % files, including the log file, and (b)~place a trailing `\%' in a line of code % written to a file. % % To achieve this we define the `\%' character as \cmd{\rubikpercentchar} % (modified from: Abrahams PW, Berry K and Hargreaves KA (1990), p~292) % [see refs Section~\ref{sec:references}]\label{sec:abrahams}, % and also two `comment' commands which implement it. This `workaround' % is necessary because \TeX\ does not allow the use of the \cmd{\%} command % for placing a `\%' character in the token list of \cmd{\write}. % See Abrahams \textit{et.~al} (1990) for details. % \begin{macrocode} {\catcode`\%=12 \global\def\rubikpercentchar{%}}% \newcommand{\@comment}{\rubikpercentchar\rubikpercentchar\space}% \newcommand{\@commentone}{\rubikpercentchar}% % \end{macrocode} % \end{macro} % \end{macro} % % % % \begin{macro}{\rubikperlname} % This holds the name of the Perl script. A configuration-file % (\verb!rubikrotation.cfg!) can be used to change the default name of the % Perl script using a renewcommand (see Section~\ref{sec:configfile}). % \begin{macrocode} \newcommand{\rubikperlname}{rubikrotation} % \end{macrocode} % \end{macro} % % % \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 % output filename (for receiving data from the Perl script). This is because % (a)~The Perl script \texttt{rubikrotation.pl} is currently configured to read its % output filename as an argument from the command-line (so it can be flexibly % used as a stand-alone script for processing a given Rubik state through a % sequence of rotations), and (b)~\texttt{rubikrotation.sty} is currently % configured to read its input from the file \texttt{rubikstateNEW.dat}. % \begin{macrocode} \newcommand{\rubikperlcmd}{\rubikperlname\space% -i rubikstate.dat -o rubikstateNEW.dat} % \end{macrocode} % Remember to use the \cmd{\space} command following the \LaTeX\ backslash % command in order to generate the mandatory space between it and the first % command-line argument). % % A plain-text configuration-file \verb!rubikrotation.cfg! can be used to % change the default command-line code using a renewcommand % (see Section~\ref{sec:configfile}). % \end{macro} % % % \subsection{Configuration file} % % If a configuration file exists (\texttt{rubikrotation.cfg}) then input it here, % i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd} % commands and \textit{before} creating the \texttt{rubikstateERRORS.dat} file. % \begin{macrocode} \typeout{---checking for config file (rubikrotation.cfg)...} \IfFileExists{rubikrotation.cfg}{% \input{rubikrotation.cfg}% }{\typeout{---no config file available}% }% % \end{macrocode} % % % \subsection{Clean file rubikstateNEW.dat} % % {\noindent}We need to clean out any existing (old) rubikstateNEW.dat file, % since if the TeX shell command-line switch is accidentally not used then the Perl script % \texttt{rubikrotation.pl} will not be CALLed, and hence this file will not be renewed % (i.e.,~an `old' image may be used). % \begin{macrocode} \typeout{---cleaning file rubikstateNEW.dat}% \newwrite\outfile% \immediate\openout\outfile=rubikstateNEW.dat% \@print{\@comment rubikstateNEW.dat}% \immediate\closeout\outfile% % \end{macrocode} % % % \subsection{rubikstateERRORS.dat} % % {\noindent}We first open the file \texttt{rubikstateERRORS.dat} which is used % by the Perl script \texttt{rubikrotation.pl} for writing its error-messages to. % This file is displayed by the command % \cmd{\ShowRubikErrors}. % % \textsc{important note}: this file is created fresh each time LaTeX is run, % and hence the Perl script only appends data to it during the \LaTeX\ run, % so this file just grows until either it is destroyed or recreated---this is % a useful feature since the file accumulates all error messages as the % \texttt{.tex} file is processed. % We can't make the Perl script create the file since the Perl script is only % CALLed if we use a \cmd{\RubikRotation} or \cmd{\CheckRubikState} % command (which we may not\,!)---so it has to be created here. % \begin{macrocode} \typeout{---creating file rubikstateERRORS.dat}% \newwrite\outfile% \immediate\openout\outfile=rubikstateERRORS.dat% \@print{\@comment rubikstateERRORS.dat}% \@print{\@comment ---(RR.sty v\RRfileversion): comments output by Perl script}% \immediate\closeout\outfile% % \end{macrocode} % % % \subsection{Setting up file-access for new files} % % Having set up all the primary files, we now need to set up a newwrite for % all subsequent file openings (e.g.,~for \texttt{rubikstate.dat} and saving % to arbitrary filenames by the \cmd{\SaveRubikState} command). Otherwise, we % can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use % \texttt{openout7} when opening and writing to files. We will implement new % openings using the command \verb!\@openstatefile! (see below). % \begin{macrocode} \typeout{---setting up newwrite for rubikrotation.sty to use...}% \newwrite\outfile% % \end{macrocode} % % % \begin{macro}{\@openstatefile} % \begin{macro}{\@closestatefile} % We also need commands for easy file opening and closing % for new instances of the file \texttt{rubikstate.dat} etc. % Note that for this we are therefore using the same outfile number as set up % by the \verb!\newwrite...! above. % \begin{macrocode} \newcommand{\@openstatefile}{\immediate\openout\outfile=rubikstate.dat} \newcommand{\@closestatefile}{\immediate\closeout\outfile} % \end{macrocode} % \end{macro} % \end{macro} % % % \subsection{Saving the Rubik state} % % \begin{macro}{\@printrubikstate} % This internal command writes the Rubik configuration to % the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command % (see Sections~\ref{saverubikstate} and \ref{generaloverview}). % The file \texttt{rubikstate.dat} is read by the Perl script, and represents % the state on which the new \cmd{\RubikRotation} command acts. % Note that we append the key-word \texttt{checkstate} to the end of the file % in order to trigger the Perl script to implement its \texttt{checkstate} subroutine. % % The actual state is simply an ordered sequence of the faces and the colours % associated with each facelet of that face. The colour associated with a particular facelet % is held by the variable for that facelet. For example, the top-left facelet associated with % the \textsc{front} face is held in the variable \cmd{\Flt} (see Section~\ref{saverubikstate}). % Further relevant documentation is in the \textsc{rubikcube} package. % \begin{macrocode} \newcommand{\@printrubikstate}{% \@print{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}% \@print{down,\Dlt,\Dmt,\Drt,\Dlm,\Dmm,\Drm,\Dlb,\Dmb,\Drb}% \@print{left,\Llt,\Lmt,\Lrt,\Llm,\Lmm,\Lrm,\Llb,\Lmb,\Lrb}% \@print{right,\Rlt,\Rmt,\Rrt,\Rlm,\Rmm,\Rrm,\Rlb,\Rmb,\Rrb}% \@print{front,\Flt,\Fmt,\Frt,\Flm,\Fmm,\Frm,\Flb,\Fmb,\Frb}% \@print{back,\Blt,\Bmt,\Brt,\Blm,\Bmm,\Brm,\Blb,\Bmb,\Brb}% \@print{checkstate}% } % \end{macrocode} % \end{macro} % % % \subsection{SaveRubikState command} % \label{sec:eijkhout} % % \begin{macro}{\SaveRubikState} % The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state % to a named file in the format of a Rubik command (so it can then be processed % by \LaTeX). Note that in order to actually write a LaTeX % command to a file without a trailing space one must prefix the command with the % \cmd{\string} command (see Eijkhout (1992), p~238) % [see refs Section~\ref{sec:references}]\label{sec:eijkhout}. % % Note that this macro uses the internal commands \cmd{\@comment} (`\%\%'), % \cmd{\@commentone} (`\%') and \cmd{\@print}. \#1 is the output filename. % We use several \cmd{\typeout} commands to write to the log file. % An example of the line of code we are trying to output to the %\texttt{rubikstateNEW.dat} file is as follows: % {\newline}\verb!\RubikFaceUp{W}{W}{G}{W}{W}{G}{B}{B}{Y}%! % \begin{macrocode} \newcommand{\SaveRubikState}[1]{% \typeout{---NEW save command------------------}% \typeout{---command = SaveRubikState{#1}}% \typeout{---saving Rubik state data to file #1}% \immediate\openout\outfile=#1% \@print{\@comment filename: #1\@commentone}% \@print{\string\RubikFaceUp% {\Ult}{\Umt}{\Urt}{\Ulm}{\Umm}{\Urm}{\Ulb}{\Umb}{\Urb}\@commentone}% \@print{\string\RubikFaceDown% {\Dlt}{\Dmt}{\Drt}{\Dlm}{\Dmm}{\Drm}{\Dlb}{\Dmb}{\Drb}\@commentone}% \@print{\string\RubikFaceLeft% {\Llt}{\Lmt}{\Lrt}{\Llm}{\Lmm}{\Lrm}{\Llb}{\Lmb}{\Lrb}\@commentone}% \@print{\string\RubikFaceRight% {\Rlt}{\Rmt}{\Rrt}{\Rlm}{\Rmm}{\Rrm}{\Rlb}{\Rmb}{\Rrb}\@commentone}% \@print{\string\RubikFaceFront% {\Flt}{\Fmt}{\Frt}{\Flm}{\Fmm}{\Frm}{\Flb}{\Fmb}{\Frb}\@commentone}% \@print{\string\RubikFaceBack% {\Blt}{\Bmt}{\Brt}{\Blm}{\Bmm}{\Brm}{\Blb}{\Bmb}{\Brb}\@commentone}% \immediate\closeout\outfile% \typeout{-----------------------------------------}% }% % \end{macrocode} % \end{macro} % % % \subsection{RubikRotation command} % \label{sec:rubikrotationcode} % % \begin{macro}{\RubikRotation} % The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence} % command (a)~writes the current Rubik state to the file \texttt{rubikstate.dat}, % (b)~writes the rotation sequence (either once or multiple times depending % on the value of the optional integer argument), and then (c)~CALLs the % Perl script \texttt{rubikrotation.pl}. It~also writes comments to the % data file and also to the log file. % % In order to allow the user to (optionally) write the main argument multiple % times to the output data-file, we require this command to allow an optional % argument (a non-negative integer) to specify the number of such repeats. % In order to implement an optional argument facility we use two macros % (countingloop and loopcounter) detailed by Feuers\"{a}nger (2015) % [\,see refs Section~\ref{sec:references}\,]\label{sec:feuersanger}, % as follows: % \begin{macrocode} %% Two macros detailed by Feuersaenger (2015) \long\def\@countingloop#1 in #2:#3#4{% #1=#2 % \@loopcounter{#1}{#3}{#4}% } %%-------------------------- \long\def\@loopcounter#1#2#3{% #3% \ifnum#1=#2 % \let\next=\relax% \else \advance#1 by1 % \def\next{\@loopcounter{#1}{#2}{#3}}% \fi \next } % \end{macrocode} % Having defined the above two macros we can now implement an optional % argument (a repeat number) indicating the number of times we want % the command to write the main argument to the output data file. % \begin{macrocode} \newcommand{\RubikRotation}[2][1]{% \typeout{---NEW rotation command------------------}% \typeout{---command = RubikRotation{#1}}% \typeout{---writing current Rubik state to file rubikstate.dat}% \@openstatefile% open data file \@print{\@comment filename: rubikstate.dat}% \@print{\@comment written by rubikrotation.sty% =v\RRfileversion\space (\RRfiledate)}% \@printrubikstate% %% countingloop code from Feuersaenger (2015) \newcount\ourRRcounter% \@countingloop{\ourRRcounter} in 1:{#1}{% \immediate\write\outfile{rotation,#2}}% \@closestatefile% close data file \typeout{---running Perl script (rubikrotation)}% \immediate\write18{\rubikperlcmd}% \typeout{---inputting NEW datafile (written by Perl script)}% \input{rubikstateNEW.dat}% \typeout{-----------------------------------------}% } % \end{macrocode} % \end{macro} % % % \subsection{ShowRubikErrors command} % \label{sec:showrubikerrors} % % \begin{macro}{\ShowRubikErrors} % This command inputs the file \texttt{rubikstateERRORS.dat}. % \begin{macrocode} \newcommand{\ShowRubikErrors}{% \typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}% \VerbatimInput{rubikstateERRORS.dat}% } % \end{macrocode} % \end{macro} % % % \subsection{CheckRubikState command} % % \begin{macro}{\CheckRubikState} % This command triggers the Perl script to implement % some simple error checking of the Rubik configuration (state). % This command (a)~writes the current Rubik state to the file % \texttt{rubikstate.dat}, and then (b)~CALLs the Perl script. % It also writes comments to the data file and also to the log file.. % \begin{macrocode} \newcommand{\CheckRubikState}{% \typeout{---NEW check command------------------}% \typeout{---command = CheckRubikState}% \typeout{---writing current Rubik state to file rubikstate.dat}% \@openstatefile% opens data file \@print{\@comment filename: rubikstate.dat}% \@printrubikstate% \@closestatefile% close data file \typeout{---running Perl script (rubikrotation)}% \immediate\write18{\rubikperlcmd}% \typeout{---inputting NEW datafile (written by Perl script)}% \input{rubikstateNEW.dat}% \typeout{-----------------------------------------}% } % \end{macrocode} % \end{macro} % % % -------------------------- % End of this package % -------------------------- % \begin{macrocode} % % \end{macrocode} % % % % % \Finale % \endinput