diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/rubik/rubikrotation.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/rubik/rubikrotation.dtx | 1177 |
1 files changed, 780 insertions, 397 deletions
diff --git a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx index 8ffc824499a..57302ac37a7 100644 --- a/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx +++ b/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx @@ -1,10 +1,12 @@ % \iffalse meta-comment % rubikrotation.dtx % +% version 3.0 +% % Authors: RWD Nickalls (dick@nickalls.org) % and Apostolos Syropoulos (asyropoulos@yahoo.com) -% Copyright 2014 RWD Nickalls + A Syropoulos +% Copyright 25 September 2015 RWD Nickalls + A Syropoulos % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either @@ -36,10 +38,12 @@ process rubikrotation.dtx again)^^J}\stop }% \usepackage{ifpdf} -\usepackage{url} %% for references -\usepackage{graphicx} %% for the two pdf figs +\usepackage{url,path} %% for references and paths +\usepackage{graphicx} %% for the two pdf figs +\usepackage{hypdoc} %% for pdf bookmarks + hyperref documenting of packages %%\OnlyDescription \EnableCrossrefs +\PageIndex \CodelineIndex \CodelineNumbered \RecordChanges @@ -54,7 +58,7 @@ % % % -% \CheckSum{302} +% \CheckSum{310} % %%% \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 @@ -74,65 +78,72 @@ % % % -% \title{The \textsf{rubikrotation} package} +% \title{The \rubikrotation\ package} % % \author{ % RWD Nickalls (dick@nickalls.org) \\ % A Syropoulos (asyropoulos@yahoo.com) % } -% \date{This file describes version \RRfileversion, last revised \RRfiledate} +% \date{This file describes version \RRfileversion\ (\RRfiledate)\\ +% \texttt{www.ctan.org/pkg/rubik}} % \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). +% The \rubikrotation\ package is a dynamic extension for the +% \textsc{rubikcube} package (both are part of the Rubik `bundle'). +% The package provides the \cmd{\RubikRotation} command which +% processes a sequence of Rubik rotation moves on-the-fly (using the Perl script +% \texttt{rubikrotation.pl}), and returns the new Rubik cube state (configuration). +% The \rubikrotation\ package also provides a command for implementing some basic +% checking of the Rubik cube state (\cmd{\CheckRubikState}), and one +% for displaying any errors (\cmd{\ShowRubikErrors}). +% +% The \rubikrotation\ package requires access to the \TeX\ \texttt{write18} +% facility, which is enabled by using the \texttt{--shell-escape} command-line switch. +% The~\rubikrotation\ package has been road-tested on a Microsoft +% platform (with MiKTeX and Strawberry Perl), on a Linux platform +% (Mandriva using {\TeX}Live), and on a Solaris platform (OpenIndiana). % \end{abstract} % +% \begin{minipage}{11cm} +% \centering +% \ifpdf +% \includegraphics[width=10cm]{Rubikrot-doc-figD.pdf} +% \else +% \fi +% \end{minipage} % -% \bigskip +% \vspace{-1\baselineskip} % % \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}). +% It consists of a style option (\texttt{rubikrotation.sty}), a +% Perl script (\texttt{rubikrotation.pl}) and some examples. % -% The primary role of the \rubikrotation\ package is to implement on-the-fly Rubik -% rotation sequences using the \cmd{\RubikRotation} command. Consequently, this +% The primary role of the \rubikrotation\ package is to implement a sequence of +% Rubik rotation moves on-the-fly using the \cmd{\RubikRotation} command. Consequently, this % package requires the use of the \texttt{--shell-escape} switch to allow -% 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' +% command-line control of the Perl script, which is really the `engine' of this package. +% +% The \rubikrotation\ package has been road-tested on a Microsoft +% platform (with MiKTeX and Strawberry Perl\,\footnote{`Strawberry Perl' % (\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). +% environment of Unix/Linux systems.}), on a Linux platform (Mandriva using +% {\TeX}Live), and on a Solaris platform (OpenIndiana). % -% The following commands are made available by \texttt{rubikrotation.sty}. +% The following commands are made available by \texttt{rubikrotation.sty}: % \begin{quote} % \begin{verbatim} -% \RubikRotation{} +% \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} @@ -146,277 +157,403 @@ % % Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it. % This will generate the following files: +%\begin{quote} % \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 +% rubikrotation.pdf --this document +% rubikrotation.pl --Perl script +% rubikrotationPL.pdf --documentation of rubikrotation.pl +% rubikrotation.1 --the man file +% Rubikrot-doc-figA.pdf +% Rubikrot-doc-figB.pdf +% Rubikrot-doc-figC.pdf +% Rubikrot-doc-figD.pdf +% examples.tex +% examples.pdf +% examples.sh +% examples.bat +%\end{verbatim} +%\end{quote} +% Note that the package includes an `examples' file (\texttt{examples.tex}) +% as well as associated \texttt{.sh} (Linux) and \texttt{.bat} (Microsoft) batch +% files which can be used to facilitate processing the file. +% The main package documentation is the file \texttt{rubikrotation.pdf}. +% +% The style option \texttt{rubikrotation.sty} is generated by running (pdf)\LaTeX\ on % the file \texttt{rubikrotation.ins} as follows: +%\begin{quote} %\begin{verbatim} % pdflatex rubikrotation.ins %\end{verbatim} -% The documentation file (\texttt{rubikrotation.pdf}) was generated using the following -% steps: +%\end{quote} +% The documentation file (\texttt{rubikrotation.pdf}) is then generated using the following +% sequence of steps\,\footnote{Since the documentation includes a complicated indexing +% system as well a \textsc{pdf} index and hyperef links (the package \texttt{hypdoc} +% is used), then a lot of pdflatex runs are required. Prior to the first run it is +% a good idea to delete any relevant \texttt{.toc}, \texttt{.aux}, \texttt{.out} files.}: +%\begin{quote} % \begin{verbatim} -% pdflatex --shell-escape rubikrotation.dtx -% pdflatex --shell-escape rubikrotation.dtx +% pdflatex rubikrotation.dtx +% pdflatex rubikrotation.dtx % makeindex -s gind.ist rubikrotation % makeindex -s gglo.ist -o rubikrotation.gls rubikrotation.glo -% pdflatex --shell-escape rubikrotation.dtx +% pdflatex rubikrotation.dtx +% pdflatex rubikrotation.dtx %\end{verbatim} +%\end{quote} % - % +% % \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: +% 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: % %\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. +%{\noindent}*.sty $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} +%{\newline}*.cfg $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/tex/latex/rubik/} +%{\newline}*.pdf $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/doc/rubik/} +%{\newline}*.pl $\rightarrow$ \texttt{/usr/local/texlive/texmf-local/scripts/rubik/} % +%\medskip +%{\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!. +% +% 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 +% (see Section~\ref{sec:configfile} below). Such a file (if one exists) will +% automatically be read by \texttt{rubikrotation.sty} providing the +% file is named \texttt{rubikrotation.cfg}. % -% \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} +%\medskip +%{\noindent}\textsc{the `man' file}:\ \ On a Linux platform this file +% (\texttt{rubikrotation.1}) would be typically located in the +% directory \verb!/usr/share/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, 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} +%\medskip +%{\noindent}\textsc{quick test}:\ \ To test that your system can now run the perl +% script, just type at the command-line +%\begin{quote} +% \begin{verbatim} +% rubikrotation -h %\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{quote} +% which should generate something like the following: +% \begin{verbatim} +% This is rubikrotation version 3.0 +% 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 +% For documentation see: rubikrotation.pdf, +% rubikrotationPL.pdf and rubikcube.pdf %\end{verbatim} % % % \section{Usage} -% +% \label{sec: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} +% and \texttt{rubikrotation.sty} in the \TeX\ file preamble \textit{after} loading +% the TikZ package (both Rubik packages require the TikZ package), for example, as follows: +%\begin{quote} +% \begin{verbatim} +% \usepackage{tikz} +% \usepackage{rubikcube,rubikrotation} %\end{verbatim} -% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} commandline switch -% (see following section). +%\end{quote} +% and run (pdf)\LaTeX\ using the \texttt{--shell-escape} command-line switch +% (see the 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. +% it is necessary to invoke (pdf)\LaTeX\ using the \texttt{--shell-escape} switch +% as follows: +%\begin{quote} % \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: +%\end{quote} +% In practice, it is probably most convenient to run this command via a +% bash/batch file. For example, on a Linux platform the following bash file +% will run the file, show any errors, and open the \textsc{pdf} using AcrobatReader. +%\begin{quote} % \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 +% echo "...checking error file" +% grep ERROR ./rubikstateERRORS.dat +% acroread filename.pdf & %\end{verbatim} +%\end{quote} % % -% \subsection{Test files} +% \subsection{Test file} % -% Two example tex files (which demonstrate the use of the package commands) are -% included in the package, namely: +% An example tex file (which demonstrates the use of some of the package commands) +% is included in the package, namely: +%\begin{quote} % \begin{verbatim} -% example-rot1.tex (shows 5 worked examples) -% example-rot2.tex (is a `test' file for experimenting with different commands) +% example-rot.tex (shows 8 worked examples) %\end{verbatim} -% These need to be run using \texttt{--shell-escape} switch; for example: +%\end{quote} +% This file needs to be run using \texttt{--shell-escape} switch; for example: +%\begin{quote} % \begin{verbatim} -% pdflatex --shell-escape example-rot1.tex +% pdflatex --shell-escape example-rot.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. +%\end{quote} +% Batch files (\texttt{.sh} for Linux, and \texttt{.bat} for Microsoft) are also provided +% to facilitate running the `example' file. +% For example, on a Linux platform one would run a \texttt{bash} file as follows: +%\begin{quote} +% \begin{verbatim} +% bash example-rot.sh +%\end{verbatim} +%\end{quote} +% If processing this file gives unexpected results (e.g.,~the cubes appear not to +% have experienced any rotations) check-out the associated log file to see if +% the operating system had any difficulties finding files etc. +% % +% \subsection{Configuration-file} +% \label{sec:configfile} % +% 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 +% user to change not only (a)~the filename of the Perl script (\texttt{rubikrotation.pl}), +% but also (b)~the command-line code used by \texttt{rubikrotation.sty} for calling the +% Perl script. This~sort of fine-tuning can be very useful, and sometimes may +% even be necessary (depending on your system) for running the Perl script. % +% For example, on some systems it maybe preferable to use a different \textsc{path}, +% file-name and/or a different command-line code to call the script. +% 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 commands we may wish to adjust. +% The~first is that defining the filename of the Perl script, namely +% \cmd{\rubikperlname}. The second is that defining the command-line call, +% 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 to use the \cmd{\space} command on the end of the backslash +% command (\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. +% +% \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 +% (called \texttt{rubikrotation.cfg}) which contains just the following line: +%\begin{quote} +%\begin{verbatim} +%\renewcommand{\rubikperlname}{rubikrotationR77} +%\end{verbatim} +%\end{quote} +% +% \medskip +% {\noindent}\textsc{example~2}:\ \ Alternatively, suppose we wish to test out +% a new Perl script with the (non-executable) name \texttt{rubikrotationR55.pl}. +% Now, in this particular case we will need to run the script using a +% slightly different command, namely, +% {\linebreak}\texttt{perl rubikrotationR55.pl ...}, and consequently we +% need to implement both these changes in the configuration-file, as follows: +%\begin{quote} +%\begin{verbatim} +%\renewcommand{\rubikperlname}{rubikrotationR55.pl} +%\renewcommand{\rubikperlcmd}{perl \rubikperlname\space\% +% -i rubikstate.dat -o rubikstateNEW.dat} +%\end{verbatim} +%\end{quote} +%{\noindent}\textsc{placing the configuration-file}:\ \ The simplest arrangement is +% just to include the \texttt{.cfg} file in the working `test' directory. +% Alternatively, the \texttt{.cfg} file could be placed in the \texttt{/texmf-local/} +% directory tree (say, in \path!/usr/local/texlive/texmf-local/tex/latex/rubik/!), +% but in this case one would then have to be careful to specify the +% correct PATH for everything in order to enable your system to find all the +% various components etc. +% +% Note that you can, of course, have several \texttt{.cfg} files, since the system will +% read only one such file (the first one it finds starting with the current working +% directory). Consequently, it may be useful to have one \texttt{.cfg} file in +% your \texttt{/texmf-local/} dir (for running the standard Rubik package), +% and another (different) \texttt{.cfg} file in your `test' directory. +% +% % \section{Commands} % -% The \textit{only} commands which \textit{must} be used inside a TikZ picture +% The \textit{only} `Rubik bundle' 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 +% 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}, +% \texttt{minipage} or \texttt{figure} environments +% generally offers maximum flexibility, since the effects of such commands when +% used inside these environments remain `local' to the environment, and are not +% therefore accessable outside that \textit{particular} environment +% (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 % (see the notes on this command below). % % -% \subsection{\cmd{\RubikRotation} command} +% \subsection[RubikRotation command]{\cmd{\RubikRotation} command} +% \label{sec:rubikrotationcmd} % % \DescribeMacro{\RubikRotation} -% The \cmd{\RubikRotation}\marg{comma separated sequence} command processes -% a comma separated sequence of rotations, and returns the final state. +% The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence} +% command processes a comma separated sequence of rotations, and returns +% the final state. The optional \oarg{integer} argument specifies the number +% of times the command should be repeated. +% % For example, if we wanted to see the effect of the rotations % \textbf{R, R, L, U, D} on a solved Rubik cube, we could use the % following commands. +%\begin{quote} % \begin{verbatim} +% \RubikCubeSolved % sets up the colours for a solved cube state +% \RubikRotation{R2,L,U,D} % \begin{tikzpicture}[scale=0.7] -% \RubikCubeSolved -% \RubikRotation{R2,L,U,D} % \DrawRubikCubeRU -% \end{tikzpicture} +% \end{tikzpicture}% %\end{verbatim} +%\end{quote} % 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 then calling the Perl script \texttt{rubikrotation.pl}. The Perl +% script then reads the current Rubik state from the (\texttt{rubikstate.dat}) +% file, performs all the rotations, and then writes the new Rubik state % (and any error messages) to the file \texttt{rubikstateNEW.dat}, -% which is then input on-the-fly by the \LaTeX\ file 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): +% which is then input on-the-fly by the \LaTeX\ file. This new Rubik state +% can then either used as the input for another \cmd{\RubikRotation}, or used +% to generate a graphic image of the cube. +% +% A given rotation sequence can be repeated multiple times, say $n$ times, by +% using the optional \verb![n]!. For example, the following two commands are equivalent: +%\begin{quote} % \begin{verbatim} -% \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp} +% \RubikRotation[3]{x,R,U} +% \RubikRotation{x,R,U,x,R,U,x,R,U} %\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): +%\end{quote} +% + +% \subsubsection{Sequences as macros} +% \label{sec:seq-as-macros} +% +% Macros which are arguments of the \TeX\ \cmd{\write} command are expanded +% on writing (Eijkhout 1992, \S\,30.2.3, p.\,238)[\,see refs Section~\ref{sec:references}\,]. +% Consequently we are able to use a sequence-defining macro as an argument for +% the \cmd{\RubikRotation} command. In fact this is very convenient, since it allows +% one to store lots of different rotation sequences by name alone. +% +% For example, we can use the name `sixspot' for a macro denoting the rotation sequence +% which generates the well known `sixspot' configuration (see the `patterns' page on the +% Reid website)[\,see refs Section~\ref{sec:references}\,], as follows: +%\begin{quote} % \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: +%\end{quote} +% With this new \cmd{\sixspot} command we are now able to generate the graphic (sixspot cube) +% very easily using the following code---this time we demonstrate the use of the more convenient +% \cmd{\ShowCube} command (which includes the \texttt{tikzpicture} environment): % % \medskip % % \begin{minipage}{6cm} % \begin{verbatim} -% \begin{tikzpicture}[scale=0.7] -% \RubikCubeSolved -% \RubikRotation{\sixspot} -% \DrawRubikCubeRU -% \end{tikzpicture} +% \RubikCubeSolved +% \RubikRotation{\sixspot} +% \ShowCube{3cm}{0.7}{\DrawRubikCubeRU} %\end{verbatim} % \end{minipage} % \begin{minipage}{3.4cm} % \centering % \ifpdf -% \includegraphics[height=3cm]{Rubikrot_doc_figA.pdf} +% \includegraphics[height=3cm]{Rubikrot-doc-figA.pdf} % \else % \fi % \end{minipage} % -% % \medskip +% Providing such macros (when used as arguments) are comma separated (as the rotation codes +% must be), then the \cmd{\RubikRotation} command can accommodate both rotation codes +% and macros; for example, \verb!\RubikRotation{x,y,\sixspot,x}!. % +% +% \subsubsection{Arguments prefixed with *, [, ]} +% \label{sec:prefixedargument} +% +% If any of the comma separated arguments is prefixed with either *, [ or ] they are +% interpreted as an inactive `string', and not as a rotation. This feature therefore +% allows a string argument to be used as a label, which can be very useful. +% +% For example, we can use this facility to label the `sixspot' configuration mentioned above, +% as follows: +%\begin{quote} +% \begin{verbatim} +% \RubikRotation{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp} +%\end{verbatim} +%\end{quote} % In practice, it is quite useful to go one step further and include -% the \texttt{*} label feature as well in the newcommand, as follows: +% the [\,] label feature in the \cmd{\sixspot} command, as follows, +%\begin{quote} % \begin{verbatim} -% \newcommand{\sixspot}{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp} +% \newcommand{\sixspot}{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp} %\end{verbatim} -% 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} +%\end{quote} +% since this has the great advantage of making the label-name visible in the log file. +% For example, the following command, which uses the rotations \textbf{x}, \textbf{x} % and \textbf{y} to initially rotate the `solved' cube before applying % the `sixspot' sequence of rotations, +%\begin{quote} % \begin{verbatim} % \RubikRotation{x2,y,\sixspot} %\end{verbatim} +%\end{quote} % will then be represented in the log file as +%\begin{quote} % \begin{verbatim} -% ...command=rotation,x2,y,*sixspot,U,Dp,R,Lp,F,Bp,U,Dp -% ...arguments passed to `rotation' sub = x2 y *sixspot U Dp R Lp F Bp U Dp (n= 11) +% ...command=rotation,x2,y,[sixspot],U,Dp,R,Lp,F,Bp,U,Dp +% ...arguments passed to `rotation' sub = x2 y [sixspot] U Dp R Lp F ... % ...rotation x OK (= rrR + rrSr + rrLp) % ...rotation x OK (= rrR + rrSr + rrLp) % ...rotation y OK (= rrU + rrSu + rrDp) -% ...*sixspot is a label OK +% ...[sixspot] is a label OK % ...rotation U OK % ...rotation Dp OK % ...rotation R OK @@ -426,8 +563,60 @@ % ...rotation U OK % ...rotation Dp OK %\end{verbatim} +%\end{quote} % In this way, several named rotation sequences can be easily distinguished -% in the log file from adjacent rotation commands. +% in the log file from adjacent rotation sequences. +% This feature is also useful when typesetting a sequence of rotation codes, since the first +% element will then appear in the form \verb![name]!, obviating the need to typeset the +% name of the sequence separately. +% +% To this end, the +% \verb!ForEachX! macro---from the \verb!forarray! package---can be very useful. +% For example, this macro is central to the following example macro for typesetting +% a rotation sequence using the Rubik \cmd{\rr} command: +%\begin{quote} +%\begin{verbatim} +%\def\x{\thislevelitem} +%\def\xcount{\thislevelcount} +% +%\newcommand{\showseq}[1]{% +% \ForEachX{,}{% +% \ifthenelse{\xcount=1}{\texttt{\x}}{,\ \rr{\x}}% +% }{#1}. +%} +%\end{verbatim} +%\end{quote} +% Now, for a sequence defined as |\newcommand{\myseq}{[myseq],U,D,Lwp,R}|, then +% the command |\showseq{\myseq}| will result in the following output: +%\begin{quote} +% \texttt{[myseq]},\ \textbf{U},\ \textbf{D},\ \textbf{Lwp},\ \textbf{R}. +%\end{quote} +% Note that we are able to typeset the name \texttt{[myseq]} differently from the +% remaining sequence since the counter \verb!\xcount! allows us to locate the first item. +% However, this macro as it stands needs further development in order to handle +% sequence elements with a terminal digit (e.g.,~\texttt{R2})---the macro will need +% to first expand this to \texttt{R, R} if the Rubik commands are to be used. +% +% \subsubsection{Groups} +% +% The \cmd{\RubikRotation} command is a convenient tool for +% illustrating how Rubik rotations and sequences of rotations are elements +% of groups and subgroups. +% For~example, using the \rubikrotation\ package it is easy to +% show that three cycles of the `sixspot' sequence return the Rubik cube to its +% original state. More formally this is equivalent to $($\cmd{\sixspot}$)3 \equiv 0$, +% and can be nicely illustrated by implementing the following pseudocode: +%\begin{verbatim} +% \RubikCubeSolved . \RubikRotation[3]{\sixspot} = \RubikCubeSolved +%\end{verbatim} +% +% \begin{minipage}{11cm} +% \centering +% \ifpdf +% \includegraphics[width=10cm]{Rubikrot-doc-figC.pdf} +% \else +% \fi +% \end{minipage} % % % \subsubsection{Random rotations} @@ -438,65 +627,78 @@ % 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. -% +% If $n > 200$ then the currently set maximum value $n=200$ will be used. +% +% As a safety feature the maximum $n$ can be changed only by editing the +% set value of the Perl variable \verb!$maxn! in the Perl script +% \texttt{rubikrotation.pl}, where (see line~583) we currently have +%\begin{quote} +%\begin{verbatim} +% my $maxn=200; +%\end{verbatim} +%\end{quote} +% % 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} +% \includegraphics[height=4cm]{Rubikrot-doc-figB.pdf} % \else % \fi % \end{minipage} +% \begin{minipage}{6cm} +% \vspace{1.6cm} +%\begin{verbatim} +% \RubikCubeSolved% +% \RubikRotation{random,120}% +% \ShowCube{5.5cm}{0.5}{\DrawRubikCubeFlat} +%\end{verbatim} +% \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 +% the \cmd{\Draw..} command is inside the TikZ picture environment (i.e.,~inside +% the \cmd{\ShowCube} command). Note also that when Rubik % 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 randomisation procedure is as follows: all the possible rotations are first allocated +% a different cardinal number (positive 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}} +% \subsection[SaveRubikState]{\cmd{\SaveRubikState} command} +% \label{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). +% format so that it can be read by \LaTeX. Consequently such a file can then be input +% so it can be drawn or processed in the usual way. The output file is `closed' immediately +% following the `write' in order to allow it to be available for input later by the same +% file if required. % % 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{quote} %\begin{verbatim} % \RubikCubeSolved% % \RubikRotation{*sixspot,U,Dp,R,Lp,F,Bp,U,Dp}% % \SaveRubikState{sixspot.tex}% %\end{verbatim} +%\end{quote} % 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{quote} %\begin{verbatim} % % filename: sixspot.tex % \RubikFaceUp{O}{O}{O}{O}{W}{O}{O}{O}{O}% @@ -506,75 +708,81 @@ % \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}% % \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}% %\end{verbatim} +%\end{quote} % We can therefore access and draw this configuration later, when required, % simply by inputting the file as follows: +%\begin{quote} %\begin{verbatim} -%\begin{tikzpicture} -% \input{sixspot.tex} -% \DrawRubikCubeFlat -%\end{tikzpicture} +%\input{sixspot.tex} +%\ShowCube{7cm}{0.7}{\DrawRubikCubeFlat} %\end{verbatim} +%\end{quote} % % -% \subsection{\cmd{\CheckRubikState} command} +% \subsection[CheckRubikState]{\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 +% (e.g.,~enter an invalid number of, say, yellow facelets), 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. +% 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. % % One can check the current Rubik state (for errors) by issuing the command +%\begin{quote} %\begin{verbatim} % \CheckRubikState% %\end{verbatim} +%\end{quote} % Note that such a check is implemented automatically with each \cmd{\RubikRotation} command. % % % % -% \subsection{\cmd{\ShowRubikErrors} command} +% \subsection[ShowRubikErrors]{\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 +% 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. % % 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. -% +% 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. % % \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 +% 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 +% \item The Perl script \texttt{rubikrotation.pl} 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. +% \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. % % \end{itemize} % % % \section{General overview} -% -% When \LaTeX\ loads the \rubikrotation\ package the following steps are implemented. +% \label{generaloverview} +% When \LaTeX\ processes \texttt{rubikrotation.sty} the following steps +% are implemented. % \begin{itemize} % % @@ -582,13 +790,13 @@ % 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}) +% \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. +% \item[4.] The plain-text file \texttt{rubikstateERRORS.dat} is created. % This file collects error messages generated by the Perl script. % % \end{itemize} @@ -597,13 +805,14 @@ % When a \cmd{\RubikRotation} command is processed it first writes the current % colour configuration of each face (the `rubik state') to the temporary file % \texttt{rubikstate.dat} (to be read by the Perl script \texttt{rubikrotation.pl}). -% 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}. +% 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 +% followed by the command \verb!\RubikRotation[2]{U,D,L,R}!, then the associated % \texttt{rubikstate.dat} file would be as follows: +%\begin{quote} % \begin{verbatim} % % filename: rubikstate.dat % up,W,W,W,W,W,W,W,W,W @@ -614,39 +823,141 @@ % back,R,R,R,R,R,R,R,R,R % checkstate % rotation,U,D,L,R +% rotation,U,D,L,R %\end{verbatim} -% Alternatively, if the \cmd{\RubikRotation} command was +%\end{quote} +% Note that the \cmd{\RubikRotation} option \texttt{[2]} results in the line \texttt{rotation,U,D,L,R} +% being written twice to the \texttt{rubikstate.dat} file, as shown above. +% +% Alternatively, if we used the command % \verb!\RubikRotation{random, 45}! then the last line written to the file -% would be the string `\texttt{rotation,random,45}' +% would be the string `\texttt{rotation,random,45}', as follows: +%\begin{quote} +% \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,random,45 +%\end{verbatim} +%\end{quote} % 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 +% 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 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 +% When control passes to Perl, the script \texttt{rubikrotation.pl} starts +% by loading the current rubikstate (prompted by the keywords \texttt{up}, \texttt{down}, +% \texttt{left}, \texttt{right}, \texttt{front}, \texttt{back}, in the file +% \texttt{rubikstate.dat}). Next the Perl script +% performs some basic checks (prompted by the key word \texttt{checkstate}), and +% then it processes the sequence of Rubik rotations (prompted by the keyword +% \texttt{rotation}). If, instead, the second argument of the `rotation' string +% is the keyword `random', and provided this is followed by a valid integer, say $n$, +% 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. % % 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 +% then this cycle repeats accordingly. Eventually a \cmd{\Draw...} command % of some form is reached and the final rubikstate is drawn in a TikZ picture % environment. % % 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. +% \cmd{\ShowRubikErrors} 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, +% by using \texttt{grep} to scan the \texttt{rubikstateERRORS.dat} file at the end of +% the run; for example, as follows: +%\begin{quote} +%\begin{verbatim} +% pdflatex --shell-escape myfile.tex +% echo "...checking error file" +% grep ERROR ./rubikstateERRORS.dat +%\end{verbatim} +%\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 Nickalls RWD and Syropoulos A (2015). The \textsc{rubikcube} package. +% \newline\url{http://www.ctan.org/pkg/rubik}, +% +% \item Reid M. \ Patterns. \url{http://www.cflmath.com/Rubik/patterns.html} +% {\newline}[\,re:~sequences as macros; in Section~\ref{sec:seq-as-macros}\,] +% +%\end{itemize} +% +% % +% \section{Change history} % +% \begin{itemize} +% \item Version 3.0 (25 September 2015) +% +% --- The \cmd{\RubikRotation} command now actions multiple instances of its argument +% as determined by an optional `repeat' \oarg{integer}. For example the command +% \cmd{\RubikRotation[3]\{R,x\}} is equivalent to the command \cmd{\RubikRotation\{R,x,R,x,R,x\}} +% (see Sections~\ref{sec:rubikrotationcmd} and \ref{sec:rubikrotationcode}). +% +% --- If a comma separated element used as an argument for the \cmd{\RubkRotation} +% command is prefixed with either a * or [ or ] character then it is not actioned +% as a rotation (see Section~\ref{sec:prefixedargument}). +% +% --- The Perl script \texttt{rubikrotation.pl} now has command-line switches, +% including \texttt{-h} to show some `help' and `usage' information +% (see Section~\ref{sec:placingfiles}). +% +% --- A `man' file for the Perl script \texttt{rubikrotation.pl} is now included in the package. +% +% --- The Perl script \texttt{rubikrotation.pl} now uses as input and output filenames +% those specified in the command-line of the CALLing program. This now allows the +% script \texttt{rubikrotation.pl} to be used as a stand-alone tool (see the +% \texttt{rubikrotation} `man' file for details). +% +% --- The documentation for the Perl script \texttt{rubikrotation.pl} is in the +% accompanying file \texttt{rubikrotationPL.pdf}. +% +% --- Fixed typos, index and minor errors in the documentation. +% +% +% \item Version 2.0 (5 February, 2014) +% +% --- First release. +% +% \end{itemize} % % ^^A ================================================== % \StopEventually{\PrintIndex} @@ -654,21 +965,27 @@ % % % \section{The code (\texttt{rubikrotation.sty})} -% +% +% {\noindent}In the following, the term `Perl script' denotes the script +% \texttt{rubikrotation.pl}. Useful information regarding the +% \TeX\ \cmd{\write} command is given in Eijkhout (1992), \S\,30.2.3 (page~238). +% For the means of including a `\%' character in the token list of \cmd{\write} see +% Abrahams \textit{et.~al} (1990). +% % \subsection{Package heading} % % \begin{macrocode} %<*rubikrotation> -\def\RRfileversion{2.0}% -\def\RRfiledate{2014/01/20}% +\def\RRfileversion{3.0}% +\def\RRfiledate{2015/09/25}% \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). +% {\noindent}The package requires \texttt{rubikcube.sty}. However \texttt{rubikcube.sty} +% is not automatically loaded (for the moment at least) since this makes it difficult +% to errorcheck new versions. % \begin{macrocode} \@ifpackageloaded{rubikcube}{}{% \typeout{---rubikrotation requires the rubikcube package.}% @@ -678,23 +995,34 @@ % % % {\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. +% for the \cmd{\VerbatimInput\{\}} command which we use for inputting and displaying +% the error file (see Section~\ref{sec:showrubikerrors}). % \begin{macrocode} \@ifpackageloaded{fancyvrb}{}{% \typeout{---rubikrotation requires the fancyvrb package% for VerbatimInput{} command.}% \RequirePackage{fancyvrb}} % \end{macrocode} -% \medskip % +% \medskip % -%\subsection{Some useful commands} -% \label{sec:usefulcommands} +% \subsection{Some useful commands} +% \label{sec:usefulcommands} +% % \begin{macro}{\rubikrotation} % First we create a suitable logo % \begin{macrocode} -\newcommand{\rubikrotation}{\textsf{rubikrotation}} +\newcommand{\rubikrotation}{\textsc{rubikrotation}} +\newcommand{\Rubikrotation}{\textsc{Rubikrotation}} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\@print} +% We need a simple print command to facilitate writing output to a file. +% \begin{macrocode} +\newcommand{\@print}[1]{\immediate\write\outfile{#1}} % \end{macrocode} % \end{macro} % @@ -702,11 +1030,17 @@ % % \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/) +% We also require access to the `\%' character so we can (a)~write comments to +% files, including the log file, and (b)~place a trailing `\%' in a line of code +% written to a file. +% +% To achieve this we define the `\%' character as \cmd{\rubikpercentchar} +% (modified from: Abrahams PW, Berry K and Hargreaves KA (1990), p~292) +% [see refs Section~\ref{sec:references}]\label{sec:abrahams}, +% and also two `comment' commands which implement it. This `workaround' +% is necessary because \TeX\ does not allow the use of the \cmd{\%} command +% for placing a `\%' character in the token list of \cmd{\write}. +% See Abrahams \textit{et.~al} (1990) for details. % \begin{macrocode} {\catcode`\%=12 \global\def\rubikpercentchar{%}}% \newcommand{\@comment}{\rubikpercentchar\rubikpercentchar\space}% @@ -716,39 +1050,50 @@ % \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. +% This holds the name of the Perl script. A configuration-file +% (\verb!rubikrotation.cfg!) can be used to change the default name of the +% Perl script using a renewcommand (see Section~\ref{sec:configfile}). % \begin{macrocode} -\newcommand{\rubikperlname}{rubikrotation.pl} +\newcommand{\rubikperlname}{rubikrotation} % \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. +% This holds the command-line code for calling the Perl script +% (assumed to be an executable file). +% Note that the command-line requires a mandatory input filename preceded +% by the \texttt{-i}~switch. An optional output filename (preceded by the +% \texttt{-o}~switch) may be used, otherwise the default output filename of +% \texttt{rubik-OUT.dat} will be used. +% +% Note that it is very important that this .sty file actually specifies an +% output filename (for receiving data from the Perl script). This is because +% (a)~The Perl script \texttt{rubikrotation.pl} is currently configured to read its +% output filename as an argument from the command-line (so it can be flexibly +% used as a stand-alone script for processing a given Rubik state through a +% sequence of rotations), and (b)~\texttt{rubikrotation.sty} is currently +% configured to read its input from the file \texttt{rubikstateNEW.dat}. % \begin{macrocode} -\newcommand{\rubikperlcmd}{perl \rubikperlname} +\newcommand{\rubikperlcmd}{\rubikperlname\space% + -i rubikstate.dat -o rubikstateNEW.dat} % \end{macrocode} +% Remember to use the \cmd{\space} command following the \LaTeX\ backslash +% command in order to generate the mandatory space between it and the first +% command-line argument). +% +% A plain-text configuration-file \verb!rubikrotation.cfg! can be used to +% change the default command-line code using a renewcommand +% (see Section~\ref{sec:configfile}). % \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} +% \subsection{Configuration file} +% +% If a configuration file exists (\texttt{rubikrotation.cfg}) then input it here, +% i.e.,~\textit{after} defining the \cmd{\rubikperlname} and \cmd{\rubikperlcmd} % commands and \textit{before} creating the \texttt{rubikstateERRORS.dat} file. % \begin{macrocode} \typeout{---checking for config file (rubikrotation.cfg)...} @@ -761,71 +1106,61 @@ % % \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). +% {\noindent}We need to clean out any existing (old) rubikstateNEW.dat file, +% since if the TeX shell command-line switch is accidentally not used then the Perl script +% \texttt{rubikrotation.pl} will not be CALLed, and hence this file will not be renewed +% (i.e.,~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)}% +\@print{\@comment rubikstateNEW.dat}% \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 +% {\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}. % -% \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 +% \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, +% so this file just grows until either it is destroyed or recreated---this is +% a useful feature since the file accumulates all error messages as the +% \texttt{.tex} file is processed. +% We can't make the Perl script create the file since the Perl script 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. +% command (which we may not\,!)---so it has to be created here. % \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}}% +\@print{\@comment ---(RR.sty v\RRfileversion): comments output by Perl script}% \immediate\closeout\outfile% % \end{macrocode} % % -% \subsection{Setting up a newwrite and file-access for new files} +% \subsection{Setting up 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 +% all subsequent file openings (e.g.,~for \texttt{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). +% 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). % \begin{macrocode} -\typeout{---setting up newwrite for rubikrotation to use...}% +\typeout{---setting up newwrite for rubikrotation.sty to use...}% \newwrite\outfile% % \end{macrocode} % % % \begin{macro}{\@openstatefile} % \begin{macro}{\@closestatefile} -% We also need commands for easy file opening and and closing +% We also need commands for easy file opening 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. @@ -840,12 +1175,19 @@ % \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 +% This internal command writes the Rubik configuration to +% the file \texttt{rubikstate.dat}, and is used by the \cmd{\RubikRotation} command +% (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 program to implement its \texttt{checkstate} subroutine. +% in order to trigger the Perl script to implement its \texttt{checkstate} subroutine. +% +% The actual state is simply an ordered sequence of the faces and the colours +% associated with each facelet of that face. The colour associated with a particular facelet +% 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{up,\Ult,\Umt,\Urt,\Ulm,\Umm,\Urm,\Ulb,\Umb,\Urb}% @@ -860,43 +1202,123 @@ % \end{macro} % % +% \subsection{SaveRubikState command} +% \label{sec:eijkhout} +% +% \begin{macro}{\SaveRubikState} +% The command \cmd{\SaveRubikState}\marg{filename} saves the Rubik state +% to a named file in the format of a Rubik command (so it can then be processed +% by \LaTeX). Note that in order to actually write a LaTeX +% command to a file without a trailing space one must prefix the command with the +% \cmd{\string} command (see Eijkhout (1992), p~238) +% [see refs Section~\ref{sec:references}]\label{sec:eijkhout}. +% +% 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: +% {\newline}\verb!\RubikFaceUp{W}{W}{G}{W}{W}{G}{B}{B}{Y}%! +% \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} +% +% % \subsection{RubikRotation command} +% \label{sec:rubikrotationcode} % % \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. +% The \cmd{\RubikRotation}\oarg{integer}\marg{comma separated sequence} +% command (a)~writes the current Rubik state to the file \texttt{rubikstate.dat}, +% (b)~writes the rotation sequence (either once or multiple times depending +% on the value of the optional integer argument), and then (c)~CALLs the +% Perl script \texttt{rubikrotation.pl}. It~also writes comments to the +% data file and also to the log file. +% +% In order to allow the user to (optionally) write the main argument multiple +% times to the output data-file, we require this command to allow an optional +% argument (a non-negative integer) to specify the number of such repeats. +% In order to implement an optional argument facility we use two macros +% (countingloop and loopcounter) detailed by Feuers\"{a}nger (2015) +% [\,see refs Section~\ref{sec:references}\,]\label{sec:feuersanger}, +% as follows: % \begin{macrocode} -\newcommand{\RubikRotation}[1]{\IfFileExists{\rubikperlname}{% +%% Two macros detailed by Feuersaenger (2015) +\long\def\@countingloop#1 in #2:#3#4{% + #1=#2 % + \@loopcounter{#1}{#3}{#4}% +} +%%-------------------------- +\long\def\@loopcounter#1#2#3{% + #3% + \ifnum#1=#2 % + \let\next=\relax% + \else + \advance#1 by1 % + \def\next{\@loopcounter{#1}{#2}{#3}}% + \fi + \next +} +% \end{macrocode} +% Having defined the above two macros we can now implement an optional +% argument (a repeat number) indicating the number of times we want +% the command to write the main argument to the output data file. +% \begin{macrocode} +\newcommand{\RubikRotation}[2][1]{% \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}% + \@print{\@comment written by rubikrotation.sty% + =v\RRfileversion\space (\RRfiledate)}% \@printrubikstate% - \@print{rotation,#1}% +%% countingloop code from Feuersaenger (2015) + \newcount\ourRRcounter% + \@countingloop{\ourRRcounter} in 1:{#1}{% + \immediate\write\outfile{rotation,#2}}% \@closestatefile% close data file - \typeout{---running Perl script}% + \typeout{---running Perl script (rubikrotation)}% \immediate\write18{\rubikperlcmd}% - \typeout{---inputting NEW datafile (from Perl)}% + \typeout{---inputting NEW datafile (written by Perl script)}% \input{rubikstateNEW.dat}% \typeout{-----------------------------------------}% - }{\typeout{** ERROR: \rubikperlname\space does not exist}% -}} + } % \end{macrocode} % \end{macro} % % % \subsection{ShowRubikErrors command} +% \label{sec:showrubikerrors} % % \begin{macro}{\ShowRubikErrors} % This command inputs the file \texttt{rubikstateERRORS.dat}. % \begin{macrocode} \newcommand{\ShowRubikErrors}{% \typeout{---ShowRubikErrors: inputting file rubikstateERRORS.dat}% - \VerbatimInput{rubikstateERRORS.dat}} + \VerbatimInput{rubikstateERRORS.dat}% + } % \end{macrocode} % \end{macro} % @@ -904,69 +1326,30 @@ % \subsection{CheckRubikState command} % % \begin{macro}{\CheckRubikState} -% This command triggers the Perl program to implement +% 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 program. +% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl script. % It also writes comments to the data file and also to the log file.. % \begin{macrocode} -\newcommand{\CheckRubikState}{\IfFileExists{\rubikperlname}{% +\newcommand{\CheckRubikState}{% \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}% + \typeout{---running Perl script (rubikrotation)}% \immediate\write18{\rubikperlcmd}% - \typeout{---inputting NEW datafile (from Perl)}% + \typeout{---inputting NEW datafile (written by Perl script)}% \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 % -------------------------- |