diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/rubik/rubikrotation.dtx')
| -rw-r--r-- | Master/texmf-dist/source/latex/rubik/rubikrotation.dtx | 396 |
1 files changed, 244 insertions, 152 deletions
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx index 2b554ef7128..33103cfc54b 100644 --- a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx +++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx @@ -1,12 +1,13 @@ % \iffalse meta-comment % rubikrotation.dtx % -% version 4.0 +% version 5.0 +% % % Authors: RWD Nickalls (dick@nickalls.org) % and Apostolos Syropoulos (asyropoulos@yahoo.com) - -% Copyright 03 March 2017 RWD Nickalls + A Syropoulos +% +% Copyright 25 February 2018 RWD Nickalls + A Syropoulos % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either @@ -37,6 +38,8 @@ (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J process rubikrotation.dtx again)^^J}\stop }% +\pagestyle{myheadings} +\markright{\texttt{rubikrotation} \ \ (Rubik bundle v5.0, 2018) \ \ \texttt{www.ctan.org/pkg/rubik}} \usepackage{ifpdf} \usepackage{url,path} %% for references and paths \usepackage{graphicx} %% for the two pdf figs @@ -58,7 +61,7 @@ % % % -%%% \CheckSum{322} +%%% \CheckSum{332} % %%% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z @@ -98,7 +101,7 @@ % \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration). % The \rubikrotation\ package also provides commands for saving the cube state % to a file (\cmd{\SaveRubikState}), and for displaying any -% errors (\cmd{\ShowRubikErrors}). +% errors (\cmd{\ShowErrors}). % \end{abstract} % % @@ -119,7 +122,8 @@ % % \section{Introduction} % -% The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} package. +% The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} +% and \textsc{rubiktwocube} packages. % It consists of a style option (\texttt{rubikrotation.sty}), a % Perl script (\texttt{rubikrotation.pl}). % @@ -135,22 +139,23 @@ % (\texttt{http://strawberryperl.com}) is a free Perl % environment for MS Windows, designed to be as close as possible to the Perl % environment of Unix/Linux systems.}), on a Linux platform (Debian v8.2.0, -% {\TeX}Live 2016, and Perl v5.20.2), and on a Solaris platform (OpenIndiana). +% {\TeX}Live 2017, and Perl v5.20.2), and on a Solaris platform (OpenIndiana). % % The following commands are made available by \texttt{rubikrotation.sty}: % \begin{quote} % \begin{verbatim} % \RubikRotation[]{} % \SaveRubikState -% \CheckRubikState -% \ShowRubikErrors +% \CheckState +% \ShowErrors % \SequenceName % \SequenceInfo % \SequenceShort % \SequenceLong %\end{verbatim} % \end{quote} -% +% Note that the \textsc{rubiktwocube} package makes available the (equivalent) +% \verb!\TwoRotation[]{}! and \verb!\SaveTwoState! commands. % % \section{Requirements} % @@ -209,8 +214,9 @@ % \label{sec:placingfiles} % % Place the files either in a working directory, or where your system -% will find them, e.g.,~in your \texttt{/texmf-local/} directory tree. -% For example, on a Linux platform with a standard \TeX\ Directory Structure (TDS), then: +% will find them, e.g.,~in the `\textsc{path}'. The \texttt{/texmf-local/} directory tree +% is often a good place; for example, on a Linux platform with a +% standard \TeX\ Directory Structure (TDS), then: % %\medskip %{\noindent}*.sty $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} @@ -222,8 +228,8 @@ %{\noindent}\textsc{perl script}:\ \ Make the perl script executable % (\texttt{chmod +x rubikrotation.pl}), and then % rename the file as `rubikrotation' (i.e.,~with no file extension), and then place -% the executable script into your current TeXLive binary directory, -% e.g.,~\path!/user/local/texlive/YYYY/bin/i386-linux!. +% the executable script in the `\textsc{path}', or possibly, directly into your +% {\TeX}Live binary directory, e.g.,~\path!/user/local/texlive/YYYY/bin/i386-linux!. % % Sometimes the setting up of a simple one or two-line plain-text % configuration-file may be useful or even necessary, depending on your system @@ -232,14 +238,17 @@ % file is named \texttt{rubikrotation.cfg}. % %\medskip -%{\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!. +%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform the manual file +% (\texttt{rubikrotation.1}) is typically located in +% either \verb!/usr/local/man/man1! or \verb!/usr/local/share/man/man1!. +% \TeX{Live} typically places such files in the directory +% \verb!/texmf-dist/doc/man/man1!. % %\medskip %{\noindent}\textsc{file database}:\ \ Finally, (depending on your system) update the % \TeX\ file database. -% For example, on a Linux platform this is achieved using the \texttt{texhash} command. +% For example, on a Linux platform this is achieved using the \texttt{texhash} command, +% or by using the {\TeX}Live Manager (\texttt{tlmgr}). % %\medskip %{\noindent}\textsc{quick test}:\ \ To test that your system can now run the perl @@ -251,12 +260,13 @@ %\end{quote} % which should generate something like the following: % \begin{verbatim} -% This is rubikrotation version 4.0 +% This is rubikrotation version ... % Usage: rubikrotation [-h] -i <input file> [-o <out file>] % where, -% [-h] gives this help listing -% [-i] creates specified input file -% [-o] creates specified output file +% [-h|--help] gives this help listing +% [-v|--version] gives version +% [-i] creates specified input file +% [-o] creates specified output file % For documentation see: rubikrotation.pdf, % rubikrotationPL.pdf and rubikcube.pdf %\end{verbatim} @@ -265,13 +275,15 @@ % \section{Usage} % \label{sec:usage} % Load the packages \texttt{rubikcube.sty}, -% \texttt{rubikrotation.sty} and \texttt{rubikpatterns.sty} in the \TeX\ file +% \texttt{rubikrotation.sty}, \texttt{rubikpatterns.sty} +% and \texttt{rubiktwocube.sty} in the \TeX\ file % preamble \textit{after} loading the TikZ package (all the Rubik packages -% require the TikZ package); for example, as follows: +% require the TikZ package). Load the \texttt{rubikcube.sty} \textit{before} the other +% Rubik bundle packages; for example, as follows: %\begin{quote} % \begin{verbatim} % \usepackage{tikz} -% \usepackage{rubikcube,rubikrotation,rubikpatterns} +% \usepackage{rubikcube,rubikrotation,rubikpatterns,rubiktwocube} %\end{verbatim} %\end{quote} % and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line option @@ -319,6 +331,26 @@ % \subsection{Configuration-file} % \label{sec:configfile} % +% It is important to realise that the default action of \texttt{rubikrotation.sty} is to +% access the Perl script as an executable file. This is because the~default definitions +% in \texttt{rubikrotation.sty} are as follows: (they are detailed in +% Section~\ref{sec:usefulcommands}) +%\begin{quote} +%\begin{verbatim} +% \newcommand{\rubikperlname}{rubikrotation} +% \newcommand{\rubikperlcmd}{\rubikperlname\space% +% -i rubikstate.dat -o rubikstateNEW.dat} +%\end{verbatim} +%\end{quote} +% Note the need here (in the second macro) to use \cmd{\space} on the end of +% (\cmd{\rubikperlname}) in order to force a following +% space---i.e.,~before the first command-line argument. +% +% If the Perl script has not been made executable, or if you wish to alter how +% the \textsc{rubikrotation} package accesses the Perl script, +% then you need to create a plain-text configuration file in order to redefine one +% or both of the above commands, as described below. +% % A plain-text configuration-file with the name \texttt{rubikrotation.cfg} % (if one exists) will automatically be read by \texttt{rubikrotation.sty}. % The \rubikrotation\ package's facility to use a configuration-file allows the @@ -332,37 +364,24 @@ % Such~a configuration-file can also facilitate testing a new Perl script having % a different name and location. % -% % \DescribeMacro{\rubikperlname} % \DescribeMacro{\rubikperlcmd} % The configuration-file is essentially a convenient software vehicle for feeding % additional \LaTeX\ code to the style option \texttt{rubikrotation.sty}, and hence % allows the contents of some commands to be easily adjusted and/or fine-tuned. -% For~the \rubikrotation\ package there are two particular macros we may wish to adjust. +% For~the \rubikrotation\ package there are two particular macros we may wish to adjust +% (see above). % The~first is that holding the filename of the Perl script, namely % \cmd{\rubikperlname}. The second is that holding the command-line call, % namely \cmd{\rubikperlcmd}. -% The~default definitions in \texttt{rubikrotation.sty} (which assume the Perl -% script is executable), are as follows: (they are detailed in -% Section~\ref{sec:usefulcommands}) -%\begin{quote} -%\begin{verbatim} -% \newcommand{\rubikperlname}{rubikrotation} -% \newcommand{\rubikperlcmd}{\rubikperlname\space% -% -i rubikstate.dat -o rubikstateNEW.dat} -%\end{verbatim} -%\end{quote} -% Note the need here (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. +% The following examples illustrate how the configuration-file may be used. % % \medskip % {\noindent}\textsc{example~1}:\ \ Suppose we wish to test out % a slightly modified Perl script % with the working (executable) name \texttt{rubikrotationR77}. In this case we % simply create, in the local working directory, a plain-text configuration-file -% (it \textit{must} be named exactly \texttt{rubikrotation.cfg}) and contains just +% (it \textit{must} be named exactly \texttt{rubikrotation.cfg}) containing just % the following line: %\begin{quote} %\begin{verbatim} @@ -387,7 +406,7 @@ %\end{quote} %{\noindent}Remember to make sure the PATH associated with the command is also correct. % -% +% \medskip %{\noindent\textsc{placing the configuration-file}:\ \ The simplest arrangement is % just to include the \texttt{.cfg} file in the working directory. % Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/} @@ -410,8 +429,8 @@ % the \textsc{rubikcube} package), although most commands can be placed % inside a TikZ environment if you wish. % -% However, using commands which influence the Rubik colour state -% (e.g.,~the \cmd{\RubikRotation} command) outside the \texttt{tikzpicture}, +% Using commands which influence the Rubik colour state +% (e.g.,~\cmd{\RubikFace..}, \cmd{\RubikCubeSolvedWY} etc.) outside the \texttt{tikzpicture}, % \texttt{minipage} or \texttt{figure} environments % generally offers maximum flexibility, since the effects of such commands when % used inside these environments remain `local' to the environment, and are not @@ -419,7 +438,7 @@ % (see also Section~4.1 in the \textsc{rubikcube} documentation). % % Conversely, the only \rubikrotation\ command which should \textit{not} -% be used inside a TikZ environment is the \cmd{\ShowRubikErrors} command +% be used inside a TikZ environment is the \cmd{\ShowErrors} command % (see the notes on this command below). % % @@ -432,7 +451,9 @@ % 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). +% implemented (see \textbf{Inverse} below). Note that the equivalent \cmd{\TwoRotation} +% command (see the \textsc{rubiktwocube} package) behaves in the same way as the +% \cmd{\RubikRotation} command in all respects. % % % The first (optional) argument \oarg{integer} of the \cmd{\RubikRotation} command is the number @@ -646,7 +667,7 @@ % \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}\,]. +% on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see references Section~\ref{sec:references}\,]. % Consequently we are able to use a sequence-defining macro as an argument for % the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows % one to store lots of different rotation sequences by name alone. Note that @@ -656,7 +677,7 @@ % 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}\,]. The `sixspot' sequence is +% Reid website)[\,see references Section~\ref{sec:references}\,]. The `sixspot' sequence is % defined as follows: %\begin{quote} % \begin{verbatim} @@ -790,10 +811,9 @@ % % The \cmd{\RubikRotation} command can also be used to scramble the % cube using a random sequence of rotations. If the first argument -% is the lower-case word `random' \textsc{and} the second argument +% is the word `random' \textsc{and} the second argument % is an integer $n$, ($1\leq n \leq 200$), then a random sequence -% of $n$ rotations will be performed; otherwise a default value -% of 50 is used (for example, if the second argument is not an integer). +% of $n$ rotations will be performed. % If $n > 200$ then the currently set maximum value $n=200$ will be used. % % As a safety feature the maximum $n$ can be changed only by editing the @@ -887,46 +907,54 @@ %\end{quote} % % -% \subsection[CheckRubikState]{\cmd{\CheckRubikState} command} +% \subsection[CheckState]{\cmd{\CheckState} command} +% \label{sec:checkstate} % -% \DescribeMacro{\CheckRubikState} +% \DescribeMacro{\CheckState} % Since it is easy to inadvertently define an invalid Rubik cube % (e.g.,~enter an invalid number of, say, yellow facelets), this command % simply checks the current colour state of all the cubies % of a 3x3x3 Rubik cube, and shows the number of facelets of each colour. -% An ERROR: code is issued if the number of facelets having a given colour exceeds~6. -% The results are written to the the \texttt{.log} file, and displayed under -% the graphic if the \cmd{\ShowRubikErrors} command is used. +% An ERROR: code is issued if the number of facelets having a given colour +% exceeds~9 for a 3x3x3 cube (Rubik cube), or exceeds 4 for a 2x2x2 cube (Two cube). +% The results are written to the the \texttt{.log} file, and displayed at the point +% the \cmd{\ShowErrors} command is used (for code see Section~\ref{sec:checkstatecode}). % % One can check the current Rubik state (for errors) by issuing the command %\begin{quote} %\begin{verbatim} -% \CheckRubikState% +% \CheckState% %\end{verbatim} %\end{quote} -% 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 +% Note (1)~that such a check is implemented automatically with each \cmd{\RubikRotation} and +% \cmd{\TwoRotation} command, and (2)~and makes only a very superficial check---simply counting the number % of cubies of each colour. % +% Note that the \cmd{\CheckState} command replaces the earlier \cmd{\CheckRubikState}, but +% we retain the old command for backwards compatibility (for the moment). % % +% \subsection[ShowErrors]{\cmd{\ShowErrors} command} +% \label{sec:showerrors} % -% \subsection[ShowRubikErrors]{\cmd{\ShowRubikErrors} command} % -% \DescribeMacro{\ShowRubikErrors} +% \DescribeMacro{\ShowErrors} % Any errors which arise can be made visible using the -% command \cmd{\ShowRubikErrors}. +% command \cmd{\ShowErrors}. % This command places a copy of the `error' file (\texttt{rubikstateERRORS.dat}) -% underneath the graphic image so you can see any errors if there are any---all this -% detail can also be found in the \texttt{.log} file. +% underneath the graphic image so you can see any errors if there are any (note that +% details of all errors are are written by default to the \texttt{.log} file) +% (for code see Section~\ref{sec:showerrorscode}). % -% Consequently, this command must be placed \textit{after} a TikZ picture +% Consequently, the \cmd{\ShowErrors} command must be placed \textit{after} a TikZ picture % environment---it cannot be used inside a TikZ environment. In fact this command -% is probably best placed at the end of the document (if there are several such -% environments), where it will reveal all rotation errors generated while -% processing the whole document. +% is probably best placed at the end of the document where it will reveal all +% rotation errors generated while processing the whole document. % Once the document is free of errors this command can be removed or just commented out. -% Run the test file \texttt{example-rot.tex} to see an example of the use of this command. +% The file \texttt{rubikexamples.pdf} shows an example of the use of this command. +% +% Note that the \cmd{\ShowErrors} command replaces the original \cmd{\ShowRubikErrors} command, +% which will be retained for backward compatibility. % % % \section{Files generated} @@ -945,7 +973,7 @@ % \item The Perl script \texttt{rubikrotation.pl} also writes error data % to the file \texttt{rubikstateERRORS.dat}. A copy of this file is displayed % under the graphic image when the command -% \cmd{\ShowRubikErrors} is used after the TikZ picture environment. +% \cmd{\ShowErrors} is used after the TikZ picture environment. % % \end{itemize} % @@ -954,7 +982,7 @@ % \label{generaloverview} % % When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps -% are implemented. +% are implemented (see Section~\ref{sec:thecode}): % \begin{itemize} % % \item[1.] A check is made to see if \texttt{fancyvrb.sty} is loaded: if not @@ -974,7 +1002,8 @@ % \end{itemize} % % -% When a \cmd{\RubikRotation} command is processed it first writes the current +% When a \cmd{\RubikRotation} command is processed +% (see Section~\ref{sec:rubikrotationcode}, line~102), it first writes the current % colour configuration of each face (the `rubik state') to the temporary file % \texttt{rubikstate.dat} (this will be read by the Perl script \texttt{rubikrotation.pl}). % The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}' @@ -987,6 +1016,7 @@ %\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat +% cubesize,three % up,W,W,W,W,W,W,W,W,W % down,Y,Y,Y,Y,Y,Y,Y,Y,Y % left,B,B,B,B,B,B,B,B,B @@ -1007,6 +1037,7 @@ %\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat +% cubesize,three % up,W,W,W,W,W,W,W,W,W % down,Y,Y,Y,Y,Y,Y,Y,Y,Y % left,B,B,B,B,B,B,B,B,B @@ -1017,13 +1048,13 @@ % rotation,random,45 %\end{verbatim} %\end{quote} -% A \cmd{\CheckRubikState} command triggers the same sequence of events except +% A \cmd{\CheckState} command triggers the same sequence of events except % that no ``\texttt{rotation,....}'' line is written. % % The action of the Perl script \texttt{rubikrotation.pl} is controlled by % the keywords (first argument of % each line) associated with each line of the file \texttt{rubikstate.dat}. -% When control passes to Perl, the script \texttt{rubikrotation.pl} starts +% When control passes from \LaTeX\ to Perl, the script \texttt{rubikrotation.pl} starts % by loading the current rubikstate (prompted by the keywords `\texttt{up}', `\texttt{down}', % `\texttt{left}', `\texttt{right}', `\texttt{front}', `\texttt{back}'), and performing % a syntax check---significant syntax errors at this stage @@ -1036,21 +1067,29 @@ % then the Perl script performs a sequence of $n$ random rotations. % Finally, the Perl script writes the final rubikstate to the text file % \texttt{rubikstateNEW.dat}. All error messages are written to the -% text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log-file. +% text file \texttt{rubikstateERRORS.dat} and also to the \LaTeX\ log-file. +% The Perl script now closes all open files and terminates. % -% Control then reverts to \LaTeX\ which then inputs the file +% Control then passes back to \LaTeX\ (still in \texttt{rubikrotation.sty} processing +% the \cmd{\RubikRotation} command---see Section~\ref{sec:rubikrotationcode}, line~115); +% its next action is to input the file % \texttt{rubikstateNEW.dat}. If there are more \cmd{\RubikRotation} commands % (in the \texttt{.tex} file) then this cycle repeats accordingly. % Eventually a \cmd{\Draw...} command is reached (in the \texttt{.tex} file) and % the final rubikstate is drawn in a TikZ picture environment. % -% If the TikZ picture environment is followed by a \cmd{\ShowRubikErrors} command, +% If the TikZ picture environment is followed by a \cmd{\ShowErrors} command, % then a `verbatim' copy of the \texttt{rubikstateERRORS.dat} file is displayed % immediately under the graphic. Once the graphic is error-free, then the -% \cmd{\ShowRubikErrors} command can be removed or commented out. +% \cmd{\ShowErrors} command can be removed or commented out. +% +% Alternatively, when processing a long document, it can be useful to place +% a \cmd{\ShowErrors} command at the end of the document, where it will list +% all errors which occurred. Once any errors have been fixed, this command can be +% removed or commented out. % % Note that if a \textsc{bash} file is used to coordinate the process then it is often -% convenient to use the linux \texttt{grep} utility to alert the user to any run-time errors, +% convenient to use the Linux \texttt{grep} utility to alert the user to any run-time errors, % by using \texttt{grep} to scan the \texttt{rubikstateERRORS.dat} file at the end of % the run; for example, as follows: %\begin{quote} @@ -1062,53 +1101,37 @@ %\end{quote} % % -% \section{References} -% \label{sec:references} -% -%\begin{itemize} -% -% \item Abrahams PW, Berry K and Hargreaves KA (1990). \textit{\TeX\ for the impatient} -% (Addison-Wesley Publishing Company), page~292. -% {\newline}Available from: \url{http://www.ctan.org/pkg/impatient} -% {\newline}[\,re:~\cmd{\rubikpercentchar} and \cmd{\@comment} in Section~\ref{sec:abrahams}\,] -% -% -% \item Eijkhout V (1992). \textit{\TeX\ by topic: a {\TeX}nician's reference}. -% (Addison-Wesley Publishing Company), pages~232 \&~238. -% {\newline}Available from: \url{https://bitbucket.org/VictorEijkhout/tex-by-topic/} -% [\,re:~\cmd{\string} in Section~\ref{sec:eijkhout}\,] -% [\,re:~\cmd{\write} in Section~\ref{sec:seq-as-macros}\,] % % -% \item Feuers\"{a}nger C (2015). Notes on programming in \TeX. -% {\newline}(revision: 1.12.1-32-gc90572c; 2015/07/29) -% \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf} -% {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,] -% -% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm} -% -% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package, v3.0. -% \newline\url{http://www.ctan.org/pkg/rubik}, -% -% -% \item Randelshofer website (Randelshofer W). \url{http://www.randelshofer.ch/rubik/} -% \ [\,re:~sequences and supersetENG notation\,] -% +% \section{Change history} % -% \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}\,] +% \begin{itemize} % +% \item Version 5.0 (February 2018) % -% \item Tellechea C and Segletes SB (2016). The \textsf{listofitems} package, v1.2 -% \newline\url{http://www.ctan.org/pkg/listofitems} -%\end{itemize} +% --- minor bugfixes and better syntax checking in the Perl program. +% The cube size being processed (ie 3x3x3 or 2x2x2) is now detected by the program. +% +% --- the command \cmd{\CheckState} replaces the earlier +% \cmd{\CheckRubikState} command in order +% to avoid confusion, now that we are able to process both the 3x3x3 cube (Rubik cube) +% and also the 2x2x2 cube (Two cube) +% (see Sections~\ref{sec:checkstate} and \ref{sec:checkstatecode} (code)). +% The original command is retained (for now) for backward compatibility. +% \verb!\CheckRubikState! $\rightarrow$ \verb!\CheckState! +% +% --- the command \cmd{\ShowErrors} replaces the earlier +% \cmd{\ShowRubikErrors} command in order +% to avoid confusion now, that we are able to process both the 3x3x3 cube (Rubik cube) +% and also the 2x2x2 cube (Two cube) +% (see Sections~\ref{sec:showerrors} and \ref{sec:showerrorscode} (code)). +% The original command is retained (for now) for +% backward compatibility. \verb!\ShowRubikErrors! $\rightarrow$ \verb!\ShowErrors! +% +% % % % -% \section{Change history} -% -% \begin{itemize} -% % \item Version 4.0 (March 2017) % % --- The \cmd{\RubikRotation} command has been enhanced to allow its argument to include @@ -1147,7 +1170,7 @@ % --- 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 +% --- The Perl script \texttt{rubikrotation.pl} now uses as input and output file-names % those specified in the command-line of the CALLing program. This now allows the % script \texttt{rubikrotation.pl} to be used as a stand-alone tool (see the % \texttt{rubikrotation} `man' file for details). @@ -1164,12 +1187,63 @@ % % \end{itemize} % +% +% +% +% +% \section{References} +% \label{sec:references} +% +%\begin{itemize} +% +% \item Abrahams PW, Berry K and Hargreaves KA (1990). \textit{\TeX\ for the impatient} +% (Addison-Wesley Publishing Company), page~292. +% {\newline}Available from: \url{http://www.ctan.org/pkg/impatient} +% {\newline}[\,re:~\cmd{\rubikpercentchar} and \cmd{\@comment} in Section~\ref{sec:abrahams}\,] +% +% +% \item Eijkhout V (1992). \textit{\TeX\ by topic: a {\TeX}nician's reference}. +% (Addison-Wesley Publishing Company), pages~232 \&~238. +% {\newline}Available from: \url{https://bitbucket.org/VictorEijkhout/tex-by-topic/} +% [\,re:~\cmd{\string} in Section~\ref{sec:eijkhout}\,] +% [\,re:~\cmd{\write} in Section~\ref{sec:seq-as-macros}\,] +% +% +% \item Feuers\"{a}nger C (2015). Notes on programming in \TeX. +% {\newline}(revision: 1.12.1-32-gc90572c; 2015/07/29) +% \newline\url{http://pgfplots.sourceforge.net/TeX-programming-notes.pdf} +% {\newline}[\,re:~loop macros in Section~\ref{sec:feuersanger}\,] +% +% \item Kociemba website (Kociemba H). \url{http://www.kociemba.org/cube.htm} +% +% \item Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package, v3.0. +% \newline\url{http://www.ctan.org/pkg/rubik}, +% +% +% \item Randelshofer website (Randelshofer W). \url{http://www.randelshofer.ch/rubik/} +% \ [\,re:~sequences and supersetENG notation\,] +% +% +% \item Reid website (Reid M). \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html} +% \ [\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,] +% +% +% \item Tellechea C and Segletes SB (2016). The \textsf{listofitems} package, v1.2 +% \newline\url{http://www.ctan.org/pkg/listofitems} +% +%\end{itemize} +% +% +% +% +% % ^^A ================================================== % \StopEventually{\PrintIndex} % -% +% % % \section[The code]{The code (\texttt{rubikrotation.sty})} +% \label{sec:thecode} % % {\noindent}In the following, the term `Perl script' denotes the script % \texttt{rubikrotation.pl}. Useful information regarding the @@ -1182,8 +1256,8 @@ % % \begin{macrocode} %<*rubikrotation> -\def\RRfileversion{4.0}% -\def\RRfiledate{2017/03/03}% +\def\RRfileversion{5.0}% +\def\RRfiledate{2018/02/25}% 25 February 2018 \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)] % \end{macrocode} @@ -1202,7 +1276,7 @@ % % {\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}). +% the error file (see Section~\ref{sec:showerrors}). % \begin{macrocode} \@ifpackageloaded{fancyvrb}{}{% \typeout{---rubikrotation requires the fancyvrb package% @@ -1348,7 +1422,7 @@ % {\noindent}We first open the file \texttt{rubikstateERRORS.dat} which is used % by the Perl script \texttt{rubikrotation.pl} for writing its error-messages to. % This file is displayed by the command -% \cmd{\ShowRubikErrors}. +% \cmd{\ShowErrors}. % % \textsc{important note}: this file is created fresh each time LaTeX is run, % and hence the Perl script only appends data to it during the \LaTeX\ run, @@ -1362,8 +1436,8 @@ \typeout{---creating file rubikstateERRORS.dat}% \newwrite\outfile% \immediate\openout\outfile=rubikstateERRORS.dat% -\@print{\@comment rubikstateERRORS.dat}% -\@print{\@comment --------------------}% +\@print{\@comment ShowErrors (rubikstateERRORS.dat)}% +\@print{\@comment ---------------------------------}% \immediate\closeout\outfile% % \end{macrocode} % @@ -1372,7 +1446,7 @@ % % Having set up all the primary files, we now need to set up a newwrite for % all subsequent file openings (e.g.,~for \texttt{rubikstate.dat} and saving -% to arbitrary filenames by the \cmd{\SaveRubikState} command). Otherwise, we +% to arbitrary file-names by the \cmd{\SaveRubikState} command). Otherwise, we % can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use % \texttt{openout7} when opening and writing to files. We will implement new % openings using the command \verb!\@openstatefile! (see below). @@ -1404,23 +1478,23 @@ % (see Sections~\ref{saverubikstate} and \ref{generaloverview}). % The file \texttt{rubikstate.dat} is read by the Perl script, and represents % the state on which the new \cmd{\RubikRotation} command acts. -% Note that we append the key-word \texttt{checkstate} to the end of the file -% in order to trigger the Perl script to implement its \texttt{checkstate} subroutine. +% Note that we include the line \texttt{cubesize,three} to inform the Perl script +% that the cube is a 3x3x3 cube (this is used in the `random' subroutine). % -% The actual state is simply an ordered sequence of the faces and the colours +% The actual state (colour state) is simply an ordered sequence of the faces and the colours % associated with each facelet of a face. The colour associated with a particular facelet % is held by the variable for that facelet. For example, the top-left facelet associated with % the \textsc{front} face is held in the variable \cmd{\Flt} (see Section~\ref{saverubikstate}). % Further relevant documentation is in the \textsc{rubikcube} package. % \begin{macrocode} \newcommand{\@printrubikstate}{% + \@print{cubesize,three}% \@print{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}% \@print{down,\Dlt,\Dmt,\Drt,\Dlm,\Dmm,\Drm,\Dlb,\Dmb,\Drb}% \@print{left,\Llt,\Lmt,\Lrt,\Llm,\Lmm,\Lrm,\Llb,\Lmb,\Lrb}% \@print{right,\Rlt,\Rmt,\Rrt,\Rlm,\Rmm,\Rrm,\Rlb,\Rmb,\Rrb}% \@print{front,\Flt,\Fmt,\Frt,\Flm,\Fmm,\Frm,\Flb,\Fmb,\Frb}% \@print{back,\Blt,\Bmt,\Brt,\Blm,\Bmm,\Brm,\Blb,\Bmb,\Brb}% - \@print{checkstate}% } % \end{macrocode} % \end{macro} @@ -1440,8 +1514,8 @@ % Note that this macro uses the internal commands \cmd{\@comment} (`\%\%'), % \cmd{\@commentone} (`\%') and \cmd{\@print}. \#1 is the output filename. % We use several \cmd{\typeout} commands to write to the log file. -% An example of the line of code we are trying to output to the -%\texttt{rubikstateNEW.dat} file is as follows: +% An example of one of the lines of code we are trying to output to the +%\texttt{rubikstateNEW.dat} file is as follows: % {\newline}\verb!\RubikFaceUp{W}{W}{G}{W}{W}{G}{B}{B}{Y}%! % \begin{macrocode} \newcommand{\SaveRubikState}[1]{% @@ -1512,10 +1586,11 @@ % 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{---TeX process---------------------------}% + \typeout{---script = rubikrotation.sty v\RRfileversion\space (\RRfiledate)}% + \typeout{---NEW rotation command}% \typeout{---command = RubikRotation[#1]{#2}}% - \typeout{---writing current Rubik state to file rubikstate.dat}% + \typeout{---writing current cube state to file rubikstate.dat}% \@openstatefile% open data file \@print{\@comment filename: rubikstate.dat}% \@print{\@comment written by rubikrotation.sty% @@ -1542,38 +1617,54 @@ % % % -% \subsection{ShowRubikErrors command} -% \label{sec:showrubikerrors} +% \subsection{ShowErrors command} +% \label{sec:showerrorscode} % -% \begin{macro}{\ShowRubikErrors} -% This command inputs the file \texttt{rubikstateERRORS.dat}. -% Also made a more convenient synonym = \cmd{\ShowErrors}. +% \begin{macro}{\ShowErrors} +% This command inputs the file \texttt{rubikstateERRORS.dat} +% (output by the Perl program). % \begin{macrocode} -\newcommand{\ShowRubikErrors}{% - \typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}% +\newcommand{\ShowErrors}{% + \typeout{---ShowErrors: inputting file rubikstateERRORS.dat}% \VerbatimInput{rubikstateERRORS.dat}% } -\newcommand{\ShowErrors}{\ShowRubikErrors} +% \end{macrocode} +% Since this command replaces the original command = \cmd{\ShowRubikErrors}, we will +% retain the original command for backward compatibility (for the moment at least). +% \begin{macrocode} +\newcommand{\ShowRubikErrors}{\ShowErrors} % \end{macrocode} % \end{macro} % % -% \subsection{CheckRubikState command} +% \subsection{CheckState command} +% \label{sec:checkstatecode} % -% \begin{macro}{\CheckRubikState} +% \begin{macro}{\CheckState} % This command triggers the Perl script to implement % some simple error checking of the Rubik configuration (state). % This command (a)~writes the current Rubik state to the file -% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl script. -% It also writes comments to the data file and also to the log file.. +% \texttt{rubikstate.dat}, (b)~writes the keyword `checkstate' to the +% same file, and then (c)~CALLs the Perl script. +% It also writes comments to the data file and also to the log file. +% +% Note (1)~that the command \cmd{\@printrubikstate} actually writes the +% current state to the file \texttt{rubikstate.dat}, (2)~the keyword `checkstate' +% triggers the Perl program to do a simple numerical check on the number +% of facelets with each colour. +% +% Note also that the \cmd{\CheckState} command replaces the earlier +% \cmd{\CheckRubikState}, but we retain the old command for backwards +% compatibility (for the moment). % \begin{macrocode} -\newcommand{\CheckRubikState}{% +\newcommand{\CheckState}{% \typeout{---NEW check command------------------}% - \typeout{---command = CheckRubikState}% - \typeout{---writing current Rubik state to file rubikstate.dat}% + \typeout{---command = CheckState}% + \typeout{---writing current cube state to file rubikstate.dat}% \@openstatefile% opens data file \@print{\@comment filename: rubikstate.dat}% \@printrubikstate% + \immediate\write\outfile{checkstate}% \@closestatefile% close data file \typeout{---running Perl script (rubikrotation.pl)}% \immediate\write18{\rubikperlcmd}% @@ -1581,6 +1672,7 @@ \input{rubikstateNEW.dat}% \typeout{-----------------------------------------}% } +\newcommand{\CheckRubikState}{\CheckState} % \end{macrocode} % \end{macro} % |