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