diff options
author | Karl Berry <karl@freefriends.org> | 2017-03-06 21:58:50 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-03-06 21:58:50 +0000 |
commit | aba00871ee9f5f5ac8d46fe9d0b8e29cd8ce1e8b (patch) | |
tree | 98276bb92499bc5ceb7c72cda4393f028520fc4a /Master/texmf-dist/source/latex/rubik/rubikrotation.dtx | |
parent | 346afec669dbe142884f0794af09981c591e6afd (diff) |
rubik (6mar17)
git-svn-id: svn://tug.org/texlive/trunk@43415 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/rubik/rubikrotation.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/rubik/rubikrotation.dtx | 715 |
1 files changed, 475 insertions, 240 deletions
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx index 57302ac37a7..2b554ef7128 100644 --- a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx +++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx @@ -1,12 +1,12 @@ % \iffalse meta-comment % rubikrotation.dtx % -% version 3.0 +% version 4.0 % -% Authors: RWD Nickalls (dick@nickalls.org) +% Authors: RWD Nickalls (dick@nickalls.org) % and Apostolos Syropoulos (asyropoulos@yahoo.com) -% Copyright 25 September 2015 RWD Nickalls + A Syropoulos +% Copyright 03 March 2017 RWD Nickalls + A Syropoulos % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either @@ -58,7 +58,7 @@ % % % -% \CheckSum{310} +%%% \CheckSum{322} % %%% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z @@ -78,7 +78,9 @@ % % % -% \title{The \rubikrotation\ package} +% \title{% +% \ifpdf\pdfbookmark[1]{Title}{Title}\else\fi% +% The \rubikrotation\ package} % % \author{ % RWD Nickalls (dick@nickalls.org) \\ @@ -91,49 +93,49 @@ % \begin{abstract} % The \rubikrotation\ package is a dynamic extension for the % \textsc{rubikcube} package (both are part of the Rubik `bundle'). -% The package provides the \cmd{\RubikRotation} command which +% This package provides the \cmd{\RubikRotation} command which % processes a sequence of Rubik rotation moves on-the-fly (using the Perl script % \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration). -% The \rubikrotation\ package also provides a command for implementing some basic -% checking of the Rubik cube state (\cmd{\CheckRubikState}), and one -% for displaying any errors (\cmd{\ShowRubikErrors}). -% -% The \rubikrotation\ package requires access to the \TeX\ \texttt{write18} -% facility, which is enabled by using the \texttt{--shell-escape} command-line switch. -% The~\rubikrotation\ package has been road-tested on a Microsoft -% platform (with MiKTeX and Strawberry Perl), on a Linux platform -% (Mandriva using {\TeX}Live), and on a Solaris platform (OpenIndiana). +% The \rubikrotation\ package also provides commands for saving the cube state +% to a file (\cmd{\SaveRubikState}), and for displaying any +% errors (\cmd{\ShowRubikErrors}). % \end{abstract} -% +% +% % \begin{minipage}{11cm} % \centering % \ifpdf -% \includegraphics[width=10cm]{Rubikrot-doc-figD.pdf} +% \strut\hspace{6mm}\includegraphics[width=10cm]{rubikrot-doc-figD.pdf} % \else % \fi % \end{minipage} +% % % \vspace{-1\baselineskip} % % \tableofcontents % +% \pagebreak +% % \section{Introduction} % % The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} package. % It consists of a style option (\texttt{rubikrotation.sty}), a -% Perl script (\texttt{rubikrotation.pl}) and some examples. +% Perl script (\texttt{rubikrotation.pl}). % % The primary role of the \rubikrotation\ package is to implement a sequence of -% Rubik rotation moves on-the-fly using the \cmd{\RubikRotation} command. Consequently, this -% package requires the use of the \texttt{--shell-escape} switch to allow -% command-line control of the Perl script, which is really the `engine' of this package. +% Rubik rotation moves on-the-fly using the \cmd{\RubikRotation} command. +% Consequently the \rubikrotation\ package requires access to the \TeX\ \texttt{write18} +% facility, which is enabled by using the \texttt{--shell-escape} command-line switch. +% This allows command-line control of the Perl script, which is really the `engine' of +% this package. % % The \rubikrotation\ package has been road-tested on a Microsoft -% platform (with MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl' +% platform (MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl' % (\texttt{http://strawberryperl.com}) is a free Perl % environment for MS Windows, designed to be as close as possible to the Perl -% environment of Unix/Linux systems.}), on a Linux platform (Mandriva using -% {\TeX}Live), and on a Solaris platform (OpenIndiana). +% environment of Unix/Linux systems.}), on a Linux platform (Debian v8.2.0, +% {\TeX}Live 2016, and Perl v5.20.2), and on a Solaris platform (OpenIndiana). % % The following commands are made available by \texttt{rubikrotation.sty}: % \begin{quote} @@ -142,6 +144,10 @@ % \SaveRubikState % \CheckRubikState % \ShowRubikErrors +% \SequenceName +% \SequenceInfo +% \SequenceShort +% \SequenceLong %\end{verbatim} % \end{quote} % @@ -164,21 +170,15 @@ % rubikrotation.pdf --this document % rubikrotation.pl --Perl script % rubikrotationPL.pdf --documentation of rubikrotation.pl -% rubikrotation.1 --the man file -% Rubikrot-doc-figA.pdf -% Rubikrot-doc-figB.pdf -% Rubikrot-doc-figC.pdf -% Rubikrot-doc-figD.pdf -% examples.tex -% examples.pdf -% examples.sh -% examples.bat +% rubikrotation.1 --manual file for rubikrotation.pl (`man' file) +% rubikrot-doc-figA.pdf +% rubikrot-doc-figB.pdf +% rubikrot-doc-figC.pdf +% rubikrot-doc-figD.pdf %\end{verbatim} %\end{quote} -% Note that the package includes an `examples' file (\texttt{examples.tex}) -% as well as associated \texttt{.sh} (Linux) and \texttt{.bat} (Microsoft) batch -% files which can be used to facilitate processing the file. % The main package documentation is the file \texttt{rubikrotation.pdf}. +% The documentation of the Perl program \texttt{rubikrotation.pl} is the file \texttt{rubikrotationPL.pdf} % % The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on % the file \texttt{rubikrotation.ins} as follows: @@ -189,7 +189,7 @@ %\end{quote} % The documentation file (\texttt{rubikrotation.pdf}) is then generated using the following % sequence of steps\,\footnote{Since the documentation includes a complicated indexing -% system as well a \textsc{pdf} index and hyperef links (the package \texttt{hypdoc} +% system as well as an index and hyperef links (the package \texttt{hypdoc} % is used), then a lot of pdflatex runs are required. Prior to the first run it is % a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}: %\begin{quote} @@ -232,7 +232,7 @@ % file is named \texttt{rubikrotation.cfg}. % %\medskip -%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this file +%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this manual file % (\texttt{rubikrotation.1}) would be typically located in the % directory \verb!/usr/share/man/man1!. % @@ -251,7 +251,7 @@ %\end{quote} % which should generate something like the following: % \begin{verbatim} -% This is rubikrotation version 3.0 +% This is rubikrotation version 4.0 % Usage: rubikrotation [-h] -i <input file> [-o <out file>] % where, % [-h] gives this help listing @@ -264,27 +264,31 @@ % % \section{Usage} % \label{sec:usage} -% Load the packages \texttt{rubikcube.sty} -% and \texttt{rubikrotation.sty} in the \TeX\ file preamble \textit{after} loading -% the TikZ package (both Rubik packages require the TikZ package), for example, as follows: +% Load the packages \texttt{rubikcube.sty}, +% \texttt{rubikrotation.sty} and \texttt{rubikpatterns.sty} in the \TeX\ file +% preamble \textit{after} loading the TikZ package (all the Rubik packages +% require the TikZ package); for example, as follows: %\begin{quote} % \begin{verbatim} % \usepackage{tikz} -% \usepackage{rubikcube,rubikrotation} +% \usepackage{rubikcube,rubikrotation,rubikpatterns} %\end{verbatim} %\end{quote} -% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line switch +% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line option % (see the following section). % % +% % \subsection{Enabling the \TeX\ `shell' facility} +% \label{sec:shellescape} % -% In order to enable the \TeX\ `write18' facility (so it can run the Perl script) -% it is necessary to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch -% as follows: +% In order to access the \TeX\ \cmd{\write18} syntax (so we can access system commands, +% and hence run the Perl script), +% it is necessary to invoke the \LaTeX\ engine (e.g.,~(pdf)\LaTeX\ or Lua\LaTeX) +% using the \texttt{--shell-escape} command-line option; for example: %\begin{quote} % \begin{verbatim} -% pdflatex --shell-escape filename.tex +% pdflatex --shell-escape filename.tex %\end{verbatim} %\end{quote} % In practice, it is probably most convenient to run this command via a @@ -298,34 +302,18 @@ % acroread filename.pdf & %\end{verbatim} %\end{quote} -% -% -% \subsection{Test file} -% -% An example tex file (which demonstrates the use of some of the package commands) -% is included in the package, namely: -%\begin{quote} -% \begin{verbatim} -% example-rot.tex (shows 8 worked examples) -%\end{verbatim} -%\end{quote} -% This file needs to be run using \texttt{--shell-escape} switch; for example: -%\begin{quote} -% \begin{verbatim} -% pdflatex --shell-escape example-rot.tex -%\end{verbatim} -%\end{quote} -% Batch files (\texttt{.sh} for Linux, and \texttt{.bat} for Microsoft) are also provided -% to facilitate running the `example' file. -% For example, on a Linux platform one would run a \texttt{bash} file as follows: +% If the \LaTeX\ engine is Lua\LaTeX, e.g., %\begin{quote} % \begin{verbatim} -% bash example-rot.sh +% lualatex --shell-escape filename.tex %\end{verbatim} %\end{quote} -% If processing this file gives unexpected results (e.g.,~the cubes appear not to -% have experienced any rotations) check-out the associated log file to see if -% the operating system had any difficulties finding files etc. +%then \texttt{rubikrotation.sty} will automatically load +% the recently developed \textsf{shellesc} package in order to facilitate system access to Perl +% (see Section~\ref{sec:CodePackageHeading}). See \textit{\LaTeX\ News}, issue~24, +% Feb~2016 for further details of the \textsf{shellesc} package. +% Consequently, if you intend to use Lua\LaTeX\ then you will need to ensure your system +% has access to the \textsf{shellesc} package (it can always be downloaded from CTAN directly). % % % \subsection{Configuration-file} @@ -350,9 +338,9 @@ % The configuration-file is essentially a convenient software vehicle for feeding % additional \LaTeX\ code to the style option \texttt{rubikrotation.sty}, and hence % allows the contents of some commands to be easily adjusted and/or fine-tuned. -% For~the \rubikrotation\ package there are two particular commands we may wish to adjust. -% The~first is that defining the filename of the Perl script, namely -% \cmd{\rubikperlname}. The second is that defining the command-line call, +% For~the \rubikrotation\ package there are two particular macros we may wish to adjust. +% The~first is that holding the filename of the Perl script, namely +% \cmd{\rubikperlname}. The second is that holding the command-line call, % namely \cmd{\rubikperlcmd}. % The~default definitions in \texttt{rubikrotation.sty} (which assume the Perl % script is executable), are as follows: (they are detailed in @@ -364,8 +352,8 @@ % -i rubikstate.dat -o rubikstateNEW.dat} %\end{verbatim} %\end{quote} -% Note the need here to use the \cmd{\space} command on the end of the backslash -% command (\cmd{\rubikperlname}) in order to force a following +% Note the need here (in the second macro) to use \cmd{\space} on the end of +% (\cmd{\rubikperlname}) in order to force a following % space---i.e.,~before the first command-line argument. The following examples % illustrate how the configuration-file may be used. % @@ -374,7 +362,8 @@ % a slightly modified Perl script % with the working (executable) name \texttt{rubikrotationR77}. In this case we % simply create, in the local working directory, a plain-text configuration-file -% (called \texttt{rubikrotation.cfg}) which contains just the following line: +% (it \textit{must} be named exactly \texttt{rubikrotation.cfg}) and contains just +% the following line: %\begin{quote} %\begin{verbatim} %\renewcommand{\rubikperlname}{rubikrotationR77} @@ -387,7 +376,8 @@ % Now, in this particular case we will need to run the script using a % slightly different command, namely, % {\linebreak}\texttt{perl rubikrotationR55.pl ...}, and consequently we -% need to implement both these changes in the configuration-file, as follows: +% need to implement \textit{both} these changes (of name and command) in +% the configuration-file, as follows: %\begin{quote} %\begin{verbatim} %\renewcommand{\rubikperlname}{rubikrotationR55.pl} @@ -395,8 +385,11 @@ % -i rubikstate.dat -o rubikstateNEW.dat} %\end{verbatim} %\end{quote} -%{\noindent}\textsc{placing the configuration-file}:\ \ The simplest arrangement is -% just to include the \texttt{.cfg} file in the working `test' directory. +%{\noindent}Remember to make sure the PATH associated with the command is also correct. +% +% +%{\noindent\textsc{placing the configuration-file}:\ \ The simplest arrangement is +% just to include the \texttt{.cfg} file in the working directory. % Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/} % directory tree (say, in \path!/usr/local/texlive/texmf-local/tex/latex/rubik/!), % but in this case one would then have to be careful to specify the @@ -422,7 +415,7 @@ % \texttt{minipage} or \texttt{figure} environments % generally offers maximum flexibility, since the effects of such commands when % used inside these environments remain `local' to the environment, and are not -% therefore accessable outside that \textit{particular} environment +% therefore accessible outside that \textit{particular} environment % (see also Section~4.1 in the \textsc{rubikcube} documentation). % % Conversely, the only \rubikrotation\ command which should \textit{not} @@ -430,72 +423,257 @@ % (see the notes on this command below). % % -% \subsection[RubikRotation command]{\cmd{\RubikRotation} command} -% \label{sec:rubikrotationcmd} +% +% +% \subsection[RubikRotation]{\cmd{\RubikRotation} command} +% \label{sec:rubikrotationcmd} % % \DescribeMacro{\RubikRotation} -% The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence} -% command processes a comma separated sequence of rotations, and returns -% the final state. The optional \oarg{integer} argument specifies the number -% of times the command should be repeated. -% -% For example, if we wanted to see the effect of the rotations -% \textbf{R, R, L, U, D} on a solved Rubik cube, we could use the -% following commands. +% The \cmd{\RubikRotation}\oarg{integer}\marg{comma-separated sequence} +% command processes a sequence of rotation codes, and returns +% the final state. The inverse sequence can also be +% implemented (see \textbf{Inverse} below). +% +% +% The first (optional) argument \oarg{integer} of the \cmd{\RubikRotation} command is the number +% of times the whole command itself should be repeated; for example +% as follows: \verb!\RubikRotation[2]{...}!. +% +% The second (mandatory) argument consists of a comma-separated sequence +% of rotation codes, e.g.,~\texttt{U, D2}, which may be encoded as a macro. In addition, there +% may be additional comma-separated macros and optional \verb![name]!, +% `repeat blocks' and `info blocks' (see below). +% The general structure of the second argument is as follows: +% \verb!\RubikRotation{[name],...,\macro,...,(repeat)n,...,<info>}!. +% These elements are now described in detail. +% +% +% +% \textbf{Square brackets}: \ This is an optional `sequence name' facility. +% The contents of square brackets are not processed +% as rotations, and can therefore be used as a `name' of the sequence, e.g.,~\verb![CrossSeq]!, +% or as a tag, to be visible in the log file. The contents must \textit{not} include commas, but +% can have other separators, e.g.,~spaces, semicolons etc. Importantly, the contents of the +% first square bracket will be designated the sequence name and will be held as the +% macro \cmd{\SequenceName}. Square brackets can also be used in repeat blocks (see below). +% Square brackets must be separated by a comma from adjacent codes. +% +% +% \textbf{Repeat block}: \ This is an optional comma-separated sequence of rotation +% codes which is to be repeated a specified number of times. It must be delimited +% by balanced curved brackets, and an optional terminal integer $n$ (repeat number) +% can be used. For example, \verb!(F,B3)2,! where the `2' indicates that the rotation +% sequence \verb!F,B3! is to be processed twice. If the repeat number is omitted +% then $n=1$ is assumed. Repeat blocks must be separated by a comma from adjacent codes, +% and can include balanced square brackets (see below). +% +% +% \textbf{Info block}: \ +% This is an optional block of meta information, and must be +% delimited by balanced angle-brackets \verb!<..>!. An info-block typically carries +% information regarding the sequence itself; typically, something +% like \verb!<(20f*) //C2(a)>!. If an infoblock includes the keyword `inverse' then +% the program will implement the inverse sequence of rotations (see below). +% An info-block must be separated by a comma from the adjacent codes. +% The contents of all info blocks will be held collectively as the macro \cmd{\SequenceInfo}. +% +% +% \textbf{Inverse sequence}: \ +% The (mathematically) inverse sequence of the given sequence can be implemented by including +% the keyword `inverse' (or INVERSE) in an infoblock, +% as follows \verb!\RubikRotation{<inverse>, ... }!. The keyword can be either in its +% own separate infoblock, or inside a larger infoblock. The program simply checks for the +% string `inverse', which can be either lower-case or upper-case. The implemented sequence +% can be checked by looking at (or printing) the contents of the macro +% \cmd{\SequenceLong} (see section on \textit{Sequence strings} below). Note that the macro +% \cmd{\SequenceLong} is also shown (expanded) in the log file. +% +% +% \subsubsection{Examples} +% +% Some examples of the use of the \cmd{\RubikRotation} command are as follows; the commas are important and brackets must +% be balanced and not nested: %\begin{quote} % \begin{verbatim} -% \RubikCubeSolved % sets up the colours for a solved cube state -% \RubikRotation{R2,L,U,D} -% \begin{tikzpicture}[scale=0.7] -% \DrawRubikCubeRU -% \end{tikzpicture}% +% \RubikRotation[2]{x,R2,U} +% \RubikRotation{\sixspot} +% \RubikRotation{<inverse>,[myseqB],U,D,L,R2,(M,U)3,D2} +% \RubikRotation{[K32466],U,F,U2,F,L2,B,U2,F,Lp,Rp,F2,D,R2,U2,L2,B,Fp, +% L,F2,D,<(20f*) //Oh{I}>} +%\end{verbatim} +%\end{quote} +% +% \noindent\textbf{Inverse sequence} +% +% Inverting a sequence involves (a)~reversing the order, and (b)~inverting each element. +% Thus, the inverse of the sequence \verb!(Up,D,L2,Rp)! is \verb!(R,Lp,Lp,Dp,U)!. +% But~\verb!(Lp,Lp)! $\equiv$ \verb!L2!, and so the inverse +% of \verb!(Up,D,L2,Rp)! would generally be expressed as \verb!(R,L2,Dp,U)!. +% However, since the macro \cmd{\SequenceLong} records the individual elements as they are processed, +% when a sequence is inverted notational compressions such as \verb!Lp,Lp! $\rightarrow$ \verb!L2! +% are not made. +% For example, processing the command \verb!\RubikRotation{<inverse>,Up,D,L2,Rp}! results in the macro +% \cmd{\SequenceLong} being displayed in the subsequent \texttt{rubikstateNEW.dat} file as +%\begin{quote} +% \begin{verbatim} +% \renewcommand\SequenceLong{R,Lp,Lp,Dp,U}% +%\end{verbatim} +%\end{quote} +% A more extensive example is given at the end of Section~\ref{sec:sequencestrings}. +% +% +% \medskip\noindent\textbf{Repetitions} +% +% Repetitions can be achieved in various ways. First, all the rotations in the second argument +% can be repeated multiple times, say $n$ times, by +% using the optional \verb![n]! argument of the \cmd{\RubikRotation[]\{\}} command; +% i.e.,~the whole of the mandatory argument of the \cmd{\RubikRotation} command is then +% executed $n$ times. +% +% Second, a sub-sequence of rotations can be repeated within the main +% argument multiple times, by delimiting such groups with curved brackets +% and a trailing integer (i.e.,~in a repeat-block), as described above. +% If no integer is given, then $n=1$ is assumed, and hence curved brackets can also be used +% simply to highlight particular sequences. +% For example, the following five commands are equivalent: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation[3]{x,R2,U} +% \RubikRotation{(x,R2,U)3} +% \RubikRotation{(x,R2,U)2,x,R2,U} +% \RubikRotation{x,R2,U,x,R2,U,x,R2,U} +% \RubikRotation{(x,R2,U),(x,R2,U),(x,R2,U)} +%\end{verbatim} +%\end{quote} +% +% +% \medskip\noindent\textbf{Macros} +% +% Note also that macros representing a rotation sequence can also appear as part of the main argument. +% So, extending the previous example, if we were to define \verb!\newcommand{\ShortSeq}{x,R2,U}!, then +% the following three commands would also be equivalent to the five previous ones: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation[3]{\ShortSeq} +% \RubikRotation{(\ShortSeq)3} +% \RubikRotation{(x,R2,U),\ShortSeq,\ShortSeq} %\end{verbatim} %\end{quote} -% The \cmd{\RubikRotation} command results in \LaTeX\ first writing +% +% +% \medskip\noindent\textbf{Process overview} +% +% The \cmd{\RubikRotation} command results in \LaTeX\ first writing % the current Rubik state to a text file (\texttt{rubikstate.dat}), % and then calling the Perl script \texttt{rubikrotation.pl}. The Perl % script then reads the current Rubik state from the (\texttt{rubikstate.dat}) -% file, performs all the rotations, and then writes the new Rubik state -% (and any error messages) to the file \texttt{rubikstateNEW.dat}, -% which is then input on-the-fly by the \LaTeX\ file. This new Rubik state -% can then either used as the input for another \cmd{\RubikRotation}, or used -% to generate a graphic image of the cube. -% -% A given rotation sequence can be repeated multiple times, say $n$ times, by -% using the optional \verb![n]!. For example, the following two commands are equivalent: +% file, performs all the rotations, and then writes the new Rubik state, +% and the four \cmd{\Sequence...} macros (see below), and any error messages, all to the +% file \texttt{rubikstateNEW.dat}, +% which is then input on-the-fly by the \texttt{.tex} file. This new Rubik state +% can then be used either as the input for another \cmd{\RubikRotation} command, or used +% to generate a graphic image of the cube. The \cmd{\Sequence...} macros can then +% be used for typesetting the sequence of rotations in various formats. +% +% +% \subsubsection{Sequence strings} +% \label{sec:sequencestrings} +% +% \DescribeMacro{\SequenceName} +% \DescribeMacro{\SequenceInfo} +% \DescribeMacro{\SequenceShort} +% \DescribeMacro{\SequenceLong} +% The sequence of rotation codes used as the main argument for the \cmd{\RubikRotation} +% command is also returned in the form of four macros, namely \cmd{\SequenceName} (contains the +% `name' of the sequence if a \texttt{[name]} exists), \cmd{\SequenceInfo} (contains any sequence +% meta data in `info-blocks'), \cmd{\SequenceShort} (contains the original +% sequence of rotation codes), and \cmd{\SequenceLong} (contains the expanded or `Long' form of the +% original sequence---i.e.,~in which any `short' rotation codes (e.g.,~\texttt{R2, L3}) in the original +% sequence have been expanded into their separate codes---e.g.,~\texttt{R, R, L, L, L} etc.). +% +% For example, if we wanted to see the effect of the sequence associated with the `SixTs' +% cube configuration +% \verb![SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>! +% on a solved Rubik cube (where `SixTs' is the `name' of the sequence), +% we could use the following commands: %\begin{quote} % \begin{verbatim} -% \RubikRotation[3]{x,R,U} -% \RubikRotation{x,R,U,x,R,U,x,R,U} +% \RubikCubeSolved % sets up the colours for a solved cube state +% \RubikRotation{[SixTs],F2,R2,U2,Fp,B,D2,L2,F,B,<(14q*,14f*)>} +% \ShowCube{2.8cm}{0.7}{\DrawRubikCubeRU} %\end{verbatim} %\end{quote} +% Note (a)~contents of a square bracket [..] are not processed as rotations, (b)~the contents +% of the first square bracket in a sequence is taken to be the `name' of the sequence +% (see Section~\ref{sec:prefixedargument} for more details). +% In this example the four \cmd{\Sequence..} macros described above would now hold +% the following strings: +%\begin{quote} +% \cmd{\SequenceName} = SixTs +%{\newline} \cmd{\SequenceInfo} = (14q*,14f*) +%{\newline} \cmd{\SequenceShort} = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B +%{\newline} \cmd{\SequenceLong} = F,F,R,R,U,U,Fp,B,D,D,L,L,F,B +%\end{quote} +% +% As another example, we now show how to implement the inverse of the above \verb!SixTs! +% sequence, by including the key word `inverse' in an infoblock, and, more conveniently, +% using the macro \verb!\sixts! from the \textsc{rubikpatterns} package, as follows: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation{<inverse>,\sixts} +%\end{verbatim} +%\end{quote} +% In this case, the log file would then show the associated \cmd{\Sequence..} macros as follows: +%\begin{quote} +% \begin{verbatim} +%...SequenceName = SixTs +%...SequenceInfo = inverse; (14q*; 9f*) +%...SequenceShort = [SixTs],F2,R2,U2,Fp,B,D2,L2,F,B +%...SequenceLong = Bp,Fp,Lp,Lp,Dp,Dp,Bp,F,Up,Up,Rp,Rp,Fp,Fp +%\end{verbatim} +%\end{quote} +% showing that the macro \cmd{\SequenceShort} holds the \verb!\sixts! sequence, while +% the macro \cmd{\SequenceLong} holds the inverse sequence which was actually implemented. +% +% For further details regarding the use of these \cmd{\Sequence..} macros for typesetting +% the various components of a sequence, and why the \cmd{\SequenceLong} command is +% particularly useful, see Section~10 in the \textsc{rubikcube} documentation +% (the \cmd{\ShowSequence} command). +% +% % - % \subsubsection{Sequences as macros} -% \label{sec:seq-as-macros} +% \label{sec:seq-as-macros} % % Macros which are arguments of the \TeX\ \cmd{\write} command are expanded % on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see refs Section~\ref{sec:references}\,]. % Consequently we are able to use a sequence-defining macro as an argument for % the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows -% one to store lots of different rotation sequences by name alone. +% one to store lots of different rotation sequences by name alone. Note that +% \texttt{rubikpatterns.sty} (part of the Rubik bundle) is a collection/database +% of many such well-known named sequences. % -% For example, we can use the name `sixspot' for a macro denoting the rotation sequence +% For example, by installing the \textsc{rubikpatterns} package we are able to use the +% name `sixspot' for a macro denoting the rotation sequence % which generates the well known `sixspot' configuration (see the `patterns' page on the -% Reid website)[\,see refs Section~\ref{sec:references}\,], as follows: +% Reid website)[\,see refs Section~\ref{sec:references}\,]. The `sixspot' sequence is +% defined as follows: %\begin{quote} % \begin{verbatim} -% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp} +% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp,<(8q*, 8f*)>} %\end{verbatim} %\end{quote} -% With this new \cmd{\sixspot} command we are now able to generate the graphic (sixspot cube) +% Armed with the \cmd{\sixspot} macro we are now able to generate the graphic (sixspot cube) % very easily using the following code---this time we demonstrate the use of the more convenient % \cmd{\ShowCube} command (which includes the \texttt{tikzpicture} environment): % % \medskip % -% \begin{minipage}{6cm} +% \begin{minipage}{7cm} % \begin{verbatim} +% \usepackage{rubikcube,rubikrotation} +% \usepackage{rubikpatterns} +% ... % \RubikCubeSolved % \RubikRotation{\sixspot} % \ShowCube{3cm}{0.7}{\DrawRubikCubeRU} @@ -504,7 +682,7 @@ % \begin{minipage}{3.4cm} % \centering % \ifpdf -% \includegraphics[height=3cm]{Rubikrot-doc-figA.pdf} +% \includegraphics[height=3cm]{rubikrot-doc-figA.pdf} % \else % \fi % \end{minipage} @@ -515,87 +693,75 @@ % and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!. % % -% \subsubsection{Arguments prefixed with *, [, ]} +% \subsubsection{Arguments in square brackets } % \label{sec:prefixedargument} % -% If any of the comma separated arguments is prefixed with either *, [ or ] they are -% interpreted as an inactive `string', and not as a rotation. This feature therefore -% allows a string argument to be used as a label, which can be very useful. +% The contents of a square bracket are not processed as rotations, but are simply +% interpreted as an inactive `string'. This feature therefore +% allows the contents to be used as a label, which can be very useful. +% Note the contents of square brackets must not include commas, but spaces and semicolons +% are allowed. % -% For example, we can use this facility to label the `sixspot' configuration mentioned above, +% For example, we can use this facility to `name' the `SixSpot' configuration mentioned above, % as follows: %\begin{quote} % \begin{verbatim} -% \RubikRotation{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp} +% \RubikRotation{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp} %\end{verbatim} %\end{quote} % In practice, it is quite useful to go one step further and include -% the [\,] label feature in the \cmd{\sixspot} command, as follows, +% the [\,] label-name feature in the \cmd{\sixspot} command, as follows, %\begin{quote} % \begin{verbatim} -% \newcommand{\sixspot}{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp} +% \newcommand{\sixspot}{[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp} %\end{verbatim} %\end{quote} -% since this has the great advantage of making the label-name visible in the log file. -% For example, the following command, which uses the rotations \textbf{x}, \textbf{x} -% and \textbf{y} to initially rotate the `solved' cube before applying -% the `sixspot' sequence of rotations, +% Note that using the \texttt{[name]} facility has the great advantage of making the +% label-name visible in the log-file. +% For example, the following command, which uses the rotations \textbf{x2}, +% and \textbf{y} to rotate the Rubik cube after applying +% the `sixspot' sequence of rotations: %\begin{quote} % \begin{verbatim} -% \RubikRotation{x2,y,\sixspot} +% \RubikRotation{\sixspot,x2,y} %\end{verbatim} %\end{quote} % will then be represented in the log file as %\begin{quote} % \begin{verbatim} -% ...command=rotation,x2,y,[sixspot],U,Dp,R,Lp,F,Bp,U,Dp -% ...arguments passed to `rotation' sub = x2 y [sixspot] U Dp R Lp F ... -% ...rotation x OK (= rrR + rrSr + rrLp) -% ...rotation x OK (= rrR + rrSr + rrLp) -% ...rotation y OK (= rrU + rrSu + rrDp) -% ...[sixspot] is a label OK -% ...rotation U OK -% ...rotation Dp OK -% ...rotation R OK -% ...rotation Lp OK -% ...rotation F OK -% ...rotation Bp OK -% ...rotation U OK -% ...rotation Dp OK +% ...dataline = rotation,[SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,<(8q*; 8f*)>,x2,y +% ...[SixSpot] is a label OK +% ...rotation U, OK +% ...rotation Dp, OK +% ...rotation R, OK +% ...rotation Lp, OK +% ...rotation F, OK +% ...rotation Bp, OK +% ...rotation U, OK +% ...rotation Dp, OK +% ...Expanding x2 ... +% ...rotation x, OK (= x = R + Sr + Lp) +% ...rotation x, OK (= x = R + Sr + Lp) +% ...rotation y, OK (= y = U + Su + Dp) +% ...writing new Rubik state to file rubikstateNEW.dat +% ...SequenceName = SixSpot +% ...SequenceInfo = (8q*; 8f*) +% ...SequenceShort = [SixSpot],U,Dp,R,Lp,F,Bp,U,Dp,x2,y +% ...SequenceLong = U,Dp,R,Lp,F,Bp,U,Dp,x,x,y %\end{verbatim} %\end{quote} -% In this way, several named rotation sequences can be easily distinguished -% in the log file from adjacent rotation sequences. +% Note that the \verb!\sixspot! macro, as held in the \textsc{rubikpatterns} package, includes a terminal +% infoblock holding the `SequenceInfo' as indicated in the above example. +% +% Also, note that the square bracket feature allows for several named rotation sequences +% to be easily distinguished in the log file from adjacent rotation sequences. % This feature is also useful when typesetting a sequence of rotation codes, since the first % element will then appear in the form \verb![name]!, obviating the need to typeset the % name of the sequence separately. % -% To this end, the -% \verb!ForEachX! macro---from the \verb!forarray! package---can be very useful. -% For example, this macro is central to the following example macro for typesetting -% a rotation sequence using the Rubik \cmd{\rr} command: -%\begin{quote} -%\begin{verbatim} -%\def\x{\thislevelitem} -%\def\xcount{\thislevelcount} -% -%\newcommand{\showseq}[1]{% -% \ForEachX{,}{% -% \ifthenelse{\xcount=1}{\texttt{\x}}{,\ \rr{\x}}% -% }{#1}. -%} -%\end{verbatim} -%\end{quote} -% Now, for a sequence defined as |\newcommand{\myseq}{[myseq],U,D,Lwp,R}|, then -% the command |\showseq{\myseq}| will result in the following output: -%\begin{quote} -% \texttt{[myseq]},\ \textbf{U},\ \textbf{D},\ \textbf{Lwp},\ \textbf{R}. -%\end{quote} -% Note that we are able to typeset the name \texttt{[myseq]} differently from the -% remaining sequence since the counter \verb!\xcount! allows us to locate the first item. -% However, this macro as it stands needs further development in order to handle -% sequence elements with a terminal digit (e.g.,~\texttt{R2})---the macro will need -% to first expand this to \texttt{R, R} if the Rubik commands are to be used. +% See also the \cmd{\ShowSequence} command (in the \textsc{rubikcube} package) +% for a convenient way of displaying a sequence of rotations in various formats. +% % % \subsubsection{Groups} % @@ -604,7 +770,8 @@ % of groups and subgroups. % For~example, using the \rubikrotation\ package it is easy to % show that three cycles of the `sixspot' sequence return the Rubik cube to its -% original state. More formally this is equivalent to $($\cmd{\sixspot}$)3 \equiv 0$, +% original state. More formally this is equivalent to +% $($\cmd{\sixspot}$)3 \equiv e$\,\footnote{$e$ is the `identity' element}, % and can be nicely illustrated by implementing the following pseudocode: %\begin{verbatim} % \RubikCubeSolved . \RubikRotation[3]{\sixspot} = \RubikCubeSolved @@ -613,7 +780,7 @@ % \begin{minipage}{11cm} % \centering % \ifpdf -% \includegraphics[width=10cm]{Rubikrot-doc-figC.pdf} +% \includegraphics[width=10cm]{rubikrot-doc-figC.pdf} % \else % \fi % \end{minipage} @@ -623,30 +790,31 @@ % % The \cmd{\RubikRotation} command can also be used to scramble the % cube using a random sequence of rotations. If the first argument -% is the lowercase word `random' \textsc{and} the second argument +% is the lower-case word `random' \textsc{and} the second argument % is an integer $n$, ($1\leq n \leq 200$), then a random sequence % of $n$ rotations will be performed; otherwise a default value % of 50 is used (for example, if the second argument is not an integer). % If $n > 200$ then the currently set maximum value $n=200$ will be used. % -% As a safety feature the maximum $n$ can be changed only by editing the -% set value of the Perl variable \verb!$maxn! in the Perl script -% \texttt{rubikrotation.pl}, where (see line~583) we currently have +% As a safety feature the maximum $n$ can be changed only by editing the +% set value of the Perl variable \verb!$maxn! in the Perl script +% \texttt{rubikrotation.pl}, where we currently have +% (see the `random' subroutine in the document \texttt{rubikrotationPL.pdf}) %\begin{quote} %\begin{verbatim} % my $maxn=200; %\end{verbatim} %\end{quote} % -% For example, the following commands will scramble a solved cube using a +% For example, the following commands scramble a solved cube using a % sequence of 120 random rotations, and display the state in the form of -% a semi-flat cube. +% a semi-flat (SF) cube. % % \begin{minipage}{3.4cm} % \centering % \ifpdf -% \includegraphics[height=4cm]{Rubikrot-doc-figB.pdf} +% \includegraphics[height=4cm]{rubikrot-doc-figB.pdf} % \else % \fi % \end{minipage} @@ -655,7 +823,7 @@ %\begin{verbatim} % \RubikCubeSolved% % \RubikRotation{random,120}% -% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeFlat} +% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeSF} %\end{verbatim} % \end{minipage} % @@ -691,7 +859,7 @@ %\begin{quote} %\begin{verbatim} % \RubikCubeSolved% -% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}% +% \RubikRotation{U,Dp,R,Lp,F,Bp,U,Dp}% % \SaveRubikState{sixspot.tex}% %\end{verbatim} %\end{quote} @@ -709,12 +877,12 @@ % \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}% %\end{verbatim} %\end{quote} -% We can therefore access and draw this configuration later, when required, -% simply by inputting the file as follows: +% We can therefore access and draw this configuration in a Semi-Flat format +% later, when required, simply by inputting the file as follows: %\begin{quote} %\begin{verbatim} %\input{sixspot.tex} -%\ShowCube{7cm}{0.7}{\DrawRubikCubeFlat} +%\ShowCube{7cm}{0.7}{\DrawRubikCubeSF} %\end{verbatim} %\end{quote} % @@ -724,7 +892,7 @@ % \DescribeMacro{\CheckRubikState} % Since it is easy to inadvertently define an invalid Rubik cube % (e.g.,~enter an invalid number of, say, yellow facelets), this command -% checks the current colour state of all the cubies +% simply checks the current colour state of all the cubies % of a 3x3x3 Rubik cube, and shows the number of facelets of each colour. % An ERROR: code is issued if the number of facelets having a given colour exceeds~6. % The results are written to the the \texttt{.log} file, and displayed under @@ -736,7 +904,9 @@ % \CheckRubikState% %\end{verbatim} %\end{quote} -% Note that such a check is implemented automatically with each \cmd{\RubikRotation} command. +% Note (1)~that such a check is implemented automatically with each \cmd{\RubikRotation} +% command, and (2)~this is actually only a very superficial check---simply counting the number +% of cubies of each colour. % % % @@ -758,6 +928,7 @@ % Once the document is free of errors this command can be removed or just commented out. % Run the test file \texttt{example-rot.tex} to see an example of the use of this command. % +% % \section{Files generated} % % @@ -780,21 +951,22 @@ % % % \section{General overview} -% \label{generaloverview} -% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps -% are implemented. -% \begin{itemize} +% \label{generaloverview} % +% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps +% are implemented. +% \begin{itemize} % % \item[1.] A check is made to see if \texttt{fancyvrb.sty} is loaded: if not -% then this package is loaded if it is available (this package is required -% for inputting the file \texttt{rubikstateERRORS.dat}). +% then this package is loaded (this package supplies the command \cmd{\VerbatimInput} which +% is required for inputting the file \texttt{rubikstateERRORS.dat} in verbatim form). % % \item[2.] A check is made to see if a configuration-file (\texttt{rubikrotation.cfg}) % exists: if so then this file is input. % -% \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists): -% otherwise the file is created (this prevents an `old' file being used by \LaTeX). +% \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists), +% otherwise the file is created (this prevents an `old' version of the file being +% used by \LaTeX). % % \item[4.] The plain-text file \texttt{rubikstateERRORS.dat} is created. % This file collects error messages generated by the Perl script. @@ -804,14 +976,14 @@ % % When a \cmd{\RubikRotation} command is processed it first writes the current % colour configuration of each face (the `rubik state') to the temporary file -% \texttt{rubikstate.dat} (to be read by the Perl script \texttt{rubikrotation.pl}). +% \texttt{rubikstate.dat} (this will be read by the Perl script \texttt{rubikrotation.pl}). % The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}' % as well as a copy of the string of Rubik rotations. % It~then calls the Perl script \texttt{rubikrotation.pl}. % % For example, if we use the command \cmd{\RubikCubeSolved} % followed by the command \verb!\RubikRotation[2]{U,D,L,R}!, then the associated -% \texttt{rubikstate.dat} file would be as follows: +% \texttt{rubikstate.dat} file will be written as follows: %\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat @@ -826,12 +998,12 @@ % rotation,U,D,L,R %\end{verbatim} %\end{quote} -% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the line \texttt{rotation,U,D,L,R} +% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the string ``\texttt{rotation,U,D,L,R}'' % being written twice to the \texttt{rubikstate.dat} file, as shown above. % % Alternatively, if we used the command % \verb!\RubikRotation{random, 45}! then the last line written to the file -% would be the string `\texttt{rotation,random,45}', as follows: +% would be the string ``\texttt{rotation,random,45}'', as follows: %\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat @@ -846,29 +1018,31 @@ %\end{verbatim} %\end{quote} % A \cmd{\CheckRubikState} command triggers the same sequence of events except -% no `rotation' line is written. +% that no ``\texttt{rotation,....}'' line is written. % % The action of the Perl script \texttt{rubikrotation.pl} is controlled by % the keywords (first argument of % each line) associated with each line of the file \texttt{rubikstate.dat}. % When control passes to Perl, the script \texttt{rubikrotation.pl} starts -% by loading the current rubikstate (prompted by the keywords \texttt{up}, \texttt{down}, -% \texttt{left}, \texttt{right}, \texttt{front}, \texttt{back}, in the file -% \texttt{rubikstate.dat}). Next the Perl script -% performs some basic checks (prompted by the key word \texttt{checkstate}), and -% then it processes the sequence of Rubik rotations (prompted by the keyword -% \texttt{rotation}). If, instead, the second argument of the `rotation' string -% is the keyword `random', and provided this is followed by a valid integer, say $n$, +% by loading the current rubikstate (prompted by the keywords `\texttt{up}', `\texttt{down}', +% `\texttt{left}', `\texttt{right}', `\texttt{front}', `\texttt{back}'), and performing +% a syntax check---significant syntax errors at this stage +% will cause the program to issue appropriate error messages and then terminate cleanly. +% Next, the Perl script performs some basic cube checks +% (prompted by the key word `\texttt{checkstate}'), and then the program processes +% the sequence of Rubik rotations (prompted by the keyword +% `\texttt{rotation}'). If, instead, the second argument of the `\texttt{rotation,...}' string +% is the keyword `\texttt{random}', and provided this is followed by a valid integer, say $n$, % then the Perl script performs a sequence of $n$ random rotations. -% Finally, the Perl script writes the final `rubikstate' to the text file +% Finally, the Perl script writes the final rubikstate to the text file % \texttt{rubikstateNEW.dat}. All error messages are written to the -% text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log file. +% text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log-file. % % Control then reverts to \LaTeX\ which then inputs the file % \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands -% then this cycle repeats accordingly. Eventually a \cmd{\Draw...} command -% of some form is reached and the final rubikstate is drawn in a TikZ picture -% environment. +% (in the \texttt{.tex} file) then this cycle repeats accordingly. +% Eventually a \cmd{\Draw...} command is reached (in the \texttt{.tex} file) and +% the final rubikstate is drawn in a TikZ picture environment. % % If the TikZ picture environment is followed by a \cmd{\ShowRubikErrors} command, % then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed @@ -911,13 +1085,22 @@ % \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf} % {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,] % +% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm} % -% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package. +% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package, v3.0. % \newline\url{http://www.ctan.org/pkg/rubik}, % -% \item Reid M. \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html} -% {\newline}[\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,] % +% \item Randelshofer website (Randelshofer W). \url{http://www.randelshofer.ch/rubik/} +% \ [\,re:~sequences and supersetENG notation\,] +% +% +% \item Reid website (Reid M). \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html} +% \ [\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,] +% +% +% \item Tellechea C and Segletes SB (2016). The \textsf{listofitems} package, v1.2 +% \newline\url{http://www.ctan.org/pkg/listofitems} %\end{itemize} % % @@ -925,6 +1108,27 @@ % \section{Change history} % % \begin{itemize} +% +% \item Version 4.0 (March 2017) +% +% --- The \cmd{\RubikRotation} command has been enhanced to allow its argument to include +% so-called repeat-blocks (rotation-sequences which can be repeated multiple times), and +% info-blocks for holding sequence metadata (see Section~\ref{sec:rubikrotationcmd}). +% Syntax checking of the \cmd{\RubikRotation} argument is much improved +% (see \texttt{rubikrotationPL.pdf} for details of the Perl script). +% +% --- Four new macros which hold derived data (see Section~\ref{sec:rubikrotationcmd}). +% \begin{quote} +% \cmd{\SequenceName} +% \newline\cmd{\SequenceInfo} +% \newline\cmd{\SequenceShort} +% \newline\cmd{\SequenceLong} +% \end{quote} +% +% --- Better syntax checking of the \cmd{\RubikRotation} argument by the Perl program \texttt{rubikrotation.pl}. +% +% +% % \item Version 3.0 (25 September 2015) % % --- The \cmd{\RubikRotation} command now actions multiple instances of its argument @@ -932,7 +1136,7 @@ % \cmd{\RubikRotation[3]\{R,x\}} is equivalent to the command \cmd{\RubikRotation\{R,x,R,x,R,x\}} % (see Sections~\ref{sec:rubikrotationcmd} and \ref{sec:rubikrotationcode}). % -% --- If a comma separated element used as an argument for the \cmd{\RubkRotation} +% --- If a comma separated element used as an argument for the \cmd{\RubikRotation} % command is prefixed with either a * or [ or ] character then it is not actioned % as a rotation (see Section~\ref{sec:prefixedargument}). % @@ -940,7 +1144,8 @@ % including \texttt{-h} to show some `help' and `usage' information % (see Section~\ref{sec:placingfiles}). % -% --- A `man' file for the Perl script \texttt{rubikrotation.pl} is now included in the package. +% --- A `man' file (manual file) for the Perl script \texttt{rubikrotation.pl} is now +% included in the package. % % --- The Perl script \texttt{rubikrotation.pl} now uses as input and output filenames % those specified in the command-line of the CALLing program. This now allows the @@ -964,7 +1169,7 @@ % % % -% \section{The code (\texttt{rubikrotation.sty})} +% \section[The code]{The code (\texttt{rubikrotation.sty})} % % {\noindent}In the following, the term `Perl script' denotes the script % \texttt{rubikrotation.pl}. Useful information regarding the @@ -973,11 +1178,12 @@ % Abrahams \textit{et.~al} (1990). % % \subsection{Package heading} +% \label{sec:CodePackageHeading} % % \begin{macrocode} %<*rubikrotation> -\def\RRfileversion{3.0}% -\def\RRfiledate{2015/09/25}% +\def\RRfileversion{4.0}% +\def\RRfiledate{2017/03/03}% \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)] % \end{macrocode} @@ -994,7 +1200,7 @@ % % % -% {\noindent}The \rubikrotation\ package requires access to the fancyvrb package +% {\noindent}The \rubikrotation\ package requires access to the \textsf{fancyvrb} package % for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying % the error file (see Section~\ref{sec:showrubikerrors}). % \begin{macrocode} @@ -1004,6 +1210,24 @@ \RequirePackage{fancyvrb}} % \end{macrocode} % +% +% {\noindent}For the \cmd{\write18} syntax to work with +% Lua\TeX\ (so we can access system commands) we require +% the recent \textsf{shellesc} package, which we load using the +% \textsf{ifluatex} conditional (see Section~\ref{sec:shellescape}). +% \begin{macrocode} +\@ifpackageloaded{ifluatex}{}{% + \typeout{---rubikrotation requires the ifluatex package.}% + \RequirePackage{ifluatex}} +\ifluatex% + \@ifpackageloaded{shellesc}{}{% + \typeout{---rubikrotation requires the shellesc package + to run using Lua\LaTeX.}% + \RequirePackage{shellesc}} +\fi% +% \end{macrocode} +% +% % \medskip % % \subsection{Some useful commands} @@ -1059,30 +1283,30 @@ \newcommand{\rubikperlname}{rubikrotation} % \end{macrocode} % \end{macro} -% +% Note that here we are assuming that the script is an executable file. % % \begin{macro}{\rubikperlcmd} % This holds the command-line code for calling the Perl script -% (assumed to be an executable file). % Note that the command-line requires a mandatory input filename preceded % by the \texttt{-i}~switch. An optional output filename (preceded by the % \texttt{-o}~switch) may be used, otherwise the default output filename of % \texttt{rubik-OUT.dat} will be used. % -% Note that it is very important that this .sty file actually specifies an +% Note that it is very important that we do actually specify an % output filename (for receiving data from the Perl script). This is because % (a)~The Perl script \texttt{rubikrotation.pl} is currently configured to read its % output filename as an argument from the command-line (so it can be flexibly % used as a stand-alone script for processing a given Rubik state through a % sequence of rotations), and (b)~\texttt{rubikrotation.sty} is currently -% configured to read its input from the file \texttt{rubikstateNEW.dat}. +% configured to read its input (i.e.,~data generated by the Perl script) +% from the file \texttt{rubikstateNEW.dat}. % \begin{macrocode} \newcommand{\rubikperlcmd}{\rubikperlname\space% -i rubikstate.dat -o rubikstateNEW.dat} % \end{macrocode} -% Remember to use the \cmd{\space} command following the \LaTeX\ backslash -% command in order to generate the mandatory space between it and the first -% command-line argument). +% Remember to use the \cmd{\space} macro following the \cmd{\rubikperlname} macro +% in order to generate the mandatory space before the first +% command-line argument. % % A plain-text configuration-file \verb!rubikrotation.cfg! can be used to % change the default command-line code using a renewcommand @@ -1094,7 +1318,7 @@ % % If a configuration file exists (\texttt{rubikrotation.cfg}) then input it here, % i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd} -% commands and \textit{before} creating the \texttt{rubikstateERRORS.dat} file. +% macros and \textit{before} creating the \texttt{rubikstateERRORS.dat} file. % \begin{macrocode} \typeout{---checking for config file (rubikrotation.cfg)...} \IfFileExists{rubikrotation.cfg}{% @@ -1139,7 +1363,7 @@ \newwrite\outfile% \immediate\openout\outfile=rubikstateERRORS.dat% \@print{\@comment rubikstateERRORS.dat}% -\@print{\@comment ---(RR.sty v\RRfileversion): comments output by Perl script}% +\@print{\@comment --------------------}% \immediate\closeout\outfile% % \end{macrocode} % @@ -1184,7 +1408,7 @@ % in order to trigger the Perl script to implement its \texttt{checkstate} subroutine. % % The actual state is simply an ordered sequence of the faces and the colours -% associated with each facelet of that face. The colour associated with a particular facelet +% associated with each facelet of a face. The colour associated with a particular facelet % is held by the variable for that facelet. For example, the top-left facelet associated with % the \textsc{front} face is held in the variable \cmd{\Flt} (see Section~\ref{saverubikstate}). % Further relevant documentation is in the \textsc{rubikcube} package. @@ -1256,10 +1480,12 @@ % Perl script \texttt{rubikrotation.pl}. It~also writes comments to the % data file and also to the log file. % -% In order to allow the user to (optionally) write the main argument multiple -% times to the output data-file, we require this command to allow an optional +% The way we allow the user to (optionally) process the main argument multiple +% times is simply by writing the associated output command multiple +% times to the output data-file. Consequently, we require the \cmd{\RubikRotation} +% command to allow a square-bracket optional % argument (a non-negative integer) to specify the number of such repeats. -% In order to implement an optional argument facility we use two macros +% In order to implement this optional argument facility we use two macros % (countingloop and loopcounter) detailed by Feuers\"{a}nger (2015) % [\,see refs Section~\ref{sec:references}\,]\label{sec:feuersanger}, % as follows: @@ -1286,8 +1512,9 @@ % the command to write the main argument to the output data file. % \begin{macrocode} \newcommand{\RubikRotation}[2][1]{% + \typeout{---TeX process (rubikrotation.sty)-------}% \typeout{---NEW rotation command------------------}% - \typeout{---command = RubikRotation{#1}}% + \typeout{---command = RubikRotation[#1]{#2}}% \typeout{---writing current Rubik state to file rubikstate.dat}% \@openstatefile% open data file \@print{\@comment filename: rubikstate.dat}% @@ -1299,14 +1526,20 @@ \@countingloop{\ourRRcounter} in 1:{#1}{% \immediate\write\outfile{rotation,#2}}% \@closestatefile% close data file - \typeout{---running Perl script (rubikrotation)}% + \typeout{---CALLing Perl script (rubikrotation.pl)}% \immediate\write18{\rubikperlcmd}% - \typeout{---inputting NEW datafile (written by Perl script)}% + \typeout{---inputting NEW datafile (data written by Perl script)}% \input{rubikstateNEW.dat}% \typeout{-----------------------------------------}% } % \end{macrocode} % \end{macro} +% Note that the new \cmd{\ShellEscape} command implemented by the recent +% \textsf{shellesc} package is equivalent to \cmd{\immediate}\cmd{\write18} (see above), +% and so we probably ought to use \cmd{\ShellEscape} instead in future (and hence load +% \textsf{shellesc} automatically). At present, however, we leave the user to make +% sure that the \textsf{shellesc} package is actually available on their system. +% % % % \subsection{ShowRubikErrors command} @@ -1314,11 +1547,13 @@ % % \begin{macro}{\ShowRubikErrors} % This command inputs the file \texttt{rubikstateERRORS.dat}. +% Also made a more convenient synonym = \cmd{\ShowErrors}. % \begin{macrocode} \newcommand{\ShowRubikErrors}{% \typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}% \VerbatimInput{rubikstateERRORS.dat}% } +\newcommand{\ShowErrors}{\ShowRubikErrors} % \end{macrocode} % \end{macro} % @@ -1340,9 +1575,9 @@ \@print{\@comment filename: rubikstate.dat}% \@printrubikstate% \@closestatefile% close data file - \typeout{---running Perl script (rubikrotation)}% + \typeout{---running Perl script (rubikrotation.pl)}% \immediate\write18{\rubikperlcmd}% - \typeout{---inputting NEW datafile (written by Perl script)}% + \typeout{---inputting NEW datafile (data written by Perl script)}% \input{rubikstateNEW.dat}% \typeout{-----------------------------------------}% } |