diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/rubik/rubikrotation.dtx |
Initial commit
Diffstat (limited to 'macros/latex/contrib/rubik/rubikrotation.dtx')
-rw-r--r-- | macros/latex/contrib/rubik/rubikrotation.dtx | 1697 |
1 files changed, 1697 insertions, 0 deletions
diff --git a/macros/latex/contrib/rubik/rubikrotation.dtx b/macros/latex/contrib/rubik/rubikrotation.dtx new file mode 100644 index 0000000000..33103cfc54 --- /dev/null +++ b/macros/latex/contrib/rubik/rubikrotation.dtx @@ -0,0 +1,1697 @@ +% \iffalse meta-comment +% rubikrotation.dtx +% +% version 5.0 +% +% +% Authors: RWD Nickalls (dick@nickalls.org) +% and Apostolos Syropoulos (asyropoulos@yahoo.com) +% +% Copyright 25 February 2018 RWD Nickalls + A Syropoulos +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either +% version 1.3c of this license or (at your option) any +% later version. The latest version of this licence is in +% +% http://www.latex-project.org/lppl.txt +% +%<*readme> +% +% The rubikrotation package provides a collection of LaTeX commands and macros +% for the typesetting of Rubik cube configurations and rotation +% sequences using the TikZ graphic language. +% +% Please report errors or suggestions for improvement to +% +% Dick Nickalls or Apostolos Syropoulos +% +% This package requires the basic TikZ package to be loaded already +%</readme> +% +%<*driver> +\listfiles +\documentclass{ltxdoc} +\IfFileExists{rubikrotation.sty}{\usepackage{rubikrotation}}{% + \GenericWarning{rubikrotation.dtx}{Package file rubikrotation.sty not found. + Documentation will be messed up!^^J + (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J + process rubikrotation.dtx again)^^J}\stop +}% +\pagestyle{myheadings} +\markright{\texttt{rubikrotation} \ \ (Rubik bundle v5.0, 2018) \ \ \texttt{www.ctan.org/pkg/rubik}} +\usepackage{ifpdf} +\usepackage{url,path} %% for references and paths +\usepackage{graphicx} %% for the two pdf figs +\usepackage{hypdoc} %% for pdf bookmarks + hyperref documenting of packages +%%\OnlyDescription +\EnableCrossrefs +\PageIndex +\CodelineIndex +\CodelineNumbered +\RecordChanges +\setcounter{StandardModuleDepth}{1} +\begin{document} + \DocInput{rubikrotation.dtx} + \PrintChanges + \PrintIndex +\end{document} +%</driver> +% \fi +% +% +% +%%% \CheckSum{332} +% +%%% \CharacterTable +%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z +%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z +%% Digits \0\1\2\3\4\5\6\7\8\9 +%% Exclamation \! Double quote \" Hash (number) \# +%% Dollar \$ Percent \% Ampersand \& +%% Acute accent \' Left paren \( Right paren \) +%% Asterisk \* Plus \+ Comma \, +%% Minus \- Point \. Solidus \/ +%% Colon \: Semicolon \; Less than \< +%% Equals \= Greater than \> Question mark \? +%% Commercial at \@ Left bracket \[ Backslash \\ +%% Right bracket \] Circumflex \^ Underscore \_ +%% Grave accent \` Left brace \{ Vertical bar \| +%% Right brace \} Tilde \~} +% +% +% +% \title{% +% \ifpdf\pdfbookmark[1]{Title}{Title}\else\fi% +% The \rubikrotation\ package} +% +% \author{ +% RWD Nickalls (dick@nickalls.org) \\ +% A Syropoulos (asyropoulos@yahoo.com) +% } +% \date{This file describes version \RRfileversion\ (\RRfiledate)\\ +% \texttt{www.ctan.org/pkg/rubik}} +% \maketitle +% +% \begin{abstract} +% The \rubikrotation\ package is a dynamic extension for the +% \textsc{rubikcube} package (both are part of the Rubik `bundle'). +% This package provides the \cmd{\RubikRotation} command which +% processes a sequence of Rubik rotation moves on-the-fly (using the Perl script +% \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration). +% The \rubikrotation\ package also provides commands for saving the cube state +% to a file (\cmd{\SaveRubikState}), and for displaying any +% errors (\cmd{\ShowErrors}). +% \end{abstract} +% +% +% \begin{minipage}{11cm} +% \centering +% \ifpdf +% \strut\hspace{6mm}\includegraphics[width=10cm]{rubikrot-doc-figD.pdf} +% \else +% \fi +% \end{minipage} +% +% +% \vspace{-1\baselineskip} +% +% \tableofcontents +% +% \pagebreak +% +% \section{Introduction} +% +% The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} +% and \textsc{rubiktwocube} packages. +% It consists of a style option (\texttt{rubikrotation.sty}), a +% Perl script (\texttt{rubikrotation.pl}). +% +% The primary role of the \rubikrotation\ package is to implement a sequence of +% Rubik rotation moves on-the-fly using the \cmd{\RubikRotation} command. +% Consequently the \rubikrotation\ package requires access to the \TeX\ \texttt{write18} +% facility, which is enabled by using the \texttt{--shell-escape} command-line switch. +% This allows command-line control of the Perl script, which is really the `engine' of +% this package. +% +% The \rubikrotation\ package has been road-tested on a Microsoft +% platform (MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl' +% (\texttt{http://strawberryperl.com}) is a free Perl +% environment for MS Windows, designed to be as close as possible to the Perl +% environment of Unix/Linux systems.}), on a Linux platform (Debian v8.2.0, +% {\TeX}Live 2017, and Perl v5.20.2), and on a Solaris platform (OpenIndiana). +% +% The following commands are made available by \texttt{rubikrotation.sty}: +% \begin{quote} +% \begin{verbatim} +% \RubikRotation[]{} +% \SaveRubikState +% \CheckState +% \ShowErrors +% \SequenceName +% \SequenceInfo +% \SequenceShort +% \SequenceLong +%\end{verbatim} +% \end{quote} +% Note that the \textsc{rubiktwocube} package makes available the (equivalent) +% \verb!\TwoRotation[]{}! and \verb!\SaveTwoState! commands. +% +% \section{Requirements} +% +% The \rubikrotation\ package requires the TikZ and the \textsc{rubikcube} packages. +% +% +% \section{Installation} +% +% \subsection{Generating the files} +% +% Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it. +% This will generate the following files: +%\begin{quote} +% \begin{verbatim} +% rubikrotation.ins +% rubikrotation.dtx +% rubikrotation.pdf --this document +% rubikrotation.pl --Perl script +% rubikrotationPL.pdf --documentation of rubikrotation.pl +% rubikrotation.1 --manual file for rubikrotation.pl (`man' file) +% rubikrot-doc-figA.pdf +% rubikrot-doc-figB.pdf +% rubikrot-doc-figC.pdf +% rubikrot-doc-figD.pdf +%\end{verbatim} +%\end{quote} +% The main package documentation is the file \texttt{rubikrotation.pdf}. +% The documentation of the Perl program \texttt{rubikrotation.pl} is the file \texttt{rubikrotationPL.pdf} +% +% The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on +% the file \texttt{rubikrotation.ins} as follows: +%\begin{quote} +%\begin{verbatim} +% pdflatex rubikrotation.ins +%\end{verbatim} +%\end{quote} +% The documentation file (\texttt{rubikrotation.pdf}) is then generated using the following +% sequence of steps\,\footnote{Since the documentation includes a complicated indexing +% system as well as an index and hyperef links (the package \texttt{hypdoc} +% is used), then a lot of pdflatex runs are required. Prior to the first run it is +% a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}: +%\begin{quote} +% \begin{verbatim} +% pdflatex rubikrotation.dtx +% pdflatex rubikrotation.dtx +% makeindex -s gind.ist rubikrotation +% makeindex -s gglo.ist -o rubikrotation.gls rubikrotation.glo +% pdflatex rubikrotation.dtx +% pdflatex rubikrotation.dtx +%\end{verbatim} +%\end{quote} +% +% +% +% \subsection{Placing the files} +% \label{sec:placingfiles} +% +% Place the files either in a working directory, or where your system +% will find them, e.g.,~in the `\textsc{path}'. The \texttt{/texmf-local/} directory tree +% is often a good place; for example, on a Linux platform with a +% standard \TeX\ Directory Structure (TDS), then: +% +%\medskip +%{\noindent}*.sty $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} +%{\newline}*.cfg $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} +%{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubik/} +%{\newline}*.pl $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/scripts/rubik/} +% +%\medskip +%{\noindent}\textsc{perl script}:\ \ Make the perl script executable +% (\texttt{chmod +x rubikrotation.pl}), and then +% rename the file as `rubikrotation' (i.e.,~with no file extension), and then place +% the executable script in the `\textsc{path}', or possibly, directly into your +% {\TeX}Live binary directory, e.g.,~\path!/user/local/texlive/YYYY/bin/i386-linux!. +% +% Sometimes the setting up of a simple one or two-line plain-text +% configuration-file may be useful or even necessary, depending on your system +% (see Section~\ref{sec:configfile} below). Such a file (if one exists) will +% automatically be read by \texttt{rubikrotation.sty} providing the +% file is named \texttt{rubikrotation.cfg}. +% +%\medskip +%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform the manual file +% (\texttt{rubikrotation.1}) is typically located in +% either \verb!/usr/local/man/man1! or \verb!/usr/local/share/man/man1!. +% \TeX{Live} typically places such files in the directory +% \verb!/texmf-dist/doc/man/man1!. +% +%\medskip +%{\noindent}\textsc{file database}:\ \ Finally, (depending on your system) update the +% \TeX\ file database. +% For example, on a Linux platform this is achieved using the \texttt{texhash} command, +% or by using the {\TeX}Live Manager (\texttt{tlmgr}). +% +%\medskip +%{\noindent}\textsc{quick test}:\ \ To test that your system can now run the perl +% script, just type at the command-line +%\begin{quote} +% \begin{verbatim} +% rubikrotation -h +%\end{verbatim} +%\end{quote} +% which should generate something like the following: +% \begin{verbatim} +% This is rubikrotation version ... +% Usage: rubikrotation [-h] -i <input file> [-o <out file>] +% where, +% [-h|--help] gives this help listing +% [-v|--version] gives version +% [-i] creates specified input file +% [-o] creates specified output file +% For documentation see: rubikrotation.pdf, +% rubikrotationPL.pdf and rubikcube.pdf +%\end{verbatim} +% +% +% \section{Usage} +% \label{sec:usage} +% Load the packages \texttt{rubikcube.sty}, +% \texttt{rubikrotation.sty}, \texttt{rubikpatterns.sty} +% and \texttt{rubiktwocube.sty} in the \TeX\ file +% preamble \textit{after} loading the TikZ package (all the Rubik packages +% require the TikZ package). Load the \texttt{rubikcube.sty} \textit{before} the other +% Rubik bundle packages; for example, as follows: +%\begin{quote} +% \begin{verbatim} +% \usepackage{tikz} +% \usepackage{rubikcube,rubikrotation,rubikpatterns,rubiktwocube} +%\end{verbatim} +%\end{quote} +% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line option +% (see the following section). +% +% +% +% \subsection{Enabling the \TeX\ `shell' facility} +% \label{sec:shellescape} +% +% In order to access the \TeX\ \cmd{\write18} syntax (so we can access system commands, +% and hence run the Perl script), +% it is necessary to invoke the \LaTeX\ engine (e.g.,~(pdf)\LaTeX\ or Lua\LaTeX) +% using the \texttt{--shell-escape} command-line option; for example: +%\begin{quote} +% \begin{verbatim} +% pdflatex --shell-escape filename.tex +%\end{verbatim} +%\end{quote} +% In practice, it is probably most convenient to run this command via a +% bash/batch file. For example, on a Linux platform the following bash file +% will run the file, show any errors, and open the \textsc{pdf} using AcrobatReader. +%\begin{quote} +% \begin{verbatim} +% pdflatex --shell-escape filename.tex +% echo "...checking error file" +% grep ERROR ./rubikstateERRORS.dat +% acroread filename.pdf & +%\end{verbatim} +%\end{quote} +% If the \LaTeX\ engine is Lua\LaTeX, e.g., +%\begin{quote} +% \begin{verbatim} +% lualatex --shell-escape filename.tex +%\end{verbatim} +%\end{quote} +%then \texttt{rubikrotation.sty} will automatically load +% the recently developed \textsf{shellesc} package in order to facilitate system access to Perl +% (see Section~\ref{sec:CodePackageHeading}). See \textit{\LaTeX\ News}, issue~24, +% Feb~2016 for further details of the \textsf{shellesc} package. +% Consequently, if you intend to use Lua\LaTeX\ then you will need to ensure your system +% has access to the \textsf{shellesc} package (it can always be downloaded from CTAN directly). +% +% +% \subsection{Configuration-file} +% \label{sec:configfile} +% +% It is important to realise that the default action of \texttt{rubikrotation.sty} is to +% access the Perl script as an executable file. This is because the~default definitions +% in \texttt{rubikrotation.sty} are as follows: (they are detailed in +% Section~\ref{sec:usefulcommands}) +%\begin{quote} +%\begin{verbatim} +% \newcommand{\rubikperlname}{rubikrotation} +% \newcommand{\rubikperlcmd}{\rubikperlname\space% +% -i rubikstate.dat -o rubikstateNEW.dat} +%\end{verbatim} +%\end{quote} +% Note the need here (in the second macro) to use \cmd{\space} on the end of +% (\cmd{\rubikperlname}) in order to force a following +% space---i.e.,~before the first command-line argument. +% +% If the Perl script has not been made executable, or if you wish to alter how +% the \textsc{rubikrotation} package accesses the Perl script, +% then you need to create a plain-text configuration file in order to redefine one +% or both of the above commands, as described below. +% +% A plain-text configuration-file with the name \texttt{rubikrotation.cfg} +% (if one exists) will automatically be read by \texttt{rubikrotation.sty}. +% The \rubikrotation\ package's facility to use a configuration-file allows the +% user to change not only (a)~the filename of the Perl script (\texttt{rubikrotation.pl}), +% but also (b)~the command-line code used by \texttt{rubikrotation.sty} for calling the +% Perl script. This~sort of fine-tuning can be very useful, and sometimes may +% even be necessary (depending on your system) for running the Perl script. +% +% For example, on some systems it maybe preferable to use a different \textsc{path}, +% file-name and/or a different command-line code to call the script. +% Such~a configuration-file can also facilitate testing a new Perl script having +% a different name and location. +% +% \DescribeMacro{\rubikperlname} +% \DescribeMacro{\rubikperlcmd} +% The configuration-file is essentially a convenient software vehicle for feeding +% additional \LaTeX\ code to the style option \texttt{rubikrotation.sty}, and hence +% allows the contents of some commands to be easily adjusted and/or fine-tuned. +% For~the \rubikrotation\ package there are two particular macros we may wish to adjust +% (see above). +% The~first is that holding the filename of the Perl script, namely +% \cmd{\rubikperlname}. The second is that holding the command-line call, +% namely \cmd{\rubikperlcmd}. +% The following examples illustrate how the configuration-file may be used. +% +% \medskip +% {\noindent}\textsc{example~1}:\ \ Suppose we wish to test out +% a slightly modified Perl script +% with the working (executable) name \texttt{rubikrotationR77}. In this case we +% simply create, in the local working directory, a plain-text configuration-file +% (it \textit{must} be named exactly \texttt{rubikrotation.cfg}) containing just +% the following line: +%\begin{quote} +%\begin{verbatim} +%\renewcommand{\rubikperlname}{rubikrotationR77} +%\end{verbatim} +%\end{quote} +% +% \medskip +% {\noindent}\textsc{example~2}:\ \ Alternatively, suppose we wish to test out +% a new Perl script with the (non-executable) name \texttt{rubikrotationR55.pl}. +% Now, in this particular case we will need to run the script using a +% slightly different command, namely, +% {\linebreak}\texttt{perl rubikrotationR55.pl ...}, and consequently we +% need to implement \textit{both} these changes (of name and command) in +% the configuration-file, as follows: +%\begin{quote} +%\begin{verbatim} +%\renewcommand{\rubikperlname}{rubikrotationR55.pl} +%\renewcommand{\rubikperlcmd}{perl \rubikperlname\space\% +% -i rubikstate.dat -o rubikstateNEW.dat} +%\end{verbatim} +%\end{quote} +%{\noindent}Remember to make sure the PATH associated with the command is also correct. +% +% \medskip +%{\noindent\textsc{placing the configuration-file}:\ \ The simplest arrangement is +% just to include the \texttt{.cfg} file in the working directory. +% Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/} +% directory tree (say, in \path!/usr/local/texlive/texmf-local/tex/latex/rubik/!), +% but in this case one would then have to be careful to specify the +% correct PATH for everything in order to enable your system to find all the +% various components etc. +% +% Note that you can, of course, have several \texttt{.cfg} files, since the system will +% read only one such file (the first one it finds starting with the current working +% directory). Consequently, it may be useful to have one \texttt{.cfg} file in +% your \texttt{/texmf-local/} dir (for running the standard Rubik package), +% and another (different) \texttt{.cfg} file in your `test' directory. +% +% +% \section{Commands} +% +% The \textit{only} `Rubik bundle' commands which \textit{must} be used inside a TikZ picture +% environment are the \cmd{\Draw...} commands (these are all provided by +% the \textsc{rubikcube} package), although most commands can be placed +% inside a TikZ environment if you wish. +% +% Using commands which influence the Rubik colour state +% (e.g.,~\cmd{\RubikFace..}, \cmd{\RubikCubeSolvedWY} etc.) outside the \texttt{tikzpicture}, +% \texttt{minipage} or \texttt{figure} environments +% generally offers maximum flexibility, since the effects of such commands when +% used inside these environments remain `local' to the environment, and are not +% therefore accessible outside that \textit{particular} environment +% (see also Section~4.1 in the \textsc{rubikcube} documentation). +% +% Conversely, the only \rubikrotation\ command which should \textit{not} +% be used inside a TikZ environment is the \cmd{\ShowErrors} command +% (see the notes on this command below). +% +% +% +% +% \subsection[RubikRotation]{\cmd{\RubikRotation} command} +% \label{sec:rubikrotationcmd} +% +% \DescribeMacro{\RubikRotation} +% The \cmd{\RubikRotation}\oarg{integer}\marg{comma-separated sequence} +% command processes a sequence of rotation codes, and returns +% the final state. The inverse sequence can also be +% implemented (see \textbf{Inverse} below). Note that the equivalent \cmd{\TwoRotation} +% command (see the \textsc{rubiktwocube} package) behaves in the same way as the +% \cmd{\RubikRotation} command in all respects. +% +% +% The first (optional) argument \oarg{integer} of the \cmd{\RubikRotation} command is the number +% of times the whole command itself should be repeated; for example +% as follows: \verb!\RubikRotation[2]{...}!. +% +% The second (mandatory) argument consists of a comma-separated sequence +% of rotation codes, e.g.,~\texttt{U, D2}, which may be encoded as a macro. In addition, there +% may be additional comma-separated macros and optional \verb![name]!, +% `repeat blocks' and `info blocks' (see below). +% The general structure of the second argument is as follows: +% \verb!\RubikRotation{[name],...,\macro,...,(repeat)n,...,<info>}!. +% These elements are now described in detail. +% +% +% +% \textbf{Square brackets}: \ This is an optional `sequence name' facility. +% The contents of square brackets are not processed +% as rotations, and can therefore be used as a `name' of the sequence, e.g.,~\verb![CrossSeq]!, +% or as a tag, to be visible in the log file. The contents must \textit{not} include commas, but +% can have other separators, e.g.,~spaces, semicolons etc. Importantly, the contents of the +% first square bracket will be designated the sequence name and will be held as the +% macro \cmd{\SequenceName}. Square brackets can also be used in repeat blocks (see below). +% Square brackets must be separated by a comma from adjacent codes. +% +% +% \textbf{Repeat block}: \ This is an optional comma-separated sequence of rotation +% codes which is to be repeated a specified number of times. It must be delimited +% by balanced curved brackets, and an optional terminal integer $n$ (repeat number) +% can be used. For example, \verb!(F,B3)2,! where the `2' indicates that the rotation +% sequence \verb!F,B3! is to be processed twice. If the repeat number is omitted +% then $n=1$ is assumed. Repeat blocks must be separated by a comma from adjacent codes, +% and can include balanced square brackets (see below). +% +% +% \textbf{Info block}: \ +% This is an optional block of meta information, and must be +% delimited by balanced angle-brackets \verb!<..>!. An info-block typically carries +% information regarding the sequence itself; typically, something +% like \verb!<(20f*) //C2(a)>!. If an infoblock includes the keyword `inverse' then +% the program will implement the inverse sequence of rotations (see below). +% An info-block must be separated by a comma from the adjacent codes. +% The contents of all info blocks will be held collectively as the macro \cmd{\SequenceInfo}. +% +% +% \textbf{Inverse sequence}: \ +% The (mathematically) inverse sequence of the given sequence can be implemented by including +% the keyword `inverse' (or INVERSE) in an infoblock, +% as follows \verb!\RubikRotation{<inverse>, ... }!. The keyword can be either in its +% own separate infoblock, or inside a larger infoblock. The program simply checks for the +% string `inverse', which can be either lower-case or upper-case. The implemented sequence +% can be checked by looking at (or printing) the contents of the macro +% \cmd{\SequenceLong} (see section on \textit{Sequence strings} below). Note that the macro +% \cmd{\SequenceLong} is also shown (expanded) in the log file. +% +% +% \subsubsection{Examples} +% +% Some examples of the use of the \cmd{\RubikRotation} command are as follows; the commas are important and brackets must +% be balanced and not nested: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation[2]{x,R2,U} +% \RubikRotation{\sixspot} +% \RubikRotation{<inverse>,[myseqB],U,D,L,R2,(M,U)3,D2} +% \RubikRotation{[K32466],U,F,U2,F,L2,B,U2,F,Lp,Rp,F2,D,R2,U2,L2,B,Fp, +% L,F2,D,<(20f*) //Oh{I}>} +%\end{verbatim} +%\end{quote} +% +% \noindent\textbf{Inverse sequence} +% +% Inverting a sequence involves (a)~reversing the order, and (b)~inverting each element. +% Thus, the inverse of the sequence \verb!(Up,D,L2,Rp)! is \verb!(R,Lp,Lp,Dp,U)!. +% But~\verb!(Lp,Lp)! $\equiv$ \verb!L2!, and so the inverse +% of \verb!(Up,D,L2,Rp)! would generally be expressed as \verb!(R,L2,Dp,U)!. +% However, since the macro \cmd{\SequenceLong} records the individual elements as they are processed, +% when a sequence is inverted notational compressions such as \verb!Lp,Lp! $\rightarrow$ \verb!L2! +% are not made. +% For example, processing the command \verb!\RubikRotation{<inverse>,Up,D,L2,Rp}! results in the macro +% \cmd{\SequenceLong} being displayed in the subsequent \texttt{rubikstateNEW.dat} file as +%\begin{quote} +% \begin{verbatim} +% \renewcommand\SequenceLong{R,Lp,Lp,Dp,U}% +%\end{verbatim} +%\end{quote} +% A more extensive example is given at the end of Section~\ref{sec:sequencestrings}. +% +% +% \medskip\noindent\textbf{Repetitions} +% +% Repetitions can be achieved in various ways. First, all the rotations in the second argument +% can be repeated multiple times, say $n$ times, by +% using the optional \verb![n]! argument of the \cmd{\RubikRotation[]\{\}} command; +% i.e.,~the whole of the mandatory argument of the \cmd{\RubikRotation} command is then +% executed $n$ times. +% +% Second, a sub-sequence of rotations can be repeated within the main +% argument multiple times, by delimiting such groups with curved brackets +% and a trailing integer (i.e.,~in a repeat-block), as described above. +% If no integer is given, then $n=1$ is assumed, and hence curved brackets can also be used +% simply to highlight particular sequences. +% For example, the following five commands are equivalent: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation[3]{x,R2,U} +% \RubikRotation{(x,R2,U)3} +% \RubikRotation{(x,R2,U)2,x,R2,U} +% \RubikRotation{x,R2,U,x,R2,U,x,R2,U} +% \RubikRotation{(x,R2,U),(x,R2,U),(x,R2,U)} +%\end{verbatim} +%\end{quote} +% +% +% \medskip\noindent\textbf{Macros} +% +% Note also that macros representing a rotation sequence can also appear as part of the main argument. +% So, extending the previous example, if we were to define \verb!\newcommand{\ShortSeq}{x,R2,U}!, then +% the following three commands would also be equivalent to the five previous ones: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation[3]{\ShortSeq} +% \RubikRotation{(\ShortSeq)3} +% \RubikRotation{(x,R2,U),\ShortSeq,\ShortSeq} +%\end{verbatim} +%\end{quote} +% +% +% \medskip\noindent\textbf{Process overview} +% +% The \cmd{\RubikRotation} command results in \LaTeX\ first writing +% the current Rubik state to a text file (\texttt{rubikstate.dat}), +% and then calling the Perl script \texttt{rubikrotation.pl}. The Perl +% script then reads the current Rubik state from the (\texttt{rubikstate.dat}) +% file, performs all the rotations, and then writes the new Rubik state, +% and the four \cmd{\Sequence...} macros (see below), and any error messages, all to the +% file \texttt{rubikstateNEW.dat}, +% which is then input on-the-fly by the \texttt{.tex} file. This new Rubik state +% can then be used either as the input for another \cmd{\RubikRotation} command, or used +% to generate a graphic image of the cube. The \cmd{\Sequence...} macros can then +% be used for typesetting the sequence of rotations in various formats. +% +% +% \subsubsection{Sequence strings} +% \label{sec:sequencestrings} +% +% \DescribeMacro{\SequenceName} +% \DescribeMacro{\SequenceInfo} +% \DescribeMacro{\SequenceShort} +% \DescribeMacro{\SequenceLong} +% The sequence of rotation codes used as the main argument for the \cmd{\RubikRotation} +% command is also returned in the form of four macros, namely \cmd{\SequenceName} (contains the +% `name' of the sequence if a \texttt{[name]} exists), \cmd{\SequenceInfo} (contains any sequence +% meta data in `info-blocks'), \cmd{\SequenceShort} (contains the original +% sequence of rotation codes), and \cmd{\SequenceLong} (contains the expanded or `Long' form of the +% original sequence---i.e.,~in which any `short' rotation codes (e.g.,~\texttt{R2, L3}) in the original +% sequence have been expanded into their separate codes---e.g.,~\texttt{R, R, L, L, L} etc.). +% +% For example, if we wanted to see the effect of the sequence associated with the `SixTs' +% cube configuration +% \verb![SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>! +% on a solved Rubik cube (where `SixTs' is the `name' of the sequence), +% we could use the following commands: +%\begin{quote} +% \begin{verbatim} +% \RubikCubeSolved % sets up the colours for a solved cube state +% \RubikRotation{[SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>} +% \ShowCube{2.8cm}{0.7}{\DrawRubikCubeRU} +%\end{verbatim} +%\end{quote} +% Note (a)~contents of a square bracket [..] are not processed as rotations, (b)~the contents +% of the first square bracket in a sequence is taken to be the `name' of the sequence +% (see Section~\ref{sec:prefixedargument} for more details). +% In this example the four \cmd{\Sequence..} macros described above would now hold +% the following strings: +%\begin{quote} +% \cmd{\SequenceName} = SixTs +%{\newline} \cmd{\SequenceInfo} = (14q*,14f*) +%{\newline} \cmd{\SequenceShort} = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B +%{\newline} \cmd{\SequenceLong} = F,F,R,R,U,U,Fp,B,D,D,L,L,F,B +%\end{quote} +% +% As another example, we now show how to implement the inverse of the above \verb!SixTs! +% sequence, by including the key word `inverse' in an infoblock, and, more conveniently, +% using the macro \verb!\sixts! from the \textsc{rubikpatterns} package, as follows: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation{<inverse>,\sixts} +%\end{verbatim} +%\end{quote} +% In this case, the log file would then show the associated \cmd{\Sequence..} macros as follows: +%\begin{quote} +% \begin{verbatim} +%...SequenceName = SixTs +%...SequenceInfo = inverse; (14q*; 9f*) +%...SequenceShort = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B +%...SequenceLong = Bp,Fp,Lp,Lp,Dp,Dp,Bp,F,Up,Up,Rp,Rp,Fp,Fp +%\end{verbatim} +%\end{quote} +% showing that the macro \cmd{\SequenceShort} holds the \verb!\sixts! sequence, while +% the macro \cmd{\SequenceLong} holds the inverse sequence which was actually implemented. +% +% For further details regarding the use of these \cmd{\Sequence..} macros for typesetting +% the various components of a sequence, and why the \cmd{\SequenceLong} command is +% particularly useful, see Section~10 in the \textsc{rubikcube} documentation +% (the \cmd{\ShowSequence} command). +% +% +% +% \subsubsection{Sequences as macros} +% \label{sec:seq-as-macros} +% +% Macros which are arguments of the \TeX\ \cmd{\write} command are expanded +% on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see references Section~\ref{sec:references}\,]. +% Consequently we are able to use a sequence-defining macro as an argument for +% the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows +% one to store lots of different rotation sequences by name alone. Note that +% \texttt{rubikpatterns.sty} (part of the Rubik bundle) is a collection/database +% of many such well-known named sequences. +% +% For example, by installing the \textsc{rubikpatterns} package we are able to use the +% name `sixspot' for a macro denoting the rotation sequence +% which generates the well known `sixspot' configuration (see the `patterns' page on the +% Reid website)[\,see references Section~\ref{sec:references}\,]. The `sixspot' sequence is +% defined as follows: +%\begin{quote} +% \begin{verbatim} +% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>} +%\end{verbatim} +%\end{quote} +% Armed with the \cmd{\sixspot} macro we are now able to generate the graphic (sixspot cube) +% very easily using the following code---this time we demonstrate the use of the more convenient +% \cmd{\ShowCube} command (which includes the \texttt{tikzpicture} environment): +% +% \medskip +% +% \begin{minipage}{7cm} +% \begin{verbatim} +% \usepackage{rubikcube,rubikrotation} +% \usepackage{rubikpatterns} +% ... +% \RubikCubeSolved +% \RubikRotation{\sixspot} +% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU} +%\end{verbatim} +% \end{minipage} +% \begin{minipage}{3.4cm} +% \centering +% \ifpdf +% \includegraphics[height=3cm]{rubikrot-doc-figA.pdf} +% \else +% \fi +% \end{minipage} +% +% \medskip +% Providing such macros (when used as arguments) are comma separated (as the rotation codes +% must be), then the \cmd{\RubikRotation} command can accommodate both rotation codes +% and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!. +% +% +% \subsubsection{Arguments in square brackets } +% \label{sec:prefixedargument} +% +% The contents of a square bracket are not processed as rotations, but are simply +% interpreted as an inactive `string'. This feature therefore +% allows the contents to be used as a label, which can be very useful. +% Note the contents of square brackets must not include commas, but spaces and semicolons +% are allowed. +% +% For example, we can use this facility to `name' the `SixSpot' configuration mentioned above, +% as follows: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp} +%\end{verbatim} +%\end{quote} +% In practice, it is quite useful to go one step further and include +% the [\,] label-name feature in the \cmd{\sixspot} command, as follows, +%\begin{quote} +% \begin{verbatim} +% \newcommand{\sixspot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp} +%\end{verbatim} +%\end{quote} +% Note that using the \texttt{[name]} facility has the great advantage of making the +% label-name visible in the log-file. +% For example, the following command, which uses the rotations \textbf{x2}, +% and \textbf{y} to rotate the Rubik cube after applying +% the `sixspot' sequence of rotations: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation{\sixspot,x2,y} +%\end{verbatim} +%\end{quote} +% will then be represented in the log file as +%\begin{quote} +% \begin{verbatim} +% ...dataline = rotation,[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*; 8f*)>,x2,y +% ...[SixSpot] is a label OK +% ...rotation U, OK +% ...rotation Dp, OK +% ...rotation R, OK +% ...rotation Lp, OK +% ...rotation F, OK +% ...rotation Bp, OK +% ...rotation U, OK +% ...rotation Dp, OK +% ...Expanding x2 ... +% ...rotation x, OK (= x = R + Sr + Lp) +% ...rotation x, OK (= x = R + Sr + Lp) +% ...rotation y, OK (= y = U + Su + Dp) +% ...writing new Rubik state to file rubikstateNEW.dat +% ...SequenceName = SixSpot +% ...SequenceInfo = (8q*; 8f*) +% ...SequenceShort = [SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,x2,y +% ...SequenceLong = U,Dp,R,Lp,F,Bp,U,Dp,x,x,y +%\end{verbatim} +%\end{quote} +% Note that the \verb!\sixspot! macro, as held in the \textsc{rubikpatterns} package, includes a terminal +% infoblock holding the `SequenceInfo' as indicated in the above example. +% +% Also, note that the square bracket feature allows for several named rotation sequences +% to be easily distinguished in the log file from adjacent rotation sequences. +% This feature is also useful when typesetting a sequence of rotation codes, since the first +% element will then appear in the form \verb![name]!, obviating the need to typeset the +% name of the sequence separately. +% +% See also the \cmd{\ShowSequence} command (in the \textsc{rubikcube} package) +% for a convenient way of displaying a sequence of rotations in various formats. +% +% +% \subsubsection{Groups} +% +% The \cmd{\RubikRotation} command is a convenient tool for +% illustrating how Rubik rotations and sequences of rotations are elements +% of groups and subgroups. +% For~example, using the \rubikrotation\ package it is easy to +% show that three cycles of the `sixspot' sequence return the Rubik cube to its +% original state. More formally this is equivalent to +% $($\cmd{\sixspot}$)3 \equiv e$\,\footnote{$e$ is the `identity' element}, +% and can be nicely illustrated by implementing the following pseudocode: +%\begin{verbatim} +% \RubikCubeSolved . \RubikRotation[3]{\sixspot} = \RubikCubeSolved +%\end{verbatim} +% +% \begin{minipage}{11cm} +% \centering +% \ifpdf +% \includegraphics[width=10cm]{rubikrot-doc-figC.pdf} +% \else +% \fi +% \end{minipage} +% +% +% \subsubsection{Random rotations} +% +% The \cmd{\RubikRotation} command can also be used to scramble the +% cube using a random sequence of rotations. If the first argument +% is the word `random' \textsc{and} the second argument +% is an integer $n$, ($1\leq n \leq 200$), then a random sequence +% of $n$ rotations will be performed. +% If $n > 200$ then the currently set maximum value $n=200$ will be used. +% +% As a safety feature the maximum $n$ can be changed only by editing the +% set value of the Perl variable \verb!$maxn! in the Perl script +% \texttt{rubikrotation.pl}, where we currently have +% (see the `random' subroutine in the document \texttt{rubikrotationPL.pdf}) +%\begin{quote} +%\begin{verbatim} +% my $maxn=200; +%\end{verbatim} +%\end{quote} +% +% For example, the following commands scramble a solved cube using a +% sequence of 120 random rotations, and display the state in the form of +% a semi-flat (SF) cube. +% + +% \begin{minipage}{3.4cm} +% \centering +% \ifpdf +% \includegraphics[height=4cm]{rubikrot-doc-figB.pdf} +% \else +% \fi +% \end{minipage} +% \begin{minipage}{6cm} +% \vspace{1.6cm} +%\begin{verbatim} +% \RubikCubeSolved% +% \RubikRotation{random,120}% +% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeSF} +%\end{verbatim} +% \end{minipage} +% +% Note that in this particular example (above), only +% the \cmd{\Draw..} command is inside the TikZ picture environment (i.e.,~inside +% the \cmd{\ShowCube} command). Note also that when Rubik +% commands are outside a TikZ picture environment, they should have a +% trailing \% to stop additional white space being included. +% +% \medskip +% +% The randomisation procedure is as follows: all the possible rotations are first allocated +% a different cardinal number (positive integer) and collected into an array. +% Then a sequence of $n$ randomised numbers is generated and mapped to +% the array to generate the associated sequence of random rotations. +% The sequence used is detailed in the \texttt{.log} file. +% +% +% \subsection[SaveRubikState]{\cmd{\SaveRubikState} command} +% \label{saverubikstate} +% +% \DescribeMacro{\SaveRubikState} +% The command \cmd{\SaveRubikState}\marg{filename} saves the state (configuration) +% of the Rubik cube to the file \marg{filename} in the standard \cmd{\RubikFace...} +% format so that it can be read by \LaTeX. Consequently such a file can then be input +% so it can be drawn or processed in the usual way. The output file is `closed' immediately +% following the `write' in order to allow it to be available for input later by the same +% file if required. +% +% For example, the following commands would save the so-called `sixspot' configuration +% (generated by the rotations \textbf{U, Dp, R, Lp, F, Bp, U, Dp}) +% to the file \verb!sixspot.tex!. +%\begin{quote} +%\begin{verbatim} +% \RubikCubeSolved% +% \RubikRotation{U,Dp,R,Lp,F,Bp,U,Dp}% +% \SaveRubikState{sixspot.tex}% +%\end{verbatim} +%\end{quote} +% The form of the file \verb!sixspot.tex! will then be as follows---the +% filename (commented out) is automatically written to the top of the +% file for convenience. +%\begin{quote} +%\begin{verbatim} +% % filename: sixspot.tex +% \RubikFaceUp{O}{O}{O}{O}{W}{O}{O}{O}{O}% +% \RubikFaceDown{R}{R}{R}{R}{Y}{R}{R}{R}{R}% +% \RubikFaceLeft{Y}{Y}{Y}{Y}{B}{Y}{Y}{Y}{Y}% +% \RubikFaceRight{W}{W}{W}{W}{G}{W}{W}{W}{W}% +% \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}% +% \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}% +%\end{verbatim} +%\end{quote} +% We can therefore access and draw this configuration in a Semi-Flat format +% later, when required, simply by inputting the file as follows: +%\begin{quote} +%\begin{verbatim} +%\input{sixspot.tex} +%\ShowCube{7cm}{0.7}{\DrawRubikCubeSF} +%\end{verbatim} +%\end{quote} +% +% +% \subsection[CheckState]{\cmd{\CheckState} command} +% \label{sec:checkstate} +% +% \DescribeMacro{\CheckState} +% Since it is easy to inadvertently define an invalid Rubik cube +% (e.g.,~enter an invalid number of, say, yellow facelets), this command +% simply checks the current colour state of all the cubies +% of a 3x3x3 Rubik cube, and shows the number of facelets of each colour. +% An ERROR: code is issued if the number of facelets having a given colour +% exceeds~9 for a 3x3x3 cube (Rubik cube), or exceeds 4 for a 2x2x2 cube (Two cube). +% The results are written to the the \texttt{.log} file, and displayed at the point +% the \cmd{\ShowErrors} command is used (for code see Section~\ref{sec:checkstatecode}). +% +% One can check the current Rubik state (for errors) by issuing the command +%\begin{quote} +%\begin{verbatim} +% \CheckState% +%\end{verbatim} +%\end{quote} +% Note (1)~that such a check is implemented automatically with each \cmd{\RubikRotation} and +% \cmd{\TwoRotation} command, and (2)~and makes only a very superficial check---simply counting the number +% of cubies of each colour. +% +% Note that the \cmd{\CheckState} command replaces the earlier \cmd{\CheckRubikState}, but +% we retain the old command for backwards compatibility (for the moment). +% +% +% \subsection[ShowErrors]{\cmd{\ShowErrors} command} +% \label{sec:showerrors} +% +% +% \DescribeMacro{\ShowErrors} +% Any errors which arise can be made visible using the +% command \cmd{\ShowErrors}. +% This command places a copy of the `error' file (\texttt{rubikstateERRORS.dat}) +% underneath the graphic image so you can see any errors if there are any (note that +% details of all errors are are written by default to the \texttt{.log} file) +% (for code see Section~\ref{sec:showerrorscode}). +% +% Consequently, the \cmd{\ShowErrors} command must be placed \textit{after} a TikZ picture +% environment---it cannot be used inside a TikZ environment. In fact this command +% is probably best placed at the end of the document where it will reveal all +% rotation errors generated while processing the whole document. +% Once the document is free of errors this command can be removed or just commented out. +% The file \texttt{rubikexamples.pdf} shows an example of the use of this command. +% +% Note that the \cmd{\ShowErrors} command replaces the original \cmd{\ShowRubikErrors} command, +% which will be retained for backward compatibility. +% +% +% \section{Files generated} +% +% +% Whenever the \cmd{\RubikRotation} or \cmd{\CheckRubikState} commands are used, +% three small temporary plain-text files for holding data are generated as +% follows (they are refreshed with each \LaTeX\ run, and are not actively deleted). +% \begin{itemize} +% \item \LaTeX\ writes Rubik state data to the file \texttt{rubikstate.dat}. +% +% \item The Perl script \texttt{rubikrotation.pl} reads the file +% \texttt{rubikstate.dat} and then writes +% the new rubik state to the file \texttt{rubikstateNEW.dat}. +% +% \item The Perl script \texttt{rubikrotation.pl} also writes error data +% to the file \texttt{rubikstateERRORS.dat}. A copy of this file is displayed +% under the graphic image when the command +% \cmd{\ShowErrors} is used after the TikZ picture environment. +% +% \end{itemize} +% +% +% \section{General overview} +% \label{generaloverview} +% +% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps +% are implemented (see Section~\ref{sec:thecode}): +% \begin{itemize} +% +% \item[1.] A check is made to see if \texttt{fancyvrb.sty} is loaded: if not +% then this package is loaded (this package supplies the command \cmd{\VerbatimInput} which +% is required for inputting the file \texttt{rubikstateERRORS.dat} in verbatim form). +% +% \item[2.] A check is made to see if a configuration-file (\texttt{rubikrotation.cfg}) +% exists: if so then this file is input. +% +% \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists), +% otherwise the file is created (this prevents an `old' version of the file being +% used by \LaTeX). +% +% \item[4.] The plain-text file \texttt{rubikstateERRORS.dat} is created. +% This file collects error messages generated by the Perl script. +% +% \end{itemize} +% +% +% When a \cmd{\RubikRotation} command is processed +% (see Section~\ref{sec:rubikrotationcode}, line~102), it first writes the current +% colour configuration of each face (the `rubik state') to the temporary file +% \texttt{rubikstate.dat} (this will be read by the Perl script \texttt{rubikrotation.pl}). +% The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}' +% as well as a copy of the string of Rubik rotations. +% It~then calls the Perl script \texttt{rubikrotation.pl}. +% +% For example, if we use the command \cmd{\RubikCubeSolved} +% followed by the command \verb!\RubikRotation[2]{U,D,L,R}!, then the associated +% \texttt{rubikstate.dat} file will be written as follows: +%\begin{quote} +% \begin{verbatim} +% % filename: rubikstate.dat +% cubesize,three +% up,W,W,W,W,W,W,W,W,W +% down,Y,Y,Y,Y,Y,Y,Y,Y,Y +% left,B,B,B,B,B,B,B,B,B +% right,G,G,G,G,G,G,G,G,G +% front,O,O,O,O,O,O,O,O,O +% back,R,R,R,R,R,R,R,R,R +% checkstate +% rotation,U,D,L,R +% rotation,U,D,L,R +%\end{verbatim} +%\end{quote} +% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the string ``\texttt{rotation,U,D,L,R}'' +% being written twice to the \texttt{rubikstate.dat} file, as shown above. +% +% Alternatively, if we used the command +% \verb!\RubikRotation{random, 45}! then the last line written to the file +% would be the string ``\texttt{rotation,random,45}'', as follows: +%\begin{quote} +% \begin{verbatim} +% % filename: rubikstate.dat +% cubesize,three +% up,W,W,W,W,W,W,W,W,W +% down,Y,Y,Y,Y,Y,Y,Y,Y,Y +% left,B,B,B,B,B,B,B,B,B +% right,G,G,G,G,G,G,G,G,G +% front,O,O,O,O,O,O,O,O,O +% back,R,R,R,R,R,R,R,R,R +% checkstate +% rotation,random,45 +%\end{verbatim} +%\end{quote} +% A \cmd{\CheckState} command triggers the same sequence of events except +% that no ``\texttt{rotation,....}'' line is written. +% +% The action of the Perl script \texttt{rubikrotation.pl} is controlled by +% the keywords (first argument of +% each line) associated with each line of the file \texttt{rubikstate.dat}. +% When control passes from \LaTeX\ to Perl, the script \texttt{rubikrotation.pl} starts +% by loading the current rubikstate (prompted by the keywords `\texttt{up}', `\texttt{down}', +% `\texttt{left}', `\texttt{right}', `\texttt{front}', `\texttt{back}'), and performing +% a syntax check---significant syntax errors at this stage +% will cause the program to issue appropriate error messages and then terminate cleanly. +% Next, the Perl script performs some basic cube checks +% (prompted by the key word `\texttt{checkstate}'), and then the program processes +% the sequence of Rubik rotations (prompted by the keyword +% `\texttt{rotation}'). If, instead, the second argument of the `\texttt{rotation,...}' string +% is the keyword `\texttt{random}', and provided this is followed by a valid integer, say $n$, +% then the Perl script performs a sequence of $n$ random rotations. +% Finally, the Perl script writes the final rubikstate to the text file +% \texttt{rubikstateNEW.dat}. All error messages are written to the +% text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log-file. +% The Perl script now closes all open files and terminates. +% +% Control then passes back to \LaTeX\ (still in \texttt{rubikrotation.sty} processing +% the \cmd{\RubikRotation} command---see Section~\ref{sec:rubikrotationcode}, line~115); +% its next action is to input the file +% \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands +% (in the \texttt{.tex} file) then this cycle repeats accordingly. +% Eventually a \cmd{\Draw...} command is reached (in the \texttt{.tex} file) and +% the final rubikstate is drawn in a TikZ picture environment. +% +% If the TikZ picture environment is followed by a \cmd{\ShowErrors} command, +% then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed +% immediately under the graphic. Once the graphic is error-free, then the +% \cmd{\ShowErrors} command can be removed or commented out. +% +% Alternatively, when processing a long document, it can be useful to place +% a \cmd{\ShowErrors} command at the end of the document, where it will list +% all errors which occurred. Once any errors have been fixed, this command can be +% removed or commented out. +% +% Note that if a \textsc{bash} file is used to coordinate the process then it is often +% convenient to use the Linux \texttt{grep} utility to alert the user to any run-time errors, +% by using \texttt{grep} to scan the \texttt{rubikstateERRORS.dat} file at the end of +% the run; for example, as follows: +%\begin{quote} +%\begin{verbatim} +% pdflatex --shell-escape myfile.tex +% echo "...checking error file" +% grep ERROR ./rubikstateERRORS.dat +%\end{verbatim} +%\end{quote} +% +% +% +% +% \section{Change history} +% +% \begin{itemize} +% +% \item Version 5.0 (February 2018) +% +% --- minor bugfixes and better syntax checking in the Perl program. +% The cube size being processed (ie 3x3x3 or 2x2x2) is now detected by the program. +% +% --- the command \cmd{\CheckState} replaces the earlier +% \cmd{\CheckRubikState} command in order +% to avoid confusion, now that we are able to process both the 3x3x3 cube (Rubik cube) +% and also the 2x2x2 cube (Two cube) +% (see Sections~\ref{sec:checkstate} and \ref{sec:checkstatecode} (code)). +% The original command is retained (for now) for backward compatibility. +% \verb!\CheckRubikState! $\rightarrow$ \verb!\CheckState! +% +% --- the command \cmd{\ShowErrors} replaces the earlier +% \cmd{\ShowRubikErrors} command in order +% to avoid confusion now, that we are able to process both the 3x3x3 cube (Rubik cube) +% and also the 2x2x2 cube (Two cube) +% (see Sections~\ref{sec:showerrors} and \ref{sec:showerrorscode} (code)). +% The original command is retained (for now) for +% backward compatibility. \verb!\ShowRubikErrors! $\rightarrow$ \verb!\ShowErrors! +% +% +% +% +% +% \item Version 4.0 (March 2017) +% +% --- The \cmd{\RubikRotation} command has been enhanced to allow its argument to include +% so-called repeat-blocks (rotation-sequences which can be repeated multiple times), and +% info-blocks for holding sequence metadata (see Section~\ref{sec:rubikrotationcmd}). +% Syntax checking of the \cmd{\RubikRotation} argument is much improved +% (see \texttt{rubikrotationPL.pdf} for details of the Perl script). +% +% --- Four new macros which hold derived data (see Section~\ref{sec:rubikrotationcmd}). +% \begin{quote} +% \cmd{\SequenceName} +% \newline\cmd{\SequenceInfo} +% \newline\cmd{\SequenceShort} +% \newline\cmd{\SequenceLong} +% \end{quote} +% +% --- Better syntax checking of the \cmd{\RubikRotation} argument by the Perl program \texttt{rubikrotation.pl}. +% +% +% +% \item Version 3.0 (25 September 2015) +% +% --- The \cmd{\RubikRotation} command now actions multiple instances of its argument +% as determined by an optional `repeat' \oarg{integer}. For example the command +% \cmd{\RubikRotation[3]\{R,x\}} is equivalent to the command \cmd{\RubikRotation\{R,x,R,x,R,x\}} +% (see Sections~\ref{sec:rubikrotationcmd} and \ref{sec:rubikrotationcode}). +% +% --- If a comma separated element used as an argument for the \cmd{\RubikRotation} +% command is prefixed with either a * or [ or ] character then it is not actioned +% as a rotation (see Section~\ref{sec:prefixedargument}). +% +% --- The Perl script \texttt{rubikrotation.pl} now has command-line switches, +% including \texttt{-h} to show some `help' and `usage' information +% (see Section~\ref{sec:placingfiles}). +% +% --- A `man' file (manual file) for the Perl script \texttt{rubikrotation.pl} is now +% included in the package. +% +% --- The Perl script \texttt{rubikrotation.pl} now uses as input and output file-names +% those specified in the command-line of the CALLing program. This now allows the +% script \texttt{rubikrotation.pl} to be used as a stand-alone tool (see the +% \texttt{rubikrotation} `man' file for details). +% +% --- The documentation for the Perl script \texttt{rubikrotation.pl} is in the +% accompanying file \texttt{rubikrotationPL.pdf}. +% +% --- Fixed typos, index and minor errors in the documentation. +% +% +% \item Version 2.0 (5 February, 2014) +% +% --- First release. +% +% \end{itemize} +% +% +% +% +% +% \section{References} +% \label{sec:references} +% +%\begin{itemize} +% +% \item Abrahams PW, Berry K and Hargreaves KA (1990). \textit{\TeX\ for the impatient} +% (Addison-Wesley Publishing Company), page~292. +% {\newline}Available from: \url{http://www.ctan.org/pkg/impatient} +% {\newline}[\,re:~\cmd{\rubikpercentchar} and \cmd{\@comment} in Section~\ref{sec:abrahams}\,] +% +% +% \item Eijkhout V (1992). \textit{\TeX\ by topic: a {\TeX}nician's reference}. +% (Addison-Wesley Publishing Company), pages~232 \&~238. +% {\newline}Available from: \url{https://bitbucket.org/VictorEijkhout/tex-by-topic/} +% [\,re:~\cmd{\string} in Section~\ref{sec:eijkhout}\,] +% [\,re:~\cmd{\write} in Section~\ref{sec:seq-as-macros}\,] +% +% +% \item Feuers\"{a}nger C (2015). Notes on programming in \TeX. +% {\newline}(revision: 1.12.1-32-gc90572c; 2015/07/29) +% \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf} +% {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,] +% +% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm} +% +% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package, v3.0. +% \newline\url{http://www.ctan.org/pkg/rubik}, +% +% +% \item Randelshofer website (Randelshofer W). \url{http://www.randelshofer.ch/rubik/} +% \ [\,re:~sequences and supersetENG notation\,] +% +% +% \item Reid website (Reid M). \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html} +% \ [\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,] +% +% +% \item Tellechea C and Segletes SB (2016). The \textsf{listofitems} package, v1.2 +% \newline\url{http://www.ctan.org/pkg/listofitems} +% +%\end{itemize} +% +% +% +% +% +% ^^A ================================================== +% \StopEventually{\PrintIndex} +% +% +% +% \section[The code]{The code (\texttt{rubikrotation.sty})} +% \label{sec:thecode} +% +% {\noindent}In the following, the term `Perl script' denotes the script +% \texttt{rubikrotation.pl}. Useful information regarding the +% \TeX\ \cmd{\write} command is given in Eijkhout (1992), \S\,30.2.3 (page~238). +% For the means of including a `\%' character in the token list of \cmd{\write} see +% Abrahams \textit{et.~al} (1990). +% +% \subsection{Package heading} +% \label{sec:CodePackageHeading} +% +% \begin{macrocode} +%<*rubikrotation> +\def\RRfileversion{5.0}% +\def\RRfiledate{2018/02/25}% 25 February 2018 +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)] +% \end{macrocode} +% +% +% {\noindent}The package requires \texttt{rubikcube.sty}. However \texttt{rubikcube.sty} +% is not automatically loaded (for the moment at least) since this makes it difficult +% to errorcheck new versions. +% \begin{macrocode} +\@ifpackageloaded{rubikcube}{}{% + \typeout{---rubikrotation requires the rubikcube package.}% + }% +% \end{macrocode} +% +% +% +% {\noindent}The \rubikrotation\ package requires access to the \textsf{fancyvrb} package +% for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying +% the error file (see Section~\ref{sec:showerrors}). +% \begin{macrocode} +\@ifpackageloaded{fancyvrb}{}{% + \typeout{---rubikrotation requires the fancyvrb package% + for VerbatimInput{} command.}% + \RequirePackage{fancyvrb}} +% \end{macrocode} +% +% +% {\noindent}For the \cmd{\write18} syntax to work with +% Lua\TeX\ (so we can access system commands) we require +% the recent \textsf{shellesc} package, which we load using the +% \textsf{ifluatex} conditional (see Section~\ref{sec:shellescape}). +% \begin{macrocode} +\@ifpackageloaded{ifluatex}{}{% + \typeout{---rubikrotation requires the ifluatex package.}% + \RequirePackage{ifluatex}} +\ifluatex% + \@ifpackageloaded{shellesc}{}{% + \typeout{---rubikrotation requires the shellesc package + to run using Lua\LaTeX.}% + \RequirePackage{shellesc}} +\fi% +% \end{macrocode} +% +% +% \medskip +% +% \subsection{Some useful commands} +% \label{sec:usefulcommands} +% +% \begin{macro}{\rubikrotation} +% First we create a suitable logo +% \begin{macrocode} +\newcommand{\rubikrotation}{\textsc{rubikrotation}} +\newcommand{\Rubikrotation}{\textsc{Rubikrotation}} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\@print} +% We need a simple print command to facilitate writing output to a file. +% \begin{macrocode} +\newcommand{\@print}[1]{\immediate\write\outfile{#1}} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\@comment} +% \begin{macro}{\@commentone} +% We also require access to the `\%' character so we can (a)~write comments to +% files, including the log file, and (b)~place a trailing `\%' in a line of code +% written to a file. +% +% To achieve this we define the `\%' character as \cmd{\rubikpercentchar} +% (modified from: Abrahams PW, Berry K and Hargreaves KA (1990), p~292) +% [see refs Section~\ref{sec:references}]\label{sec:abrahams}, +% and also two `comment' commands which implement it. This `workaround' +% is necessary because \TeX\ does not allow the use of the \cmd{\%} command +% for placing a `\%' character in the token list of \cmd{\write}. +% See Abrahams \textit{et.~al} (1990) for details. +% \begin{macrocode} +{\catcode`\%=12 \global\def\rubikpercentchar{%}}% +\newcommand{\@comment}{\rubikpercentchar\rubikpercentchar\space}% +\newcommand{\@commentone}{\rubikpercentchar}% +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% \begin{macro}{\rubikperlname} +% This holds the name of the Perl script. A configuration-file +% (\verb!rubikrotation.cfg!) can be used to change the default name of the +% Perl script using a renewcommand (see Section~\ref{sec:configfile}). +% \begin{macrocode} +\newcommand{\rubikperlname}{rubikrotation} +% \end{macrocode} +% \end{macro} +% Note that here we are assuming that the script is an executable file. +% +% \begin{macro}{\rubikperlcmd} +% This holds the command-line code for calling the Perl script +% Note that the command-line requires a mandatory input filename preceded +% by the \texttt{-i}~switch. An optional output filename (preceded by the +% \texttt{-o}~switch) may be used, otherwise the default output filename of +% \texttt{rubik-OUT.dat} will be used. +% +% Note that it is very important that we do actually specify an +% output filename (for receiving data from the Perl script). This is because +% (a)~The Perl script \texttt{rubikrotation.pl} is currently configured to read its +% output filename as an argument from the command-line (so it can be flexibly +% used as a stand-alone script for processing a given Rubik state through a +% sequence of rotations), and (b)~\texttt{rubikrotation.sty} is currently +% configured to read its input (i.e.,~data generated by the Perl script) +% from the file \texttt{rubikstateNEW.dat}. +% \begin{macrocode} +\newcommand{\rubikperlcmd}{\rubikperlname\space% + -i rubikstate.dat -o rubikstateNEW.dat} +% \end{macrocode} +% Remember to use the \cmd{\space} macro following the \cmd{\rubikperlname} macro +% in order to generate the mandatory space before the first +% command-line argument. +% +% A plain-text configuration-file \verb!rubikrotation.cfg! can be used to +% change the default command-line code using a renewcommand +% (see Section~\ref{sec:configfile}). +% \end{macro} +% +% +% \subsection{Configuration file} +% +% If a configuration file exists (\texttt{rubikrotation.cfg}) then input it here, +% i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd} +% macros and \textit{before} creating the \texttt{rubikstateERRORS.dat} file. +% \begin{macrocode} +\typeout{---checking for config file (rubikrotation.cfg)...} +\IfFileExists{rubikrotation.cfg}{% + \input{rubikrotation.cfg}% + }{\typeout{---no config file available}% +}% +% \end{macrocode} +% +% +% \subsection{Clean file rubikstateNEW.dat} +% +% {\noindent}We need to clean out any existing (old) rubikstateNEW.dat file, +% since if the TeX shell command-line switch is accidentally not used then the Perl script +% \texttt{rubikrotation.pl} will not be CALLed, and hence this file will not be renewed +% (i.e.,~an `old' image may be used). +% \begin{macrocode} +\typeout{---cleaning file rubikstateNEW.dat}% +\newwrite\outfile% +\immediate\openout\outfile=rubikstateNEW.dat% +\@print{\@comment rubikstateNEW.dat}% +\immediate\closeout\outfile% +% \end{macrocode} +% +% +% \subsection{rubikstateERRORS.dat} +% +% {\noindent}We first open the file \texttt{rubikstateERRORS.dat} which is used +% by the Perl script \texttt{rubikrotation.pl} for writing its error-messages to. +% This file is displayed by the command +% \cmd{\ShowErrors}. +% +% \textsc{important note}: this file is created fresh each time LaTeX is run, +% and hence the Perl script only appends data to it during the \LaTeX\ run, +% so this file just grows until either it is destroyed or recreated---this is +% a useful feature since the file accumulates all error messages as the +% \texttt{.tex} file is processed. +% We can't make the Perl script create the file since the Perl script is only +% CALLed if we use a \cmd{\RubikRotation} or \cmd{\CheckRubikState} +% command (which we may not\,!)---so it has to be created here. +% \begin{macrocode} +\typeout{---creating file rubikstateERRORS.dat}% +\newwrite\outfile% +\immediate\openout\outfile=rubikstateERRORS.dat% +\@print{\@comment ShowErrors (rubikstateERRORS.dat)}% +\@print{\@comment ---------------------------------}% +\immediate\closeout\outfile% +% \end{macrocode} +% +% +% \subsection{Setting up file-access for new files} +% +% Having set up all the primary files, we now need to set up a newwrite for +% all subsequent file openings (e.g.,~for \texttt{rubikstate.dat} and saving +% to arbitrary file-names by the \cmd{\SaveRubikState} command). Otherwise, we +% can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use +% \texttt{openout7} when opening and writing to files. We will implement new +% openings using the command \verb!\@openstatefile! (see below). +% \begin{macrocode} +\typeout{---setting up newwrite for rubikrotation.sty to use...}% +\newwrite\outfile% +% \end{macrocode} +% +% +% \begin{macro}{\@openstatefile} +% \begin{macro}{\@closestatefile} +% We also need commands for easy file opening and closing +% for new instances of the file \texttt{rubikstate.dat} etc. +% Note that for this we are therefore using the same outfile number as set up +% by the \verb!\newwrite...! above. +% \begin{macrocode} +\newcommand{\@openstatefile}{\immediate\openout\outfile=rubikstate.dat} +\newcommand{\@closestatefile}{\immediate\closeout\outfile} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% \subsection{Saving the Rubik state} +% +% \begin{macro}{\@printrubikstate} +% This internal command writes the Rubik configuration to +% the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command +% (see Sections~\ref{saverubikstate} and \ref{generaloverview}). +% The file \texttt{rubikstate.dat} is read by the Perl script, and represents +% the state on which the new \cmd{\RubikRotation} command acts. +% Note that we include the line \texttt{cubesize,three} to inform the Perl script +% that the cube is a 3x3x3 cube (this is used in the `random' subroutine). +% +% The actual state (colour state) is simply an ordered sequence of the faces and the colours +% associated with each facelet of a face. The colour associated with a particular facelet +% is held by the variable for that facelet. For example, the top-left facelet associated with +% the \textsc{front} face is held in the variable \cmd{\Flt} (see Section~\ref{saverubikstate}). +% Further relevant documentation is in the \textsc{rubikcube} package. +% \begin{macrocode} +\newcommand{\@printrubikstate}{% + \@print{cubesize,three}% + \@print{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}% + \@print{down,\Dlt,\Dmt,\Drt,\Dlm,\Dmm,\Drm,\Dlb,\Dmb,\Drb}% + \@print{left,\Llt,\Lmt,\Lrt,\Llm,\Lmm,\Lrm,\Llb,\Lmb,\Lrb}% + \@print{right,\Rlt,\Rmt,\Rrt,\Rlm,\Rmm,\Rrm,\Rlb,\Rmb,\Rrb}% + \@print{front,\Flt,\Fmt,\Frt,\Flm,\Fmm,\Frm,\Flb,\Fmb,\Frb}% + \@print{back,\Blt,\Bmt,\Brt,\Blm,\Bmm,\Brm,\Blb,\Bmb,\Brb}% +} +% \end{macrocode} +% \end{macro} +% +% +% \subsection{SaveRubikState command} +% \label{sec:eijkhout} +% +% \begin{macro}{\SaveRubikState} +% The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state +% to a named file in the format of a Rubik command (so it can then be processed +% by \LaTeX). Note that in order to actually write a LaTeX +% command to a file without a trailing space one must prefix the command with the +% \cmd{\string} command (see Eijkhout (1992), p~238) +% [see refs Section~\ref{sec:references}]\label{sec:eijkhout}. +% +% Note that this macro uses the internal commands \cmd{\@comment} (`\%\%'), +% \cmd{\@commentone} (`\%') and \cmd{\@print}. \#1 is the output filename. +% We use several \cmd{\typeout} commands to write to the log file. +% An example of one of the lines of code we are trying to output to the +%\texttt{rubikstateNEW.dat} file is as follows: +% {\newline}\verb!\RubikFaceUp{W}{W}{G}{W}{W}{G}{B}{B}{Y}%! +% \begin{macrocode} +\newcommand{\SaveRubikState}[1]{% +\typeout{---NEW save command------------------}% +\typeout{---command = SaveRubikState{#1}}% +\typeout{---saving Rubik state data to file #1}% +\immediate\openout\outfile=#1% +\@print{\@comment filename: #1\@commentone}% +\@print{\string\RubikFaceUp% + {\Ult}{\Umt}{\Urt}{\Ulm}{\Umm}{\Urm}{\Ulb}{\Umb}{\Urb}\@commentone}% +\@print{\string\RubikFaceDown% + {\Dlt}{\Dmt}{\Drt}{\Dlm}{\Dmm}{\Drm}{\Dlb}{\Dmb}{\Drb}\@commentone}% +\@print{\string\RubikFaceLeft% + {\Llt}{\Lmt}{\Lrt}{\Llm}{\Lmm}{\Lrm}{\Llb}{\Lmb}{\Lrb}\@commentone}% +\@print{\string\RubikFaceRight% + {\Rlt}{\Rmt}{\Rrt}{\Rlm}{\Rmm}{\Rrm}{\Rlb}{\Rmb}{\Rrb}\@commentone}% +\@print{\string\RubikFaceFront% + {\Flt}{\Fmt}{\Frt}{\Flm}{\Fmm}{\Frm}{\Flb}{\Fmb}{\Frb}\@commentone}% +\@print{\string\RubikFaceBack% + {\Blt}{\Bmt}{\Brt}{\Blm}{\Bmm}{\Brm}{\Blb}{\Bmb}{\Brb}\@commentone}% +\immediate\closeout\outfile% +\typeout{-----------------------------------------}% +}% +% \end{macrocode} +% \end{macro} +% +% +% \subsection{RubikRotation command} +% \label{sec:rubikrotationcode} +% +% \begin{macro}{\RubikRotation} +% The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence} +% command (a)~writes the current Rubik state to the file \texttt{rubikstate.dat}, +% (b)~writes the rotation sequence (either once or multiple times depending +% on the value of the optional integer argument), and then (c)~CALLs the +% Perl script \texttt{rubikrotation.pl}. It~also writes comments to the +% data file and also to the log file. +% +% The way we allow the user to (optionally) process the main argument multiple +% times is simply by writing the associated output command multiple +% times to the output data-file. Consequently, we require the \cmd{\RubikRotation} +% command to allow a square-bracket optional +% argument (a non-negative integer) to specify the number of such repeats. +% In order to implement this optional argument facility we use two macros +% (countingloop and loopcounter) detailed by Feuers\"{a}nger (2015) +% [\,see refs Section~\ref{sec:references}\,]\label{sec:feuersanger}, +% as follows: +% \begin{macrocode} +%% Two macros detailed by Feuersaenger (2015) +\long\def\@countingloop#1 in #2:#3#4{% + #1=#2 % + \@loopcounter{#1}{#3}{#4}% +} +%%-------------------------- +\long\def\@loopcounter#1#2#3{% + #3% + \ifnum#1=#2 % + \let\next=\relax% + \else + \advance#1 by1 % + \def\next{\@loopcounter{#1}{#2}{#3}}% + \fi + \next +} +% \end{macrocode} +% Having defined the above two macros we can now implement an optional +% argument (a repeat number) indicating the number of times we want +% the command to write the main argument to the output data file. +% \begin{macrocode} +\newcommand{\RubikRotation}[2][1]{% + \typeout{---TeX process---------------------------}% + \typeout{---script = rubikrotation.sty v\RRfileversion\space (\RRfiledate)}% + \typeout{---NEW rotation command}% + \typeout{---command = RubikRotation[#1]{#2}}% + \typeout{---writing current cube state to file rubikstate.dat}% + \@openstatefile% open data file + \@print{\@comment filename: rubikstate.dat}% + \@print{\@comment written by rubikrotation.sty% + =v\RRfileversion\space (\RRfiledate)}% + \@printrubikstate% +%% countingloop code from Feuersaenger (2015) + \newcount\ourRRcounter% + \@countingloop{\ourRRcounter} in 1:{#1}{% + \immediate\write\outfile{rotation,#2}}% + \@closestatefile% close data file + \typeout{---CALLing Perl script (rubikrotation.pl)}% + \immediate\write18{\rubikperlcmd}% + \typeout{---inputting NEW datafile (data written by Perl script)}% + \input{rubikstateNEW.dat}% + \typeout{-----------------------------------------}% + } +% \end{macrocode} +% \end{macro} +% Note that the new \cmd{\ShellEscape} command implemented by the recent +% \textsf{shellesc} package is equivalent to \cmd{\immediate}\cmd{\write18} (see above), +% and so we probably ought to use \cmd{\ShellEscape} instead in future (and hence load +% \textsf{shellesc} automatically). At present, however, we leave the user to make +% sure that the \textsf{shellesc} package is actually available on their system. +% +% +% +% \subsection{ShowErrors command} +% \label{sec:showerrorscode} +% +% \begin{macro}{\ShowErrors} +% This command inputs the file \texttt{rubikstateERRORS.dat} +% (output by the Perl program). +% \begin{macrocode} +\newcommand{\ShowErrors}{% + \typeout{---ShowErrors: inputting file rubikstateERRORS.dat}% + \VerbatimInput{rubikstateERRORS.dat}% + } +% \end{macrocode} +% Since this command replaces the original command = \cmd{\ShowRubikErrors}, we will +% retain the original command for backward compatibility (for the moment at least). +% \begin{macrocode} +\newcommand{\ShowRubikErrors}{\ShowErrors} +% \end{macrocode} +% \end{macro} +% +% +% \subsection{CheckState command} +% \label{sec:checkstatecode} +% +% \begin{macro}{\CheckState} +% This command triggers the Perl script to implement +% some simple error checking of the Rubik configuration (state). +% This command (a)~writes the current Rubik state to the file +% \texttt{rubikstate.dat}, (b)~writes the keyword `checkstate' to the +% same file, and then (c)~CALLs the Perl script. +% It also writes comments to the data file and also to the log file. +% +% Note (1)~that the command \cmd{\@printrubikstate} actually writes the +% current state to the file \texttt{rubikstate.dat}, (2)~the keyword `checkstate' +% triggers the Perl program to do a simple numerical check on the number +% of facelets with each colour. +% +% Note also that the \cmd{\CheckState} command replaces the earlier +% \cmd{\CheckRubikState}, but we retain the old command for backwards +% compatibility (for the moment). +% \begin{macrocode} +\newcommand{\CheckState}{% + \typeout{---NEW check command------------------}% + \typeout{---command = CheckState}% + \typeout{---writing current cube state to file rubikstate.dat}% + \@openstatefile% opens data file + \@print{\@comment filename: rubikstate.dat}% + \@printrubikstate% + \immediate\write\outfile{checkstate}% + \@closestatefile% close data file + \typeout{---running Perl script (rubikrotation.pl)}% + \immediate\write18{\rubikperlcmd}% + \typeout{---inputting NEW datafile (data written by Perl script)}% + \input{rubikstateNEW.dat}% + \typeout{-----------------------------------------}% + } +\newcommand{\CheckRubikState}{\CheckState} +% \end{macrocode} +% \end{macro} +% +% +% -------------------------- +% End of this package +% -------------------------- +% \begin{macrocode} +%</rubikrotation> +% \end{macrocode} +% +% +% +% +% \Finale +% +\endinput + + + + + |