summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2014-02-06 23:27:03 +0000
committerKarl Berry <karl@freefriends.org>2014-02-06 23:27:03 +0000
commit56864a978f93ea1c29086183c24fb535c4022270 (patch)
tree9d202380e1f31fbe99def3b9f7534e1fe0ab6544 /Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
parent7be84a697eb5391a0974c23fc8dc82413a8c7631 (diff)
rubik (4feb14)
git-svn-id: svn://tug.org/texlive/trunk@32893 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.dtx987
1 files changed, 987 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
new file mode 100644
index 00000000000..8ffc824499a
--- /dev/null
+++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
@@ -0,0 +1,987 @@
+% \iffalse meta-comment
+% rubikrotation.dtx
+%
+% Authors: RWD Nickalls (dick@nickalls.org)
+% and Apostolos Syropoulos (asyropoulos@yahoo.com)
+
+% Copyright 2014 RWD Nickalls + A Syropoulos
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.3c of this license or (at your option) any
+% later version. The latest version of this licence is in
+%
+% http://www.latex-project.org/lppl.txt
+%
+%<*readme>
+%
+% The rubikrotation package provides a collection of LaTeX commands and macros
+% for the typesetting of Rubik cube configurations and rotation
+% sequences using the TikZ graphic language.
+%
+% Please report errors or suggestions for improvement to
+%
+% Dick Nickalls or Apostolos Syropoulos
+%
+% This package requires the basic TikZ package to be loaded already
+%</readme>
+%
+%<*driver>
+\listfiles
+\documentclass{ltxdoc}
+\IfFileExists{rubikrotation.sty}{\usepackage{rubikrotation}}{%
+ \GenericWarning{rubikrotation.dtx}{Package file rubikrotation.sty not found.
+ Documentation will be messed up!^^J
+ (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J
+ process rubikrotation.dtx again)^^J}\stop
+}%
+\usepackage{ifpdf}
+\usepackage{url} %% for references
+\usepackage{graphicx} %% for the two pdf figs
+%%\OnlyDescription
+\EnableCrossrefs
+\CodelineIndex
+\CodelineNumbered
+\RecordChanges
+\setcounter{StandardModuleDepth}{1}
+\begin{document}
+ \DocInput{rubikrotation.dtx}
+ \PrintChanges
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+%
+%
+% \CheckSum{302}
+%
+%%% \CharacterTable
+%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%% Digits \0\1\2\3\4\5\6\7\8\9
+%% Exclamation \! Double quote \" Hash (number) \#
+%% Dollar \$ Percent \% Ampersand \&
+%% Acute accent \' Left paren \( Right paren \)
+%% Asterisk \* Plus \+ Comma \,
+%% Minus \- Point \. Solidus \/
+%% Colon \: Semicolon \; Less than \<
+%% Equals \= Greater than \> Question mark \?
+%% Commercial at \@ Left bracket \[ Backslash \\
+%% Right bracket \] Circumflex \^ Underscore \_
+%% Grave accent \` Left brace \{ Vertical bar \|
+%% Right brace \} Tilde \~}
+%
+%
+%
+% \title{The \textsf{rubikrotation} package}
+%
+% \author{
+% RWD Nickalls (dick@nickalls.org) \\
+% A Syropoulos (asyropoulos@yahoo.com)
+% }
+% \date{This file describes version \RRfileversion, last revised \RRfiledate}
+% \maketitle
+%
+% \begin{abstract}
+% The \rubikrotation\ package is an extension for the
+% \textsf{rubikcube} package. It provides the \cmd{\RubikRotation} command which
+% processes on-the-fly a sequence of Rubik rotation moves (using the Perl script
+% \texttt{rubikrotation.pl}) and returns the new Rubik cube state. It implements
+% some basic checking of the Rubik state, and also offers a command for displaying
+% any errors (\cmd{\ShowRubikErrors}).
+% This package requires access to the \TeX\ \texttt{write18} facility by using the
+% \texttt{--shell-escape} commandline switch.
+% The \textsf{rubikrotation} package has been road-tested on a Microsoft
+% platform (with MikTeX and Strawberry Perl), on a Linux platform ({\TeX}Live and Mandriva),
+% and on OpenIndiana (a Solaris platform).
+% \end{abstract}
+%
+%
+% \bigskip
+%
+% \tableofcontents
+%
+% \section{Introduction}
+%
+% The \rubikrotation\ package is a dynamic extension to the \textsc{rubikcube} package.
+% It consists of a style option (\texttt{rubikrotation.sty}) and a
+% Perl script (\texttt{rubikrotation.pl}).
+%
+% The primary role of the \rubikrotation\ package is to implement on-the-fly Rubik
+% rotation sequences using the \cmd{\RubikRotation} command. Consequently, this
+% package requires the use of the \texttt{--shell-escape} switch to allow
+% commandline control of the Perl script, which is really the `engine' of this package.
+% The \textsf{rubikrotation} package has been road-tested on a Microsoft
+% platform (with 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.})
+% and on a Linux platform ({\TeX}Live and Mandriva).
+%
+% The following commands are made available by \texttt{rubikrotation.sty}.
+% \begin{quote}
+% \begin{verbatim}
+% \RubikRotation{}
+% \SaveRubikState
+% \CheckRubikState
+% \ShowRubikErrors
+%\end{verbatim}
+% \end{quote}
+% Note that if the Perl script is not located in the local working directory, then
+% some care is needed regarding placing it where your system can both find it and
+% also run it. In this case, the setting up of a simple one or two-line configuration
+% file may be useful or even necessary, depending on your system
+% (see section on `installation' below).
+%
+%
+% \section{Requirements}
+%
+% The \rubikrotation\ package requires the TikZ and the \textsc{rubikcube} packages.
+%
+%
+% \section{Installation}
+%
+% \subsection{Generating the files}
+%
+% Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it.
+% This will generate the following files:
+% \begin{verbatim}
+% rubikrotation.ins
+% rubikrotation.dtx
+% rubikrotation.sty
+% rubikrotation.pl
+% rubikrotation.PDF
+% example-rot1.tex
+% example-rot1.PDF
+% example-rot2.tex
+% example-rot2.PDF
+%\end{verbatim}
+% The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on
+% the file \texttt{rubikrotation.ins} as follows:
+%\begin{verbatim}
+% pdflatex rubikrotation.ins
+%\end{verbatim}
+% The documentation file (\texttt{rubikrotation.pdf}) was generated using the following
+% steps:
+% \begin{verbatim}
+% pdflatex --shell-escape rubikrotation.dtx
+% pdflatex --shell-escape rubikrotation.dtx
+% makeindex -s gind.ist rubikrotation
+% makeindex -s gglo.ist -o rubikrotation.gls rubikrotation.glo
+% pdflatex --shell-escape rubikrotation.dtx
+%\end{verbatim}
+%
+
+%
+% \subsection{Placing the files}
+% \label{sec:placingfiles}
+%
+% Place the files either in the local working directory, or where your system
+% will find them. For a Linux system with a standard \TeX\ Directory Structure (TDS), then:
+%
+%\medskip
+%{\noindent}*.sty $\rightarrow$
+% \texttt{/usr/local/texlive/texmf-local/tex/latex/local/rubikrotation/}
+%{\newline}*.cfg $\rightarrow$
+% \texttt{/usr/local/texlive/texmf-local/tex/latex/local/rubikrotation/}
+%{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubikrotation/}
+%{\newline}*.pl $\rightarrow$ \texttt{/usr/local/bin/}
+%
+% \medskip
+% {\noindent}Finally, (depending on your system) update the \TeX\ file database using the
+% \texttt{texhash} command.
+
+%
+% \subsection{Configuration file}
+% \label{sec:configfile}
+%
+% A plane text configuration file with the name \texttt{rubikrotation.cfg} (if one exists)
+% will be read by the system. Such a file allows the user to
+% adjust (a)~the filename of the Perl script (\texttt{rubikrotation.pl})
+% and (b)~the commandline code used by \texttt{rubikrotation.sty} for calling the
+% Perl script. This sort of fine-tuning is sometimes convenient, and even necessary
+% (depending on your system), for locating and running the Perl script.
+% For example, on some systems it maybe preferable to use a different \textsc{path},
+% file name and/or a different commandline code to call the script.
+%
+%
+% \DescribeMacro{\rubikperlname}
+% \DescribeMacro{\rubikperlcmd}
+% The configuration file is essentially a convenient software vehicle for feeding some
+% additional \LaTeX\ code to the style option, and hence allow the contents of some
+% commands to be 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 commandline call,
+% namely \cmd{\rubikperlcmd}.
+% The default definitions for these (detailed in Section~\ref{sec:usefulcommands})
+% are as follows:
+%\begin{verbatim}
+% \newcommand{\rubikperlname}{rubikrotation.pl}
+% \newcommand{\rubikperlcmd}{perl \rubikperlname}
+%\end{verbatim}
+%
+%
+% For example, we might wish to test out a slightly modified Perl script, say
+% with the name \texttt{rubikrotationV3.pl}. In this case we simply create,
+% in the local working directory, a plane text configuration file
+% (called \texttt{rubikrotation.cfg}) which includes the following line:
+%\begin{verbatim}
+%\renewcommand{\rubikperlname}{rubikrotationV3.pl}
+%\end{verbatim}
+%
+% Alternatively, say, if the Perl script is being installed on a Linux platform, then
+% it would be standard to install it in the directory \texttt{/usr/local/bin}.
+% A convenient approach in this case, therefore, would be to indicate this new \textsc{path}
+% by including the following line in the configuration file:
+%\begin{verbatim}
+%\renewcommand{\rubikperlname}{/usr/local/bin/rubikrotation.pl}
+%\end{verbatim}
+% and, since this would then be an essentially permanent feature, we would then
+% place the configuration file with the style option in the
+% \texttt{texmf-local/...} directory as described in section~\ref{sec:placingfiles}
+% (placing files). Note that in this case, we have \textit{not} made the Perl script
+% `executable', since the default commandline code is effectively
+% \texttt{perl \rubikperlname}, and this works just as it is.
+%
+% However, if the Perl script \textit{is} made `executable', then
+% a different commandline code will have to be used instead.
+% For example, suppose the Perl script is made executable and renamed to just
+% \texttt{rubikrotation} (ie with no filename extension), then we now have to
+% omit the `perl' from the default commandline. Consequently, we now need to make
+% two command changes, which we implement by including the following
+% two lines in the configuration file:
+%\begin{verbatim}
+%\renewcommand{\rubikperlname}{/usr/local/bin/rubikrotation}
+%\renewcommand{\rubikperlcmd}{\rubikperlname}
+%\end{verbatim}
+%
+%
+% \section{Usage}
+%
+% Load the packages \texttt{rubikcube.sty}
+% and \texttt{rubikrotation.sty} in the \TeX\ file \textit{after} loading
+% the TikZ package, as follows:
+% \begin{verbatim}
+% \usepackage{tikz}
+% \usepackage{rubikcube,rubikrotation}
+%\end{verbatim}
+% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} commandline switch
+% (see following section).
+%
+%
+% \subsection{Enabling the \TeX\ `shell' facility}
+%
+% In order to enable the \TeX\ `write18' facility (so it can run the Perl script)
+% we will need to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch; say, as follows.
+% \begin{verbatim}
+% pdflatex --shell-escape filename.tex
+%\end{verbatim}
+% In practice, it is probably most convenient to run this via a
+% bash/batch file---something like the following, both of which
+% automatically show the graphic output:
+% \begin{verbatim}
+% pdflatex --shell-escape filename.tex
+% xpdf filename.pdf
+%\end{verbatim}
+% or
+% \begin{verbatim}
+% latex --shell-escape filename.tex
+% dvips filename.dvi
+% gv filename.ps
+%\end{verbatim}
+%
+%
+% \subsection{Test files}
+%
+% Two example tex files (which demonstrate the use of the package commands) are
+% included in the package, namely:
+% \begin{verbatim}
+% example-rot1.tex (shows 5 worked examples)
+% example-rot2.tex (is a `test' file for experimenting with different commands)
+%\end{verbatim}
+% These need to be run using \texttt{--shell-escape} switch; for example:
+% \begin{verbatim}
+% pdflatex --shell-escape example-rot1.tex
+%\end{verbatim}
+% If the files give unexpected results, check-out the log file to see if the system
+% has had any difficulties finding files etc.
+%
+%
+%
+% \section{Commands}
+%
+% The \textit{only} commands which \textit{must} be used inside a TikZ picture
+% environment are the \cmd{\Draw...} commands (these are all provided by
+% the \textsc{rubikcube} package), although most commands can be placed
+% inside a TikZ environment if necessary. However, using commands outside the environment
+% generally offers maximum flexibility, since the effects of commands used inside
+% a TikZ picture environment are `local' to that picture environment, and are not
+% therefore accessable outside the environment.
+%
+% The only command which must \textit{not}
+% be inside a TikZ environment is the \cmd{\ShowRubikErrors} command
+% (see the notes on this command below).
+%
+%
+% \subsection{\cmd{\RubikRotation} command}
+%
+% \DescribeMacro{\RubikRotation}
+% The \cmd{\RubikRotation}\marg{comma separated sequence} command processes
+% a comma separated sequence of rotations, and returns the final state.
+% 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.
+% \begin{verbatim}
+% \begin{tikzpicture}[scale=0.7]
+% \RubikCubeSolved
+% \RubikRotation{R2,L,U,D}
+% \DrawRubikCubeRU
+% \end{tikzpicture}
+%\end{verbatim}
+% 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 program \texttt{rubikrotation.pl}. The Perl
+% program 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 and used to generate
+% some graphic image of the cube.
+%
+% Note that the \cmd{\RubikRotation} command can be either inside
+% or before the Tikz picture environment. In fact only the `\cmd{\Draw...}'
+% commands (from the \textsc{rubikcube} package) actually need to be inside
+% a TikZ picture environment. Consequently this makes for great flexibility.
+%
+% \subsubsection{Arguments prefixed with a *}
+%
+% If any of the comma separated arguments (strings) is prefixed with a * it is
+% not processed as a rotation. This feature therefore allows a string argument
+% to be used as a label, which can be very useful.
+% For example, we can use the * feature to label the following
+% sequence as generating the so-called
+% `sixspot' configuration (described by Reid):
+% \begin{verbatim}
+% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+%\end{verbatim}
+% Alternatively, and probably more conveniently, we could simply use
+% the name `sixspot' to define a new command, as follows (which therefore allows
+% one to store lots of different rotation sequences by name alone):
+% \begin{verbatim}
+% \newcommand{\sixspot}{U,Dp,R,Lp,F,Bp,U,Dp}
+%\end{verbatim}
+% With this `newcommand' we are now able to generate the graphic (sixspot cube)
+% much more easily using the following code:
+%
+% \medskip
+%
+% \begin{minipage}{6cm}
+% \begin{verbatim}
+% \begin{tikzpicture}[scale=0.7]
+% \RubikCubeSolved
+% \RubikRotation{\sixspot}
+% \DrawRubikCubeRU
+% \end{tikzpicture}
+%\end{verbatim}
+% \end{minipage}
+% \begin{minipage}{3.4cm}
+% \centering
+% \ifpdf
+% \includegraphics[height=3cm]{Rubikrot_doc_figA.pdf}
+% \else
+% \fi
+% \end{minipage}
+%
+%
+% \medskip
+%
+% In practice, it is quite useful to go one step further and include
+% the \texttt{*} label feature as well in the newcommand, as follows:
+% \begin{verbatim}
+% \newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+%\end{verbatim}
+% since this has the great advantage of making the particular
+% rotation sequence identified by the label-name visible in the log file.
+% For example, the following command, which uses the rotations \textbf{x2}
+% and \textbf{y} to initially rotate the `solved' cube before applying
+% the `sixspot' sequence of rotations,
+% \begin{verbatim}
+% \RubikRotation{x2,y,\sixspot}
+%\end{verbatim}
+% will then be represented in the log file as
+% \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 Bp U Dp (n= 11)
+% ...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
+%\end{verbatim}
+% In this way, several named rotation sequences can be easily distinguished
+% in the log file from adjacent rotation commands.
+%
+%
+% \subsubsection{Random rotations}
+%
+% The \cmd{\RubikRotation} command can also be used to scramble the
+% cube using a random sequence of rotations. If the first argument
+% is the lowercase 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 value $n=200$ will be used.
+%
+% For example, the following commands will scramble a solved cube using a
+% sequence of 120 random rotations, and display the state in the form of
+% a semi-flat cube.
+%
+% \medskip
+%
+% \begin{minipage}{5.5cm}
+%\begin{verbatim}
+% \RubikCubeSolved%
+% \RubikRotation{random,120}%
+% \begin{tikzpicture}[scale=0.5]
+% \DrawRubikCubeFlat
+% \end{tikzpicture}
+%\end{verbatim}
+% \end{minipage}
+% \begin{minipage}{3.4cm}
+% \centering
+% \ifpdf
+% \includegraphics[height=4cm]{Rubikrot_doc_figB.pdf}
+% \else
+% \fi
+% \end{minipage}
+%
+% Note that in this particular example (above), only
+% the \cmd{\Draw..} command is inside the TikZ picture environment---a useful
+% method when more than one figure is being drawn. Note also, that when such
+% commands are outside a TikZ picture environment, they should have a
+% trailing \% to stop additional white space being included.
+%
+% \medskip
+%
+% The procedure is that all the possible rotations are first allocated
+% a different number (integer) and collected into an array. Then a
+% sequence of $n$ randomised numbers is generated and mapped to the array
+% to generate the associated sequence of random rotations.
+% The sequence used is detailed in the \texttt{.log} file.
+%
+%
+% \subsection{\cmd{\SaveRubikState}}
+%
+% \DescribeMacro{\SaveRubikState}
+% The command \cmd{\SaveRubikState}\marg{filename} saves the state (configuration)
+% of the Rubik cube to the file \marg{filename} in the standard \cmd{\RubikFace...}
+% format. Consequently such a file can then be input at a later stage so it can be
+% drawn or processed in the usual way (inside the TikZ picture environment).
+%
+% For example, the following commands would save the so-called `sixspot' configuration
+% (generated by the rotations \textbf{U, Dp, R, Lp, F, Bp, U, Dp})
+% to the file \verb!sixspot.tex!.
+%\begin{verbatim}
+% \RubikCubeSolved%
+% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}%
+% \SaveRubikState{sixspot.tex}%
+%\end{verbatim}
+% The form of the file \verb!sixspot.tex! will then be as follows---the
+% filename (commented out) is automatically written to the top of the
+% file for convenience.
+%\begin{verbatim}
+% % filename: sixspot.tex
+% \RubikFaceUp{O}{O}{O}{O}{W}{O}{O}{O}{O}%
+% \RubikFaceDown{R}{R}{R}{R}{Y}{R}{R}{R}{R}%
+% \RubikFaceLeft{Y}{Y}{Y}{Y}{B}{Y}{Y}{Y}{Y}%
+% \RubikFaceRight{W}{W}{W}{W}{G}{W}{W}{W}{W}%
+% \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}%
+% \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}%
+%\end{verbatim}
+% We can therefore access and draw this configuration later, when required,
+% simply by inputting the file as follows:
+%\begin{verbatim}
+%\begin{tikzpicture}
+% \input{sixspot.tex}
+% \DrawRubikCubeFlat
+%\end{tikzpicture}
+%\end{verbatim}
+%
+%
+% \subsection{\cmd{\CheckRubikState} command}
+%
+% \DescribeMacro{\CheckRubikState}
+% Since it is easy to inadvertently define an invalid Rubik cube
+% (eg enter an invalid number of, say, yellow cubies), this command
+% checks the current colour state of all the cubies
+% of a 3x3x3 Rubik cube, and shows the number of cubies of each colour.
+% An ERROR: code is issued if the number of cubies 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.
+%
+% One can check the current Rubik state (for errors) by issuing the command
+%\begin{verbatim}
+% \CheckRubikState%
+%\end{verbatim}
+% Note that such a check is implemented automatically with each \cmd{\RubikRotation} command.
+%
+%
+%
+%
+% \subsection{\cmd{\ShowRubikErrors} command}
+%
+% \DescribeMacro{\ShowRubikErrors}
+%
+% Any errors which arise can be made visible using the
+% command \cmd{\ShowRubikErrors}.
+% This command places a copy of the `error' file (\texttt{rubikstateERRORS.dat})
+% underneath the image so you can see any errors if there are any---all this
+% detail can also be found in the \texttt{.log} file.
+%
+% Consequently, this 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 document.
+%
+%
+% \section{Files generated}
+%
+%
+% Whenever the \cmd{\RubikRotation} or \cmd{\CheckRubikState} commands are used,
+% three small temporary plain text files for holding data are generated as
+% follows (they are refreshed with each \LaTeX\ run, and are not actively deleted).
+% \begin{itemize}
+% \item \LaTeX\ writes Rubik state data to the file \texttt{rubikstate.dat}.
+%
+% \item Perl reads the file \texttt{rubikstate.dat} and then writes
+% the new rubik state to the file \texttt{rubikstateNEW.dat}.
+%
+% \item Perl also writes error data to the file \texttt{rubikstateERRORS.dat}.
+% A copy of this file is displayed under the image when the command
+% \cmd{\ShowRubikErrors} is used after (outside) the TikZ picture environment.
+%
+% \end{itemize}
+%
+%
+% \section{General overview}
+%
+% When \LaTeX\ loads the \rubikrotation\ package 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}).
+%
+% \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[4.] The plain text file \texttt{rubikstateERRORS.dat} is created.
+% This file collects error messages generated by the Perl script.
+%
+% \end{itemize}
+%
+%
+% When a \cmd{\RubikRotation} command is processed 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}).
+% 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{U,D,L,R}! then the associated
+% \texttt{rubikstate.dat} file would be as follows:
+% \begin{verbatim}
+% % filename: rubikstate.dat
+% up,W,W,W,W,W,W,W,W,W
+% down,Y,Y,Y,Y,Y,Y,Y,Y,Y
+% left,B,B,B,B,B,B,B,B,B
+% right,G,G,G,G,G,G,G,G,G
+% front,O,O,O,O,O,O,O,O,O
+% back,R,R,R,R,R,R,R,R,R
+% checkstate
+% rotation,U,D,L,R
+%\end{verbatim}
+% Alternatively, if the \cmd{\RubikRotation} command was
+% \verb!\RubikRotation{random, 45}! then the last line written to the file
+% would be the string `\texttt{rotation,random,45}'
+% A \cmd{\CheckRubikState} command triggers the same sequence of events except
+% no `rotation' line is written.
+%
+% The action of the Perl program 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 Perl program starts by loading the
+% rubikstate (prompted by the keywords up, down,
+% left, right, front, back). Next the program performs
+% some basic checks (prompted by the key word `checkstate'), and then it processes
+% the sequence of Rubik rotations (prompted by the keyword `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$, then the Perl program performs
+% a sequence of $n$ random rotations.
+% Finally, the Perl program 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.
+%
+% 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 `\texttt{Draw...}' command
+% of some form is reached 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
+% immediately under the graphic. Once the graphic is error-free, then the
+% \cmd{\ShowRubikErrors} can be removed or commented out.
+%
+%
+%
+% ^^A ==================================================
+% \StopEventually{\PrintIndex}
+%
+%
+%
+% \section{The code (\texttt{rubikrotation.sty})}
+%
+% \subsection{Package heading}
+%
+% \begin{macrocode}
+%<*rubikrotation>
+\def\RRfileversion{2.0}%
+\def\RRfiledate{2014/01/20}%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)]
+% \end{macrocode}
+%
+%
+% {\noindent}The package requires rubikcube.sty. Do not automatically
+% load rubikcube.sty since this makes it difficult to errorcheck new
+% versions (for the moment at least).
+% \begin{macrocode}
+\@ifpackageloaded{rubikcube}{}{%
+ \typeout{---rubikrotation requires the rubikcube package.}%
+ }%
+% \end{macrocode}
+%
+%
+%
+% {\noindent}The \rubikrotation\ package requires access to the fancyvrb package
+% for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying
+% the error file.
+% \begin{macrocode}
+\@ifpackageloaded{fancyvrb}{}{%
+ \typeout{---rubikrotation requires the fancyvrb package%
+ for VerbatimInput{} command.}%
+ \RequirePackage{fancyvrb}}
+% \end{macrocode}
+% \medskip
+%
+%
+%\subsection{Some useful commands}
+% \label{sec:usefulcommands}
+% \begin{macro}{\rubikrotation}
+% First we create a suitable logo
+% \begin{macrocode}
+\newcommand{\rubikrotation}{\textsf{rubikrotation}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\@comment}
+% \begin{macro}{\@commentone}
+% We require access to the percent character so we can write comments
+% in files, including the log file.
+% We first define percentchar for the write statement
+% (From Abrahams PW, Berry K and Hargreaves KA (1990), ``TeX for the Impatient'', p~292;
+% available from: CTAN.../info/impatient/)
+% \begin{macrocode}
+{\catcode`\%=12 \global\def\rubikpercentchar{%}}%
+\newcommand{\@comment}{\rubikpercentchar\rubikpercentchar\space}%
+\newcommand{\@commentone}{\rubikpercentchar}%
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \begin{macro}{\@print}
+%% We need a simple print command for writing comments to a file.
+% \begin{macrocode}
+\newcommand{\@print}[1]{\immediate\write\outfile{#1}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \begin{macro}{\rubikperlname}
+% This holds the name of the Perl-5 script . It is used later to check
+% whether the Perl script exists or not. A plain text configuration file
+% \verb!rubikrotation.cfg! can be used to change the default name of the
+% Perl script using a renewcommand.
+% \begin{macrocode}
+\newcommand{\rubikperlname}{rubikrotation.pl}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \begin{macro}{\rubikperlcmd}
+% This holds the commandline code for calling the the Perl script.
+% A plain text configuration file \verb!rubikrotation.cfg! can be used to
+% change the default commandline code using a renewcommand.
+% \begin{macrocode}
+\newcommand{\rubikperlcmd}{perl \rubikperlname}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%\subsection{Configuration file}
+% If a config file exists (rubikrotation.cfg) then input it here,
+% ie \textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd}
+% commands and \textit{before} creating the \texttt{rubikstateERRORS.dat} file.
+% \begin{macrocode}
+\typeout{---checking for config file (rubikrotation.cfg)...}
+\IfFileExists{rubikrotation.cfg}{%
+ \input{rubikrotation.cfg}%
+ }{\typeout{---no config file available}%
+}%
+% \end{macrocode}
+%
+%
+% \subsection{Clean file rubikstateNEW.dat}
+%
+% {\noindent}We need to clean any existing (old) rubikstateNEW.dat file,
+% since if the TeX shell switch is accidentally not used then Perl will
+% not be CALLed and hence this file will not be renewed
+% (ie an `old' image may be used).
+% \begin{macrocode}
+\typeout{---cleaning file rubikstateNEW.dat}%
+\newwrite\outfile%
+\immediate\openout\outfile=rubikstateNEW.dat%
+\@print{\@comment rubikstateNEW.dat (by TeX)}%
+\immediate\closeout\outfile%
+% \end{macrocode}
+%
+%
+% \subsection{rubikstateERRORS.dat}
+%
+% {\noindent}The \rubikrotation\ package requires the Perl program.
+% We first open the file \texttt{rubikstateERRORS.dat} which is used
+% by the Perl program (\texttt{rubikrotation.pl}) for writing its error
+% messages to. This file is accessed and displayed by the command
+% \cmd{\ShowRubikErrors}.
+%
+% \textsc{important note}: this file is created fresh each time LaTeX is run
+% and hence the Perl program only appends data to it during the \LaTeX\ run,
+% so this file just grows until either it is destroyed or recreated---a useful
+% feature to keep since the file accumulates all error messages as the
+% .tex file is processed.
+% We can't make the Perl program create the file since the Perl program is only
+% CALLed if we use a \cmd{\RubikRotation} or \cmd{\CheckRubikState}
+% command (which we may not!)---so it has to be created (opened) here.
+%
+% The following code first opens the file, and then checks to see if
+% the Perl program (\cmd{\rubikperlname}) exists;
+% if the Perl prog does exist then all is OK,
+% otherwise we write an error message to the file.
+% \begin{macrocode}
+\typeout{---creating file rubikstateERRORS.dat}%
+\newwrite\outfile%
+\immediate\openout\outfile=rubikstateERRORS.dat%
+\@print{\@comment rubikstateERRORS.dat}%
+\typeout{---checking for Perl script \rubikperlname...}
+ \IfFileExists{\rubikperlname}{%
+ \typeout{---\rubikperlname\space exists OK}%
+ }{\typeout{** ERROR: cannot find Perl program \rubikperlname}%
+ \@print{\@comment ** ERROR: cannot find Perl program \rubikperlname}}%
+\immediate\closeout\outfile%
+% \end{macrocode}
+%
+%
+% \subsection{Setting up a newwrite and file-access for new files}
+%
+% Having set up all the primary files, we now need to set up a newwrite for
+% all subsequent files openings (eg for rubikstate.dat and saving
+% to arbitrary filenames by the \cmd{\SaveRubikState} command). Otherwise, we
+% can easily exceed the LaTeX limit of 15. From here-on \TeX\ will use openout7
+% when opening and writing to files. We will implement new openings using
+% the command \verb!\@openstatefile! (see below).
+% \begin{macrocode}
+\typeout{---setting up newwrite for rubikrotation to use...}%
+\newwrite\outfile%
+% \end{macrocode}
+%
+%
+% \begin{macro}{\@openstatefile}
+% \begin{macro}{\@closestatefile}
+% We also need commands for easy file opening and and closing
+% for new instances of the file \texttt{rubikstate.dat} etc.
+% Note that for this we are therefore using the same outfile number as set up
+% by the \verb!\newwrite...! above.
+% \begin{macrocode}
+\newcommand{\@openstatefile}{\immediate\openout\outfile=rubikstate.dat}
+\newcommand{\@closestatefile}{\immediate\closeout\outfile}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+%
+% \subsection{Saving the Rubik state}
+%
+% \begin{macro}{\@printrubikstate}
+% This command writes the Rubik configuration (state) to
+% the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command.
+% The file \texttt{rubikstate.dat} is read by the Perl program, 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 program to implement its \texttt{checkstate} subroutine.
+% \begin{macrocode}
+\newcommand{\@printrubikstate}{%
+ \@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}
+%
+%
+% \subsection{RubikRotation command}
+%
+% \begin{macro}{\RubikRotation}
+% The \cmd{\RubikRotation}\marg{comma separated sequence}
+% command (a)~writes the current Rubik state to the file
+% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl program.
+% It also writes comments to the data file and also to the log file.
+% \begin{macrocode}
+\newcommand{\RubikRotation}[1]{\IfFileExists{\rubikperlname}{%
+ \typeout{---NEW rotation command------------------}%
+ \typeout{---command = RubikRotation{#1}}%
+ \typeout{---Perl script \rubikperlname\space exists OK}%
+ \typeout{---writing current Rubik state to file rubikstate.dat}%
+ \@openstatefile% open data file
+ \@print{\@comment filename: rubikstate.dat}%
+ \@printrubikstate%
+ \@print{rotation,#1}%
+ \@closestatefile% close data file
+ \typeout{---running Perl script}%
+ \immediate\write18{\rubikperlcmd}%
+ \typeout{---inputting NEW datafile (from Perl)}%
+ \input{rubikstateNEW.dat}%
+ \typeout{-----------------------------------------}%
+ }{\typeout{** ERROR: \rubikperlname\space does not exist}%
+}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{ShowRubikErrors command}
+%
+% \begin{macro}{\ShowRubikErrors}
+% This command inputs the file \texttt{rubikstateERRORS.dat}.
+% \begin{macrocode}
+\newcommand{\ShowRubikErrors}{%
+ \typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}%
+ \VerbatimInput{rubikstateERRORS.dat}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+% \subsection{CheckRubikState command}
+%
+% \begin{macro}{\CheckRubikState}
+% This command triggers the Perl program 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 program.
+% It also writes comments to the data file and also to the log file..
+% \begin{macrocode}
+\newcommand{\CheckRubikState}{\IfFileExists{\rubikperlname}{%
+ \typeout{---NEW check command------------------}%
+ \typeout{---command = CheckRubikState}%
+ \typeout{---Perl script \rubikperlname\space exists OK}%
+ \typeout{---writing current Rubik state to file rubikstate.dat}%
+ \@openstatefile% opens data file
+ \@print{\@comment filename: rubikstate.dat}%
+ \@printrubikstate%
+ \@closestatefile% close data file
+ \typeout{---running Perl script}%
+ \immediate\write18{\rubikperlcmd}%
+ \typeout{---inputting NEW datafile (from Perl)}%
+ \input{rubikstateNEW.dat}%
+ \typeout{-----------------------------------------}%
+ }{\typeout{** ERROR: \rubikperlname\space does not exist}%
+}}
+% \end{macrocode}
+% \end{macro}
+%
+%
+%
+% \subsection{SaveRubikState macro}
+%
+% \begin{macro}{\SaveRubikState}
+% The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state
+% to a file. Note that in order to actually write a LaTeX
+% command to a file without a trailing space one must use the
+% \cmd{\string} command (see the book ``TeX by Topic'', p~238).
+% Note that this macro uses the two internal commands \cmd{\Rubik@comment}
+% and \cmd{\Rubik@print}. \#1 is the output filename.
+% We use several \cmd{\typeout} commands to write to the log file.
+% \begin{macrocode}
+\newcommand{\SaveRubikState}[1]{%
+\typeout{---NEW save command------------------}%
+\typeout{---command = SaveRubikState{#1}}%
+\typeout{---saving Rubik state data to file #1}%
+\immediate\openout\outfile=#1%
+\@print{\@comment filename: #1\@commentone}%
+\@print{\string\RubikFaceUp%
+ {\Ult}{\Umt}{\Urt}{\Ulm}{\Umm}{\Urm}{\Ulb}{\Umb}{\Urb}\@commentone}%
+\@print{\string\RubikFaceDown%
+ {\Dlt}{\Dmt}{\Drt}{\Dlm}{\Dmm}{\Drm}{\Dlb}{\Dmb}{\Drb}\@commentone}%
+\@print{\string\RubikFaceLeft%
+ {\Llt}{\Lmt}{\Lrt}{\Llm}{\Lmm}{\Lrm}{\Llb}{\Lmb}{\Lrb}\@commentone}%
+\@print{\string\RubikFaceRight%
+ {\Rlt}{\Rmt}{\Rrt}{\Rlm}{\Rmm}{\Rrm}{\Rlb}{\Rmb}{\Rrb}\@commentone}%
+\@print{\string\RubikFaceFront%
+ {\Flt}{\Fmt}{\Frt}{\Flm}{\Fmm}{\Frm}{\Flb}{\Fmb}{\Frb}\@commentone}%
+\@print{\string\RubikFaceBack%
+ {\Blt}{\Bmt}{\Brt}{\Blm}{\Bmm}{\Brm}{\Blb}{\Bmb}{\Brb}\@commentone}%
+\immediate\closeout\outfile%
+\typeout{-----------------------------------------}%
+}%
+% \end{macrocode}
+% \end{macro}
+%
+%
+% --------------------------
+% End of this package
+% --------------------------
+% \begin{macrocode}
+%</rubikrotation>
+% \end{macrocode}
+%
+%
+%
+%
+% \Finale
+%
+\endinput
+
+
+
+
+