summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/latex/rubik/rubikrotation.dtx')
-rw-r--r--Master/texmf-dist/source/latex/rubik/rubikrotation.dtx396
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}
%