summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/rubik/rubikrotation.dtx
blob: 57302ac37a78054845237deb6e6a549d2d36a211 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
% \iffalse meta-comment
% rubikrotation.dtx
%
% version 3.0
%
% Authors: RWD Nickalls (dick@nickalls.org) 
%        and Apostolos Syropoulos (asyropoulos@yahoo.com)

% 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
% version 1.3c of this license or (at your option) any
% later version. The latest version of this licence is in 
%
%       http://www.latex-project.org/lppl.txt
%
%<*readme>
%
% The rubikrotation package provides a collection of LaTeX commands and macros 
% for the typesetting of Rubik cube configurations and rotation 
% sequences using the TikZ graphic language.
%
% Please report errors or suggestions for improvement to
%
%         Dick Nickalls or Apostolos Syropoulos
%
% This package requires the basic TikZ package to be loaded already
%</readme>
%
%<*driver>
\listfiles
\documentclass{ltxdoc}
\IfFileExists{rubikrotation.sty}{\usepackage{rubikrotation}}{%
    \GenericWarning{rubikrotation.dtx}{Package file rubikrotation.sty not found.
    Documentation will be messed up!^^J
    (Generate rubikrotation.sty by (La)TeXing rubikrotation.ins, and then^^J
    process rubikrotation.dtx again)^^J}\stop
}%
\usepackage{ifpdf}
\usepackage{url,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
\setcounter{StandardModuleDepth}{1}
\begin{document}
  \DocInput{rubikrotation.dtx}
  \PrintChanges
  \PrintIndex
\end{document}
%</driver>
% \fi
%
%
% 
% \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
%%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
%
%
% \title{The \rubikrotation\ package}
%
% \author{
%      RWD Nickalls (dick@nickalls.org) \\
%     A Syropoulos (asyropoulos@yahoo.com)
%       }
%  \date{This file describes version \RRfileversion\ (\RRfiledate)\\
%  \texttt{www.ctan.org/pkg/rubik}}
%  \maketitle
%
%  \begin{abstract}
%  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}
%
% \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}), a 
%  Perl script  (\texttt{rubikrotation.pl}) and some examples.
% 
% 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 
% 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.}), on a Linux platform (Mandriva using 
%  {\TeX}Live), and on  a Solaris platform (OpenIndiana).
%
% The following  commands are made available  by  \texttt{rubikrotation.sty}:
% \begin{quote}
% \begin{verbatim}
%    \RubikRotation[]{}
%    \SaveRubikState
%    \CheckRubikState
%    \ShowRubikErrors
%\end{verbatim}
% \end{quote}
%
%
%  \section{Requirements}
% 
% The \rubikrotation\ package  requires the TikZ and the \textsc{rubikcube} packages.
% 
%
%   \section{Installation}
%
%  \subsection{Generating the files}
%
%  Place the file \texttt{rubikrotation.zip} into a temporary directory, and unzip it. 
% This will generate the following files:
%\begin{quote}
% \begin{verbatim}
% rubikrotation.ins
% rubikrotation.dtx
% 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}
%\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    rubikrotation.dtx
%  pdflatex    rubikrotation.dtx
%  makeindex -s gind.ist  rubikrotation
%  makeindex -s gglo.ist -o rubikrotation.gls  rubikrotation.glo
%  pdflatex    rubikrotation.dtx
%  pdflatex    rubikrotation.dtx
%\end{verbatim}
%\end{quote}
%
%
% 
%  \subsection{Placing the files}
% \label{sec:placingfiles}
%
% Place the files either in a working directory, or where your system 
% will find them, e.g.,~in your \texttt{/texmf-local/} directory tree. 
% For example, on a Linux platform with a standard \TeX\ Directory Structure (TDS), then:
%
%\medskip
%{\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}.
%
%\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.
%
%\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}
%\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 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}
%\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) 
% 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}
%\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
% echo "...checking error file" 
% grep ERROR  ./rubikstateERRORS.dat
% acroread filename.pdf &
%\end{verbatim}
%\end{quote}
%
%
%   \subsection{Test file}
%
% 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-rot.tex   (shows 8 worked examples)
%\end{verbatim}
%\end{quote}
% This file  needs to be run using  \texttt{--shell-escape} switch; for example:
%\begin{quote}
% \begin{verbatim}
% pdflatex  --shell-escape  example-rot.tex
%\end{verbatim}
%\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} `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 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[RubikRotation command]{\cmd{\RubikRotation} command}
% \label{sec:rubikrotationcmd}
%
%  \DescribeMacro{\RubikRotation}
% 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]
%    \DrawRubikCubeRU
% \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 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. 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[3]{x,R,U}   
% \RubikRotation{x,R,U,x,R,U,x,R,U}
%\end{verbatim}
%\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}
%\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}
% \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}
% \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 [\,] label feature  in the \cmd{\sixspot} command, as follows,
%\begin{quote}
% \begin{verbatim}
% \newcommand{\sixspot}{[sixspot],U,Dp,R,Lp,F,Bp,U,Dp}
%\end{verbatim}
%\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 ...
% ...rotation x OK (= rrR + rrSr + rrLp)
% ...rotation x OK (= rrR + rrSr + rrLp)
% ...rotation y OK (= rrU + rrSu + rrDp)
% ...[sixspot] is a label OK
% ...rotation U OK
% ...rotation Dp OK 
% ...rotation R OK
% ...rotation Lp OK
% ...rotation F OK
% ...rotation Bp OK
% ...rotation U OK
% ...rotation Dp OK 
%\end{verbatim}
%\end{quote}
% In this way, several named rotation sequences can be easily distinguished
% 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}
%
%  The \cmd{\RubikRotation} command  can also be used to  scramble the 
% cube using a random sequence of rotations. If  the first argument 
% is the lowercase word `random' \textsc{and} the second argument 
% is an integer $n$, ($1\leq n \leq 200$), then a random sequence 
% of $n$ rotations will be performed; otherwise  a default value 
% of 50 is used (for example, if the second argument is not an integer). 
% If $n > 200$ then  the 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. 
%

% \begin{minipage}{3.4cm}
% \centering
% \ifpdf
%   \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 (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 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[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 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}%
% \RubikFaceDown{R}{R}{R}{R}{Y}{R}{R}{R}{R}%
% \RubikFaceLeft{Y}{Y}{Y}{Y}{B}{Y}{Y}{Y}{Y}%
% \RubikFaceRight{W}{W}{W}{W}{G}{W}{W}{W}{W}%
% \RubikFaceFront{G}{G}{G}{G}{O}{G}{G}{G}{G}%
% \RubikFaceBack{B}{B}{B}{B}{R}{B}{B}{B}{B}%
%\end{verbatim}
%\end{quote}
% We can therefore access and draw this configuration later, when required, 
% simply by inputting  the file as follows:
%\begin{quote}
%\begin{verbatim}
%\input{sixspot.tex} 
%\ShowCube{7cm}{0.7}{\DrawRubikCubeFlat}
%\end{verbatim}
%\end{quote}
%
%
%  \subsection[CheckRubikState]{\cmd{\CheckRubikState} command}
%
%  \DescribeMacro{\CheckRubikState}
%  Since it is easy to inadvertently define an invalid Rubik cube 
% (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 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[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 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 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 
% 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  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   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}
% \label{generaloverview}
% When \LaTeX\  processes  \texttt{rubikrotation.sty}  the following steps
% are implemented.
% \begin{itemize}
%
% 
% \item[1.]  A check is made to see if  \texttt{fancyvrb.sty} is loaded: if not 
% then this package  is loaded if it is available (this package is required  
% for inputting the  file  \texttt{rubikstateERRORS.dat}).
% 
% \item[2.]  A check is made to see if a configuration-file (\texttt{rubikrotation.cfg})
%  exists:  if so then  this file is input.
%
% \item[3.] The text file \texttt{rubikstateNEW.dat} is overwritten (if it exists): 
% otherwise the file is created (this prevents an `old' file being used by \LaTeX).
%
% \item[4.]  The plain-text file \texttt{rubikstateERRORS.dat} is created. 
% This file collects error  messages generated by the Perl script.
%
% \end{itemize}
%
%
% When a \cmd{\RubikRotation} command is processed it first  writes the current 
% colour configuration of each face (the `rubik state') to the temporary file 
% \texttt{rubikstate.dat} (to be read by the Perl script \texttt{rubikrotation.pl}). 
% The \cmd{\RubikRotation} command also appends the keyword `\texttt{checkrubik}' 
%  as well as  a copy of the  string of Rubik rotations. 
% It~then calls the Perl script  \texttt{rubikrotation.pl}. 
%
% For example, if we use the command \cmd{\RubikCubeSolved}
% followed by the command \verb!\RubikRotation[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
% down,Y,Y,Y,Y,Y,Y,Y,Y,Y
% left,B,B,B,B,B,B,B,B,B
% right,G,G,G,G,G,G,G,G,G
% front,O,O,O,O,O,O,O,O,O
% back,R,R,R,R,R,R,R,R,R
% checkstate
% rotation,U,D,L,R
% rotation,U,D,L,R
%\end{verbatim}
%\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}', 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 script  \texttt{rubikrotation.pl} is controlled by 
% the keywords (first argument of
% each line)  associated with each line of the file \texttt{rubikstate.dat}. 
% When control passes to  Perl,  the script \texttt{rubikrotation.pl} starts 
% 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 \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} 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}
%
%
%
%        \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{3.0}%
\def\RRfiledate{2015/09/25}%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{rubikrotation}[\RRfiledate\space (v\RRfileversion)]
%    \end{macrocode}
%
%
% {\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.}%
   }%
%    \end{macrocode}
%
%
%
%  {\noindent}The \rubikrotation\  package requires access to the  fancyvrb package
%  for the \cmd{\VerbatimInput\{\}} command  which we use for inputting and displaying
%  the error file (see Section~\ref{sec:showrubikerrors}).
%    \begin{macrocode}
\@ifpackageloaded{fancyvrb}{}{%
   \typeout{---rubikrotation requires the fancyvrb package%
       for VerbatimInput{} command.}%
   \RequirePackage{fancyvrb}}
%    \end{macrocode}
%
%  \medskip
% 
%   \subsection{Some useful commands}
%   \label{sec:usefulcommands}
%
%    \begin{macro}{\rubikrotation}
% First we create a suitable logo
%    \begin{macrocode}
\newcommand{\rubikrotation}{\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}
%
%
%
%    \begin{macro}{\@comment}
%    \begin{macro}{\@commentone}
%  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}%
\newcommand{\@commentone}{\rubikpercentchar}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%
%
%    \begin{macro}{\rubikperlname}
%  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}
%    \end{macrocode}
%    \end{macro}
%
%
%    \begin{macro}{\rubikperlcmd}
%  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}{\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 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)...}
\IfFileExists{rubikrotation.cfg}{%
   \input{rubikrotation.cfg}%
   }{\typeout{---no config file available}%
}%
%    \end{macrocode}
%
%
%   \subsection{Clean file rubikstateNEW.dat}
%
% {\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}%
\immediate\closeout\outfile%
%    \end{macrocode}
%
%
%   \subsection{rubikstateERRORS.dat}
%
%  {\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  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 here.
%    \begin{macrocode}
\typeout{---creating file rubikstateERRORS.dat}%
\newwrite\outfile%
\immediate\openout\outfile=rubikstateERRORS.dat%
\@print{\@comment rubikstateERRORS.dat}%
\@print{\@comment ---(RR.sty v\RRfileversion): comments output by Perl script}%
\immediate\closeout\outfile%
%    \end{macrocode}
%
%
%    \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 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 
% \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.sty to use...}%
\newwrite\outfile%
%    \end{macrocode}
%
%
%    \begin{macro}{\@openstatefile}
%    \begin{macro}{\@closestatefile}
% 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. 
%    \begin{macrocode}
\newcommand{\@openstatefile}{\immediate\openout\outfile=rubikstate.dat}
\newcommand{\@closestatefile}{\immediate\closeout\outfile}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%
%    \subsection{Saving the Rubik state}
%
%    \begin{macro}{\@printrubikstate}
% This 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 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}%
   \@print{down,\Dlt,\Dmt,\Drt,\Dlm,\Dmm,\Drm,\Dlb,\Dmb,\Drb}%
   \@print{left,\Llt,\Lmt,\Lrt,\Llm,\Lmm,\Lrm,\Llb,\Lmb,\Lrb}%
   \@print{right,\Rlt,\Rmt,\Rrt,\Rlm,\Rmm,\Rrm,\Rlb,\Rmb,\Rrb}%
   \@print{front,\Flt,\Fmt,\Frt,\Flm,\Fmm,\Frm,\Flb,\Fmb,\Frb}%
   \@print{back,\Blt,\Bmt,\Brt,\Blm,\Bmm,\Brm,\Blb,\Bmb,\Brb}%
   \@print{checkstate}%
}
%    \end{macrocode}
%    \end{macro}
%
%
% \subsection{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}\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}
%% 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{---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% 
%% 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 (rubikrotation)}%
   \immediate\write18{\rubikperlcmd}%
   \typeout{---inputting NEW datafile (written by Perl script)}%
   \input{rubikstateNEW.dat}%
   \typeout{-----------------------------------------}%
 }
%    \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}%
 }
%    \end{macrocode}
%    \end{macro}
%
%
%   \subsection{CheckRubikState command}
%
%    \begin{macro}{\CheckRubikState}
% This command triggers the Perl script to implement 
%  some simple error checking of the Rubik configuration (state).
% This command (a)~writes the current Rubik state to the file 
% \texttt{rubikstate.dat}, and then (b)~CALLs the Perl script.
% It also writes comments to the data file and also to the  log file..
%    \begin{macrocode}
\newcommand{\CheckRubikState}{%
   \typeout{---NEW check command------------------}%
   \typeout{---command = CheckRubikState}%
   \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 (rubikrotation)}%
   \immediate\write18{\rubikperlcmd}%
   \typeout{---inputting NEW datafile (written by Perl script)}%
   \input{rubikstateNEW.dat}%
   \typeout{-----------------------------------------}%
 }
%    \end{macrocode}
%    \end{macro}
%
%
% --------------------------
%    End of this package
% --------------------------
%    \begin{macrocode}
%</rubikrotation>
%    \end{macrocode}
%
%
%
%
% \Finale
%
\endinput