rubik (4feb14)

git-svn-id: svn://tug.org/texlive/trunk@32893 c570f23f-e606-0410-a88d-b1316a301751

18 files changed, 611 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/rubik/README b/Master/texmf-dist/doc/latex/rubik/README
new file mode 100644
index 00000000000..29121a01cec
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/README
@@ -0,0 +1,70 @@
+
+February 3, 2014
+--------------------------------------------------------------------------
+the RUBIK bundle 2014/02/03
+ - rubikcube package v2.0      -> macros and commands for typesetting
+ - rubikrotation package v2.0  -> macros and Perl program for rotations
+--------------------------------------------------------------------------
+
+The RUBIK bundle provides two complementary packages for documenting the
+Rubik cube (3x3x3) notation, configurations and rotation sequences.
+The two packages are (a) rubikcube package, and (b) rubikrotation package.
+
+(a) Rubikcube package
+
+ The  rubikcube  package   provides  a collection of LaTeX commands 
+ and macros for  typesetting  Rubik cube  configurations  and rotation 
+ instructions using the  PGF/TikZ graphic languages.
+ This is a stand-alone LaTeX package. However, it's scope is greatly enhanced
+ by the rubikrotation package.
+
+(b) Rubikrotation package
+
+ The rubikrotation package, is a dynamic extension to
+ the rubikcube package. It consists of  the  Perl program  
+ rubikrotation.pl  and style option rubikrotation.sty.
+ The rubikrotation package  implements rotation sequences and 
+ random  scrambling of the Rubik cube on-the-fly using a
+ \RubikRotation command. It returns the new state in a form 
+ which is then used for typesetting by the rubikcube package.
+
+ Since the  \RubikRotation command works by CALLing the  
+ Perl program rubikrotation.pl, it follows that the rubikrotation
+ package requires (a)~Perl to be installed, and (b) LaTeX needs to 
+ be run using the --shell-escape commandline option.
+
+--------------------------------------------------------------------------
+RWD Nickalls    email: dick@nickalls.org
+A Syropoulos    email: 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.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+  http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+--------------------------------------------------------------------------
+The RUBIK bundle consists of the following files
+package files:
+ - rubikcube.ins
+ - rubikcube.dtx
+ - rubikrotation.ins,
+ - rubikrotation.dtx,
+ - rubikrotation.pl  (Perl program)
+image files:
+ - pdf -files for the documentation (6 pictures)
+documentation, examples and README:
+ - rubikcube.pdf
+ - rubikrotation.pdf,
+ - example-cube.pdf, example-cube.tex
+ - example-rot1.pdf, example-rot1.tex
+ - example-rot2.pdf, example-rot2.pdf
+ - README (this file)
+--------------------------------------------------------------------------
+If you have any ideas, questions, suggestions or bugs to report, please
+feel free to contact us.
+--------------------------------------------------------------------------
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figA.pdf b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figA.pdf
new file mode 100644
index 00000000000..63be7621483
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figA.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figB.pdf b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figB.pdf
new file mode 100644
index 00000000000..5bdd92967c5
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figB.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figC.pdf b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figC.pdf
new file mode 100644
index 00000000000..53dc10e8395
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figC.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figD.pdf b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figD.pdf
new file mode 100644
index 00000000000..1304c069452
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figD.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figE.pdf b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figE.pdf
new file mode 100644
index 00000000000..5d013ff25a6
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubik_doc_figE.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubikrot_doc_figA.pdf b/Master/texmf-dist/doc/latex/rubik/Rubikrot_doc_figA.pdf
new file mode 100644
index 00000000000..9154ba3075c
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubikrot_doc_figA.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/Rubikrot_doc_figB.pdf b/Master/texmf-dist/doc/latex/rubik/Rubikrot_doc_figB.pdf
new file mode 100644
index 00000000000..7478436a27f
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/Rubikrot_doc_figB.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/example-cube.pdf b/Master/texmf-dist/doc/latex/rubik/example-cube.pdf
new file mode 100644
index 00000000000..39d91a7b135
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-cube.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/example-cube.tex b/Master/texmf-dist/doc/latex/rubik/example-cube.tex
new file mode 100644
index 00000000000..e923c805c9a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-cube.tex
@@ -0,0 +1,188 @@
+%%
+%% example-cube.tex
+%% package example using the rubikcube package
+%% Requires the tikz package
+%% January 20, 2014
+%%--------NOTE-------------------------------------------
+%% USAGE:   (pdf)latex    example-cube.tex
+%%-------------------------------------------------------
+\documentclass[a4paper]{article}
+\usepackage{tikz}   %% load tikz before rubikcube
+\usepackage{rubikcube} 
+\usepackage{url}
+\pagestyle{myheadings}
+\markright{\textsc{rubikcube} package; \hspace{2cm}file = example-cube.tex}
+%% increase textwidth to make room 
+\addtolength{\oddsidemargin}{-1.5cm}
+\addtolength{\textwidth}{3cm}
+%% brace and bracket 
+\newcommand{\Rubikbracket}[1]{$\left(\mbox{#1}\right)$}
+\newcommand{\Rubikbrace}[1]{$\left\{\mbox{#1}\right\}$}
+%%
+\begin{document}
+%%-------------------------
+\subsection*{Example---the `superflip' configuration}
+
+Once you have mastered Rubik's cube, then an interesting exercise is to generate 
+the so-called `superflip' configuration, in which all the corners are correctly 
+solved, while all the edges are flipped.
+
+For the impatient,  the  superflip sequence of 24  quarter-turn rotations (listed on Randelshofer's website) is as follows. This  converts the solved cube on the left into the configuration shown on the right.
+
+\bigskip
+
+\begin{center}
+\RubikU\RubikR\RubikR\RubikFp\RubikR\RubikDp\RubikL\RubikBp\RubikR%
+\RubikUp\RubikR\RubikUp\RubikD\RubikFp\RubikU\RubikFp\RubikUp\RubikDp%
+\RubikB\RubikLp\RubikFp\RubikBp\RubikDp\RubikLp
+\end{center}
+
+\medskip
+
+{\noindent}Surprisingly,  this sequence is actually equivalent to
+\Rubikbrace{\Rubikbracket{\RubikM\RubikUp}4, \Rubiky, \Rubikxp}3
+
+
+\bigskip
+\begin{figure}[hbt]
+\centering
+\RubikCubeSolved%
+\begin{minipage}{2cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeRU
+  \end{tikzpicture}
+\end{minipage}
+\hspace{5mm}$\Longrightarrow$\hspace{5mm}%
+\RubikFaceUp   {W}{R}{W} {B}{W}{G} {W}{O}{W}%
+\RubikFaceDown {Y}{O}{Y} {B}{Y}{G} {Y}{R}{Y}%
+\RubikFaceLeft {B}{W}{B} {R}{B}{O} {B}{Y}{B}%
+\RubikFaceRight{G}{W}{G} {O}{G}{R} {G}{Y}{G}%
+\RubikFaceFront{O}{W}{O} {B}{O}{G} {O}{Y}{O}%
+\RubikFaceBack{R}{W}{R}
+              {G}{R}{B}
+              {R}{Y}{R}%
+\begin{minipage}{2cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeRU
+  \end{tikzpicture}
+\end{minipage}
+\hspace{1cm}%
+\begin{minipage}{5cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeFlat
+  \end{tikzpicture}
+\end{minipage}
+\caption{Two images of the superflip configuration.}
+\end{figure}
+
+The code for all this is given below---note that the facelet colours can be 
+written in various ways. Note also the trailing \% at the end of each line which is not inside  a TikZ picture environment, and the value of placing each TikZ picture environment inside a minipage.
+Since the default width of a Rubik cube is 4cm (see \S\,7 Fig~2 in \texttt{rubikcube.pdf}), then since the TikZ scale here is 0.5 then the required  width of its minipage is equal to $0.5 \times 4\mbox{cm} = 2\mbox{cm}$.
+%%----------
+\begin{verbatim}
+-------------------
+\newcommand{\Rubikbracket}[1]{$\left(\mbox{#1}\right)$}
+\newcommand{\Rubikbrace}[1]{$\left\{\mbox{#1}\right\}$}
+
+\begin{center}
+\RubikU\RubikR\RubikR\RubikFp\RubikR\RubikDp\RubikL\RubikBp\RubikR%
+\RubikUp\RubikR\RubikUp\RubikD\RubikFp\RubikU\RubikFp\RubikUp\RubikDp%
+\RubikB\RubikLp\RubikFp\RubikBp\RubikDp\RubikLp
+\end{center}
+
+\medskip
+
+{\noindent}Surprisingly,  this sequence is actually equivalent to
+\Rubikbrace{\Rubikbracket{\RubikM\RubikUp}4, \Rubiky, \Rubikxp}3
+
+\bigskip 
+
+\begin{figure}[hbt]
+\centering
+\RubikCubeSolved
+\begin{minipage}{2cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeRU
+  \end{tikzpicture}
+\end{minipage}
+\hspace{5mm}$\Longrightarrow$\hspace{5mm}%
+\RubikFaceUp   {Y}{B}{Y} {R}{Y}{O} {Y}{G}{Y}%
+\RubikFaceDown {W}{G}{W} {R}{W}{O} {W}{B}{W}%
+\RubikFaceLeft {R}{Y}{R} {B}{R}{G} {R}{W}{R}%
+\RubikFaceRight{O}{Y}{O} {G}{O}{B} {O}{W}{O}%
+\RubikFaceFront{G}{Y}{G} {R}{G}{O} {G}{W}{G}%
+\RubikFaceBack {B}{Y}{B}%
+               {O}{B}{R}%
+               {B}{W}{B}%
+\begin{minipage}{2cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeRU
+  \end{tikzpicture}
+\end{minipage}
+\hspace{1cm}%
+\begin{minipage}{5cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeFlat
+  \end{tikzpicture}
+\end{minipage}
+\caption{Two images of the superflip configuration.}
+\end{figure}
+-------------------
+\end{verbatim}
+
+
+\subsection*{Using the rubikrotation package}
+
+This is just a note to show that if this file were run in conjunction with the \texttt{rubikrotation} package, using the \LaTeX\ commandline switch  \texttt{--shell-escape}, then the above figure could be generated more simply by replacing
+\begin{verbatim}
+\RubikFaceUp   {Y}{B}{Y} {R}{Y}{O} {Y}{G}{Y}%
+\RubikFaceDown {W}{G}{W} {R}{W}{O} {W}{B}{W}%
+\RubikFaceLeft {R}{Y}{R} {B}{R}{G} {R}{W}{R}%
+\RubikFaceRight{O}{Y}{O} {G}{O}{B} {O}{W}{O}%
+\RubikFaceFront{G}{Y}{G} {R}{G}{O} {G}{W}{G}%
+\RubikFaceBack {B}{Y}{B}%
+               {O}{B}{R}%
+               {B}{W}{B}%
+\end{verbatim}
+with the command
+\begin{verbatim}
+\RubikRotation{\superflip}%
+\end{verbatim}
+ie,~using instead the following code:
+\begin{verbatim}
+-----------------
+\newcommand{\superflip}{U,R2,Fp,R,Dp,L,Bp,R,Up,R,Up,D,%
+Fp,U,Fp,Up,Dp,B,Lp,Fp,Bp,Dp,Lp}
+
+\begin{figure}[hbt]
+\centering
+\RubikCubeSolved%
+\begin{minipage}{2cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeRU
+  \end{tikzpicture}
+\end{minipage}
+\hspace{5mm}$\Longrightarrow$\hspace{5mm}%
+\RubikRotation{\superflip}%
+\begin{minipage}{2cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeRU
+  \end{tikzpicture}
+\end{minipage}
+\hspace{1cm}%
+\begin{minipage}{5cm}
+  \begin{tikzpicture}[scale=0.5]
+  \DrawRubikCubeFlat
+  \end{tikzpicture}
+\end{minipage}
+\caption{Two images of the superflip configuration.}
+\end{figure}
+-----------------
+\end{verbatim}
+
+
+\begin{center}
+------ END ------
+\end{center}
+
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/rubik/example-rot1.pdf b/Master/texmf-dist/doc/latex/rubik/example-rot1.pdf
new file mode 100644
index 00000000000..d18a90284e8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-rot1.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/example-rot1.sh b/Master/texmf-dist/doc/latex/rubik/example-rot1.sh
new file mode 100755
index 00000000000..b45c859559e
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-rot1.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/bash 
+pdflatex  --shell-escape  example-rot1.tex
+pdflatex  --shell-escape  example-rot1.tex
diff --git a/Master/texmf-dist/doc/latex/rubik/example-rot1.tex b/Master/texmf-dist/doc/latex/rubik/example-rot1.tex
new file mode 100644
index 00000000000..5f424bc6132
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-rot1.tex
@@ -0,0 +1,307 @@
+%%
+%% example-rot1.tex
+%% package examples using the rubikrotation package
+%% Requires  tikz and rubikcube packages
+%% January 20, 2014
+%%--------NOTE-------------------------------------------
+%% USAGE:   (pdf)latex  --shell-escape   example-rot1.tex
+%% run three times to get all labels and fig nos correct
+%%-------------------------------------------------------
+\documentclass[a4paper]{article}
+\usepackage{tikz}   %% load tikz before rubikcube
+\usepackage{rubikcube,rubikrotation} 
+\usepackage{url}
+\pagestyle{myheadings}
+\markright{\textsc{rubikrotation} package; \hspace{2cm}file = example-rot1.tex}
+%-----------
+%% some well known sequences (see the web page of Reid)
+\newcommand{\sixTs}{*sixTs,F2,R2,U2,Fp,B,D2,L2,F,B}
+\newcommand{\CubeInCube}{*CubeInCube,F,L,F,Up,R,U,F2,L2,Up,Lp,B,Dp,Bp,L2,U}
+\newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+%%==================
+\begin{document}
+
+%%------------------
+\section*{Example~1}
+
+In Figure~\ref{fig:cubeincube} we show  the so-called ``sixspot'' configuration,
+ generated from a solved cube using the rotation sequence 
+\rrU, \rrDp, \rrR, \rrLp, \rrF, \rrBp, \rrU, \rrDp
+(see the website of Reid at \url{www.math.ucf.edu/~reid/Rubik/}).
+%%--------FIGURE 1 -----------
+\begin{figure}[hbt]
+\centering
+\begin{tikzpicture}[scale=0.7]
+   \RubikCubeSolved
+   \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+   \DrawRubikCubeFlat
+\end{tikzpicture}
+\caption{\label{fig:cubeincube}The  so-called `sixspot' configuration (Reid).}
+\end{figure}
+%----------------
+\begin{verbatim}
+----------------
+\documentclass[a4paper]{article}
+\usepackage{tikz,rubikcube,rubikrotation}
+\thispagestyle{empty} %% disables pagenumbers
+\begin{document}
+\begin{tikzpicture}[scale=0.9]
+    \RubikCubeSolved
+    \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+    \DrawRubikCubeFlat
+\end{tikzpicture}
+\end{document}
+--------------
+\end{verbatim}
+Note that a more flexible approach is to   incorporate such  rotation sequences into a `newcommand'. For example, in this case we can write
+\begin{verbatim}
+\newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+\end{verbatim}
+which allows the code to Figure~\ref{fig:cubeincube} to be more easily written as:
+\begin{verbatim}
+\begin{tikzpicture}
+    \RubikCubeSolved
+    \RubikRotation{\sixspot}
+    \DrawRubikCubeFlat
+\end{tikzpicture}
+\end{verbatim}
+
+
+
+\pagebreak
+%%-------------------------
+\section*{Example~2}
+
+ In this example we show  the use of the  \verb!\ShowRubikErrors! command, which
+ places a copy of the Perl output file (\verb!rubikstateERRORS.dat!) underneath the graphic 
+ so you can see a list of all the  errors, if any (in this example we have introduced a couple
+ of errors).  It is important to note that  the  \verb!\ShowRubikErrors! command must be 
+ placed \textit{after}  the TikZ picture environment. Note also  that full details of all 
+ errors are included in the .log file. 
+
+%%--------FIGURE 2 -----------
+
+\RubikCubeSolved
+\RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,UU,Dpp}
+
+\begin{figure}[hbt]
+\centering
+\begin{tikzpicture}[scale=0.7]
+   \DrawRubikCubeFlat
+\end{tikzpicture}
+\ShowRubikErrors
+\caption{\label{fig:cubeincubeE}The same `sixspot' sequence of rotations as before, but now with some typo errors in the rotation sequence (should be \texttt{U,Dp,R,Lp,F,Bp,U,Dp}.}
+\end{figure}
+Note that only `Draw' commands really need to be inside the TikZ picture environment---see the following code which we used for the above figure.
+%-----------------
+\begin{verbatim}
+----------------
+\RubikCubeSolved
+\RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,UU,Dpp}
+%
+\begin{tikzpicture}
+   \DrawRubikCubeFlat
+\end{tikzpicture}
+\ShowRubikErrors
+----------------
+\end{verbatim}
+
+
+
+
+\pagebreak
+%-------------------------------
+\section*{Example~3}
+
+In this example we use the \verb!\RubikRotation! command to scramble a `solved' Rubik 
+cube via  a sequence of 120 random rotations, using the following  command (the details 
+of the process can be seen in the \texttt{.log} file):
+\begin{verbatim}
+\RubikRotation{random,120}
+\end{verbatim}
+In this example, we also save the final  configuration (state) to a file 
+(\texttt{exmpfig4.tex}) using the command
+\verb!\SaveRubikState{exmpfig4.tex}!
+so we can  display the cube in the same state later (see Example~4) but 
+in  a different format.
+Note that since we are using a random sequence, it follows that each 
+time this file is run not only will a visually different  cube  be generated,  
+but the same state  will be shown in both Figures~\ref{fig:randomone} and \ref{fig:randomtwo}.
+%%--------FIGURE 3 -----------
+\begin{figure}[hbt]
+\centering
+\begin{tikzpicture}[scale=0.7]
+   \RubikCubeSolved
+   \RubikRotation{random,120}
+   \SaveRubikState{exmpfig4.tex}
+   \DrawRubikFlat
+\end{tikzpicture}
+\caption{\label{fig:randomone}This shows a cube  generated by 120 random rotations}
+\end{figure}
+%----------------
+\begin{verbatim}
+-------------------
+\begin{figure}[hbt]
+\centering
+\begin{tikzpicture}[scale=0.8]
+    \RubikCubeSolved
+    \RubikRotation{random,120}
+    \SaveRubikState{exmpfig4.tex}
+    \DrawRubikFlat
+\end{tikzpicture}
+\end{figure}
+------------------
+\end{verbatim}
+
+
+
+\pagebreak
+%----------------------
+\section*{Example~4}
+
+In this example we display a cube having the same state as that shown in 
+Figure~\ref{fig:randomone}. The configuration state was saved from 
+Figure~\ref{fig:randomone} using the  command 
+\verb!\SaveRubikState{exmpfig4.tex}!, and then input here  
+using \verb!\input{exmpfig4.tex}!. These commands therefore allow  the 
+state of a previous cube to be saved to a file, and then  displayed again 
+later in  a different format.
+%%-----------FIGURE 4 -----------
+\begin{figure}[hbt]
+\centering
+\begin{tikzpicture}[scale=0.8]
+   \input{exmpfig4.tex}
+   \DrawRubikCubeLD
+\end{tikzpicture}
+\caption{\label{fig:randomtwo}This shows a Rubik cube in exactly the  same 
+state as  the one shown in Figure~\ref{fig:randomone}} 
+\end{figure}
+%%---------------------------------
+\begin{verbatim}
+-------------------
+\begin{figure}[hbt]
+\centering
+\begin{tikzpicture}[scale=0.8]
+   \input{exmpfig4.tex}
+   \DrawRubikCubeLD
+\end{tikzpicture}
+\end{figure}
+------------------
+\end{verbatim}
+
+
+
+\pagebreak
+%----------------------
+\section*{Example~5}
+
+Here we show a convenient way of displaying a series of small cubes showing 
+a sequence of rotations (\rrU, \rrR, \rrF). Following each rotation 
+we save the state to a file and then, finally, display each cube state in sequence,
+using a  couple of useful macros (\verb!\showcube!, and \verb!\lift!),
+to `show' the cubes and  to `lift' the  rotation command slightly off the baseline.
+Note that embedding the TikZ picture environment in the  \verb!\showcube! command brings 
+considerable flexibility. 
+%%-----------FIGURE 5 -----------
+\newcommand{\showcube}[1]{%
+   \begin{tikzpicture}[scale=0.5]
+   \input{#1}
+   \DrawRubikCubeRU
+   \end{tikzpicture}
+}
+\newcommand{\lift}[1]{\raisebox{8mm}{#1}\hspace{2mm}}
+%%
+\RubikCubeSolved  \SaveRubikState{exmpfig5a.tex}
+\RubikRotation{U} \SaveRubikState{exmpfig5b.tex}
+\RubikRotation{R} \SaveRubikState{exmpfig5c.tex}
+\RubikRotation{F} \SaveRubikState{exmpfig5d.tex}
+%%
+\begin{figure}[hbt]
+\centering
+\noindent     \showcube{exmpfig5a.tex}\hspace{-4mm}(a) 
+\lift{\RubikU}\showcube{exmpfig5b.tex}\hspace{-4mm}(b) 
+\lift{\RubikR}\showcube{exmpfig5c.tex}\hspace{-4mm}(c) 
+\lift{\RubikF}\showcube{exmpfig5d.tex}\hspace{-4mm}(d) 
+\caption{The rotations \rrU, \rrR, \rrF\ on a solved cube.} 
+\end{figure}
+%%---------------------------------
+
+Note that even though the \verb!\RubikCubeSolved! command (which allocates the 
+ colours to the `solved' cube) is used  prior to  the TikZ picture environment, 
+ its effects are still available to the \verb!\Draw...! command inside each of  the 
+picture environments.
+\begin{verbatim}
+-------------------
+\newcommand{\showcube}[1]{%
+   \begin{tikzpicture}[scale=0.5]
+   \input{#1}
+   \DrawRubikCubeRU
+   \end{tikzpicture}
+}
+\newcommand{\lift}[1]{\raisebox{8mm}{#1}\hspace{2mm}}
+%%
+\RubikCubeSolved  \SaveRubikState{exmpfig5a.tex}
+\RubikRotation{U} \SaveRubikState{exmpfig5b.tex}
+\RubikRotation{R} \SaveRubikState{exmpfig5c.tex}
+\RubikRotation{F} \SaveRubikState{exmpfig5d.tex}
+%%
+\begin{figure}[hbt]
+   \centering
+   \noindent     \showcube{exmpfig5a.tex}\hspace{-4mm}(a)  
+   \lift{\RubikU}\showcube{exmpfig5b.tex}\hspace{-4mm}(b)  
+   \lift{\RubikR}\showcube{exmpfig5c.tex}\hspace{-4mm}(c) 
+   \lift{\RubikF}\showcube{exmpfig5d.tex}\hspace{-4mm}(d) 
+   \ShowRubikErrors
+\caption{The rotations \rrU, \rrR, \rrF\ on a solved cube.} 
+\end{figure}
+------------------
+\end{verbatim}
+
+\pagebreak
+%----------------------
+\section*{Example~6}
+
+In this example we show how commands used inside a TikZ picture environment remain 
+local to that picture environment.
+
+In this case the first fig uses the \verb!\RubikCubeSolved! inside the TikZ environment.
+However, if we then perform the rotation  \textRubikR\  the command \verb!RubikRotation{R}! 
+results in  something quite unexpected (and obviously not correct). This is because 
+ the effect of the \verb!\RubikCubeSolved! command is not visible outside its TikZ environment, and hence the  \verb!RubikRotation{R}! command has to  operate on the state of the next earliest figure 
+(ie~Figure~5d), hence the strange form of the second figure below.
+
+\medskip
+
+   \begin{tikzpicture}[scale=0.5]
+   \RubikCubeSolved
+   \DrawRubikCubeRU
+   \end{tikzpicture}
+\hspace{5mm}\lift{\RubikR}\hspace{5mm}%
+\RubikRotation{R}%
+  \begin{tikzpicture}[scale=0.5]
+   \DrawRubikCubeRU
+   \end{tikzpicture}
+
+\medskip
+
+Since we are not here using any `minipage' environments, we need to use the \verb!\lift{}! command to raise the \rrhR\ hieroglyph off the baseline.
+
+\begin{verbatim}
+-------------------
+\begin{tikzpicture}[scale=0.5]
+   \RubikCubeSolved
+   \DrawRubikCubeRU
+\end{tikzpicture}
+\hspace{5mm}\lift{\RubikR}\hspace{5mm}%
+\RubikRotation{R}%
+\begin{tikzpicture}[scale=0.5]
+   \DrawRubikCubeRU
+\end{tikzpicture}
+-------------------
+\end{verbatim}
+
+\begin{center}
+------ END ------
+\end{center}
+
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/rubik/example-rot2.pdf b/Master/texmf-dist/doc/latex/rubik/example-rot2.pdf
new file mode 100644
index 00000000000..351ecf86d73
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-rot2.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/example-rot2.sh b/Master/texmf-dist/doc/latex/rubik/example-rot2.sh
new file mode 100644
index 00000000000..f44d9331a8b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-rot2.sh
@@ -0,0 +1 @@
+pdflatex  --shell-escape  example-rot2.tex
diff --git a/Master/texmf-dist/doc/latex/rubik/example-rot2.tex b/Master/texmf-dist/doc/latex/rubik/example-rot2.tex
new file mode 100644
index 00000000000..688717ffcab
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/example-rot2.tex
@@ -0,0 +1,42 @@
+%% example-rot2.tex
+%% January 20, 2014
+%% RWD Nickalls & A Syropoulos 
+%% example file for rubikrotation package
+%% Requires TikZ and rubikcube, and rubikrotation packages
+%% uses Perl script rubikrotation.pl
+%% experiment  by un-commenting  different RubikRotation commands,
+%%   and reviewing the .log file for details of rotations performed. 
+%%-----------------------------------------------------
+%% USAGE:  pdflatex  --shell-escape  example-rot2.tex
+%% ----------------------------------------------------
+\documentclass[a4paper]{article}
+\usepackage{tikz,rubikcube,rubikrotation}
+\pagestyle{myheadings}
+\markright{\textsc{rubikrotation} package; \hspace{2cm}file = example-rot2.tex}
+%%--------------
+%% some well known sequences (see the web page of Reid)
+\newcommand{\sixT}{*sixT,F2,R2,U2,Fp,B,D2,L2,F,B}
+\newcommand{\cubeincube}{*cubeincube,F,L,F,Up,R,U,F2,L2,Up,Lp,B,Dp,Bp,L2,U}
+\newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}
+\newcommand{\errors}{*errors,U,Dp,RR,Lpp,Fq,Bp,U,Dp,cat}
+%================
+\begin{document}
+
+\RubikCubeSolved  % sets up a solved cube
+%----------------
+%\RubikRotation{R,FFF}         %%this will show up the command FFF as being an error
+%\RubikRotation{U,D,L,R,F,B}   %% some basic rotations in sequence
+%\RubikRotation{U2,D2,L2,R2,F2,B2}  %% makes an interesting pattern
+%\RubikRotation{\sixT}         %% generates a T on each face
+%\RubikRotation{\cubeincube}   %% generates a cube-in-cube effect
+%\RubikRotation{random,67}     %%  makes 67 random rotations
+\RubikRotation{x,y,\sixspot}   %% shows a sixspot effect
+%\RubikRotation{\errors}     %% sixspot with errors (errors will be shown if using \ShowRobotErrors)
+
+\begin{tikzpicture}
+   \DrawRubikCubeFlat      %% shows cube as half cube half flat
+   %\DrawRubikFlat         %% shows cube as a flat representation
+\end{tikzpicture}
+%%--------------
+\ShowRubikErrors   %% will show error file underneath the image
+\end{document}
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/latex/rubik/rubikcube.pdf b/Master/texmf-dist/doc/latex/rubik/rubikcube.pdf
new file mode 100644
index 00000000000..5cffa577720
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/rubikcube.pdf
diff --git a/Master/texmf-dist/doc/latex/rubik/rubikrotation.pdf b/Master/texmf-dist/doc/latex/rubik/rubikrotation.pdf
new file mode 100644
index 00000000000..207abac2ea7
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/rubik/rubikrotation.pdf