20 files changed, 521 insertions, 0 deletions

diff --git a/docs/add.txt b/docs/add.txt
new file mode 100644
index 0000000..af1f079
--- /dev/null
+++ b/docs/add.txt
@@ -0,0 +1,18 @@
+
+HELP PAGE FOR COMMAND add
+
+SYNTAX
+add [MOVES|$ID1|@ID1] $ID2
+
+DESCRIPTION
+Appends either MOVES, the scramble memorized under $ID1 or the output sequence
+memorized under @ID1 at the end of the scramble memorized under $ID2. If none
+of MOVES, $ID1 or @ID1 is specified, the user will be asked to type the moves.
+Menmonic: "add x to y" or just "add to y".
+
+EXAMPLES
+add $1
+  The user is required to type the moves that will be appended to $1.
+add F R B $1
+  Appends the moves F R B to scramble $1. Now scramble $1 ends with F R B.
+
diff --git a/docs/change.txt b/docs/change.txt
new file mode 100644
index 0000000..b6bba0e
--- /dev/null
+++ b/docs/change.txt
@@ -0,0 +1,21 @@
+
+HELP PAGE FOR COMMAND change
+
+SYNTAX
+change $ID1 [MOVES|$ID2|@ID2]
+
+DESCRIPTION
+Changes the scramble $ID1 to either MOVES, the scramble $ID2, the output @ID2
+or, if none is specified, the moves entered by the user. The scramble that was
+memorized under $ID1 is then lost.
+Mnemonic: "change x to y", or just "change x".
+
+EXAMPLES
+change $1
+  The user is required to type the moves that will replace $1.
+change $2 $3
+  Saves the scramble that was saved under $3 in $2. Now $2 and $3 are the same
+  scrambles, and the old $2 is lost.
+change $1 U R
+  Saves U R as scramble $1.
+
diff --git a/docs/dr.txt b/docs/dr.txt
new file mode 100644
index 0000000..ddbd9aa
--- /dev/null
+++ b/docs/dr.txt
@@ -0,0 +1,45 @@
+
+HELP PAGE FOR COMMAND dr
+
+SYNTAX
+dr [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Solves DR for a given scramble. A scramble can be given as last argument of the
+command, or an ID of a saved scramble can be provided. If none of the two is
+given, a prompt will ask the user to input a new scramble.
+If the option "from" is given (see below), it solves DR from an EO (if edges
+are oriented) without breaking that EO.
+The first time this command is called without the option from (and, to some
+extent, also the first time it is called with the option from), nissy loads
+some pruning tables that were not loaded on startup, causing a small but
+noticeable delay.
+
+OPTIONS
+axis={fb,rl,ud}    Specify the axis for the DR. One to three axes can be given,
+                   comma separated, no spaces.
+                   Default: DR on any of the three axis (omitting the option is
+                   the same as specifying axis=fb,rl,ud).
+b=N                Specify a bound for the number of moves. N must be a number.
+                   Default value: 20.
+h                  Show hidden DRs.
+                   Default, if an DR ending in e.g. R is shown, the equivalent
+                   one ending in R' is hidden.
+from {fb|rl|ud}    Solve DR from the specified EO, which must be solved,
+                   without breaking the EO.
+niss               Use NISS. It works only if solving DR from EO.
+                   Default: does not use NISS.
+n=N                Specify a maximum number of EOs to be output. N must be a
+                   number.
+                   Default value: 1.
+
+EXAMPLES
+dr from rl axis=ud $1
+  Finds optimal DR on ud, starting from EO on rl, for the first saved scramble.
+
+dr niss from fb n=10 m=6 F2 R L B' F D U' R2 L' F D B
+  Finds up to 10 DRs of length at most 6 from EO on fb, possibly using NISS.
+
+dr n=100 axis=ud h
+  Finds 100 DRs on ud, including "hidden" DRs.
+
diff --git a/docs/drcorners.txt b/docs/drcorners.txt
new file mode 100644
index 0000000..8eb9729
--- /dev/null
+++ b/docs/drcorners.txt
@@ -0,0 +1,34 @@
+
+HELP PAGE FOR COMMAND drcorners
+
+SYNTAX
+drcorners [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Similar to drfinish, but only solves corners. CO must be solved. The scramble
+can be given as the last argument of the command, or it may be given as an $ID
+or @ID, or it can be typed out on the following line.
+
+OPTIONS
+from {ud|fb|rl}    Allows to specify on which axis the CO is solved. It is
+                   usually not necessary, since nissy will find a CO on any
+                   axis.
+i                  Ignores E-layer centers. By default cornersare solved
+                   relatively to centers; this options allows for solutions
+                   which solve corners relatively to each other and to the
+                   U and D sides, but not to the E layer (or any equivalent
+                   if the CO is not on U/D).
+b=N                Specify a bound for the number of moves. N must be a number.
+                   Default value: 20.
+n=N                Specify a maximum number of solutions to be output. N must
+                   be a number.
+                   Default value: 1.
+
+EXAMPLES
+drcorners n=3 R' D R2 D' R' U2 R D R' U2 R' D' R
+  Produces the following output:
+Found 3 results.
+@1:     U' F2 U R2 U2 F2 U F2 U R2 (10)
+@2:     U' F2 U R2 U2 B2 U R2 D R2 (10)
+@3:     U' F2 U R2 U2 B2 U L2 U L2 (10)
+
diff --git a/docs/drfinish.txt b/docs/drfinish.txt
new file mode 100644
index 0000000..efd12ac
--- /dev/null
+++ b/docs/drfinish.txt
@@ -0,0 +1,29 @@
+
+HELP PAGE FOR COMMAND drfinish
+
+SYNTAX
+drfinish [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Solves the given scramble using the DR moveset. DR must be solved. The scramble
+can be given as the last argument of the command, or it may be given as an $ID
+or @ID, or it can be typed out on the following line.
+
+OPTIONS
+from {ud|fb|rl}    Allows to specify on which axis the DR is solved. It is
+                   usually not necessary, since nissy will find a DR on any
+                   axis, but it can be useful if one want to e.g. solve an HTR
+                   state allowing quarter-turns from a specific DR.
+b=N                Specify a bound for the number of moves. N must be a number.
+                   Default value: 20.
+n=N                Specify a maximum number of solutions to be output. N must
+                   be a number.
+                   Default value: 1.
+
+EXAMPLES
+dr from ud R L' U2 R' L F2
+  Solves the given scramble using the moveset <U,D,R2,L2,F2,B2>. In this case:
+@1:     U2 R2 F2 R2 U2 R2 F2 R2 (8)
+drfinish b=7 n=10 $1
+  Finds (at most) 10 solutions of length at most 7 for the scramble $1.
+
diff --git a/docs/eo.txt b/docs/eo.txt
new file mode 100644
index 0000000..603c189
--- /dev/null
+++ b/docs/eo.txt
@@ -0,0 +1,38 @@
+
+HELP PAGE FOR COMMAND eo
+
+SYNTAX
+eo [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Solves EO for a given scramble. A scramble can be given as last argument of the
+command, or an ID of a saved scramble can be provided. If none of the two is
+given, a prompt will ask the user to input a new scramble.
+
+OPTIONS
+axis={fb,rl,ud}    Specify the axis for the EO. One to three axes can be given,
+                   comma separated, no spaces.
+                   Default: EO on any of the three axis (omitting the option is
+                   the same as specifying axis=fb,rl,ud).
+b=N                Specify a bound for the number of moves. N must be a number.
+                   Default value: 20.
+h                  Show hidden EOs.
+                   Default, if an EO ending in e.g. F is shown, the equivalent
+                   one ending in F' is hidden.
+niss               Use NISS.
+                   Default: does not use NISS.
+n=N                Specify a maximum number of EOs to be output. N must be a
+                   number.
+                   Default value: 1.
+
+EXAMPLES
+eo axis=fb $1
+  Finds one optimal EO on fb for the first saved scramble.
+
+eo n=5 b=4 U R F  
+  Finds up to 5 EOs of length at most 4 for scramble U R F.
+
+eo n=100 b=5 niss axis=fb,ud h  R' U' F L R'U'F
+  Finds up to 100 EOs of lenth at most 4, possibly using NISS, including
+  "hidden" EOs, excluding the rl axis.
+
diff --git a/docs/exit.txt b/docs/exit.txt
new file mode 100644
index 0000000..fb3d8f5
--- /dev/null
+++ b/docs/exit.txt
@@ -0,0 +1,9 @@
+
+HELP PAGE FOR COMMAND exit
+
+SYNTAX
+exit
+
+DESCRIPTION
+Exits nissy.
+
diff --git a/docs/help.txt b/docs/help.txt
new file mode 100644
index 0000000..6eeaa75
--- /dev/null
+++ b/docs/help.txt
@@ -0,0 +1,15 @@
+
+HELP PAGE FOR COMMAND help
+
+SYNTAX
+help [nissy|COMMAND]
+
+DESCRIPTION
+'help nissy' prints a general user manual. 'help COMMAND' prints a detailed
+help page for the command COMMAND, if it exists. 'help' prints a list of all
+available commands a short description for each.
+
+EXAMPLES
+help help
+  Prints this help page.
+
diff --git a/docs/htr.txt b/docs/htr.txt
new file mode 100644
index 0000000..7ed4d35
--- /dev/null
+++ b/docs/htr.txt
@@ -0,0 +1,30 @@
+
+HELP PAGE FOR COMMAND htr
+
+SYNTAX
+htr [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Finds HTR for a given scramble. DR must be solved. A scramble can be given as
+last argument of the command, or an ID of a saved scramble can be provided. If
+none of the two is given, a prompt will ask the user to input a new scramble.
+
+OPTIONS
+from {ud|fb|rl}    Allows to specify on which axis the DR is. This is usually
+                   not needed, since nissy will automatically find it out.
+b=N                Specify a bound for the number of moves. N must be a number.
+                   Default value: 20.
+h                  Show hidden HTRs.
+                   Default, if an HTR ending in e.g. R is shown, the equivalent
+                   one ending in R' is hidden.
+niss               Use NISS.
+                   Default: does not use NISS.
+n=N                Specify a maximum number of HTRs to be output. N must be a
+                   number.
+                   Default value: 1.
+
+EXAMPLES
+eo n=10 b=7 niss $1
+  Finds up to 100 HTRs of lenth at most 7, possibly using NISS, including
+  "hidden" HTRs, for scramble $1. DR must be solved.
+
diff --git a/docs/htrfinish.txt b/docs/htrfinish.txt
new file mode 100644
index 0000000..7b58307
--- /dev/null
+++ b/docs/htrfinish.txt
@@ -0,0 +1,23 @@
+
+HELP PAGE FOR COMMAND htrfinish
+
+SYNTAX
+htrfinish [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Similar to drfinish, but uses the moveset <U2,D2,R2,L2,F2,B2>. HTR must be
+solved. The scramble can be given as the last argument of the command, or it
+may be given as an $ID or @ID, or it can be typed out on the following line.
+
+OPTIONS
+b=N                Specify a bound for the number of moves. N must be a number.
+                   Default value: 20.
+n=N                Specify a maximum number ofsolutions to be output. N must be
+                   a number.
+                   Default value: 1.
+
+EXAMPLES
+htrfinish R L' U2 R' L F2
+  Produces the following solution:
+@1:     U2 R2 F2 R2 U2 R2 F2 R2 (8)
+
diff --git a/docs/invert.txt b/docs/invert.txt
new file mode 100644
index 0000000..e4644e4
--- /dev/null
+++ b/docs/invert.txt
@@ -0,0 +1,14 @@
+
+HELP PAGE FOR COMMAND invert
+
+SYNTAX
+invert [MOVES|$ID|@ID]
+
+DESCRIPTION
+Inverts a sequence of moves, which can be given also as $ID or @ID. The given
+sequence must not use NISS (if it does, use the command unniss first).
+
+EXAMPLES
+invert F R D'
+  Prints D R' F'
+
diff --git a/docs/nissy.txt b/docs/nissy.txt
new file mode 100644
index 0000000..de4744b
--- /dev/null
+++ b/docs/nissy.txt
@@ -0,0 +1,88 @@
+
+*******************************************************************************
+********************* NISSY: a cube solver and FMC helper *********************
+*******************************************************************************
+
+If you just want to solve the cube, type 'solve' followed by the scramble. This
+will not always give you an optimal solution, unless it is 10 moves or less or
+you use the "o" option. Finding the optimal solution might take very long if it
+is 16 moves or more, especially for the first time.
+
+Now the fun stuff. With nissy you can save and manipulate move sequences, for
+example:
+
+nissy-# save R' U' F
+$1:     R' U' F
+nissy-# add L2D' $1
+$1:     R' U' F L2 D'
+
+You can then ask nissy to solve certain substepson a saved scramble:
+
+nissy-# eo axis=rl $1
+@1:     U D F' R (4)
+
+And of course it uses also NISS, if you ask:
+
+nissy-# eo niss axis=rl $1
+@1:     (R) (1)
+
+Notice that the sequences you save are marked with a $, while the "output"
+sequences are marked with @. The difference between these two type of sequences
+is that those marked with @ are temporary and get lost once you get new output.
+Most commands accept as input either a move sequence typed out, a $-sequence or
+a @-sequence. For example, you can however save a @-sequence and make it
+persistent:
+
+nissy-# save @1
+$2:     (R)
+
+Nissy also understands NISS. Let's see a more complicated example where you
+save a scramble, ask for some EOs (using NISS) and then a DR on inverse:
+
+nissy-# save R' U' F R U R2 F2 R2 D R2 U L2 U R2 D2 B' D U' R D R' D U2 F2 R' U' F
+$3:     R' U' F R U R2 F2 R2 D R2 U L2 U R2 D2 B' D U' R D R' D U2 F2 R' U' F 
+nissy-# eo n=10 niss axis=fb,rl $3
+Found 10 results.
+@1:     (U' L B D F) (5)
+@2:     (U' L B' D F) (5)
+@3:     (L B U D F) (5)
+@4:     (L B' U D F) (5)
+@5:     R U B U L (5)
+@6:     R U' L (B L) (5)
+@7:     R U' B U L (5)
+@8:     R L (L B L) (5)
+@9:     R (U2 D' F R) (5)
+@10:    R (U2 F D' R) (5)
+nissy-# add @6 $3
+$3:     R' U' F R U R2 F2 R2 D R2 U L2 U R2 D2 B' D U' R D R' D U2 F2 R' U' F R U' L (B L) 
+nissy-# unniss $3
+@1:     L' B' R' U' F R U R2 F2 R2 D R2 U L2 U R2 D2 B' D U' R D R' D U2 F2 R' U' F R U' L 
+nissy-# invert @1
+@1:     L' U R' F' U R F2 U2 D' R D' R' U D' B D2 R2 U' L2 U' R2 D' R2 F2 R2 U' R' F' U R B L 
+nissy-# save @1
+$5:     L' U R' F' U R F2 U2 D' R D' R' U D' B D2 R2 U' L2 U' R2 D' R2 F2 R2 U' R' F' U R B L 
+nissy-# dr from rl $5
+@1:     F2 U D2 F' B D B (7)
+nissy-# 
+
+If you ask nissy to solve a substep (or the whole cube) using a sequence with
+NISS as scramble, it will first un-NISS it (but without saving the unNISSed
+scramble anywhere):
+
+print $3
+$3:     R' U' F R U R2 F2 R2 D R2 U L2 U R2 D2 B' D U' R D R' D U2 F2 R' U' F R U' L (B L) 
+nissy-# solve $3
+@1:     F U' R2 F2 U2 F U2 R2 L2 D R2 U B2 D' L2 D B2 D2 (18)
+
+Nissy knows how to solve certain common sub-steps for DR (or Thistlethwaite /
+Kociemba algorithms). For now it does know more common speedsolving methods.
+
+For a full list of commands type "help". For a more detailed help on a specific
+command, type "help (command)". The help pages can also be found in the docs
+folder.
+
+If you want to report a bug (I'm sure there are many!) or give a suggestion,
+you can send an email to sebastiano.tronto@gmail.com.
+
+Have fun!
+
diff --git a/docs/pic.txt b/docs/pic.txt
new file mode 100644
index 0000000..0285a2f
--- /dev/null
+++ b/docs/pic.txt
@@ -0,0 +1,20 @@
+
+HELP PAGE FOR COMMAND pic
+
+SYNTAX
+pic [MOVES|$ID|@ID]
+
+DESCRIPTION
+Prints the cube state after applying the given scramble.
+
+EXAMPLES
+pic R' U' F R U R2 F2 R2 D R2 U L2 U R2 D2 B' D U' R D R' D U2 F2 R' U' F 
+  Gives the following output:
+               UF  UL  UB  UR  DF  DL  DB  DR  FR  FL  BL  BR 
+EP:                      FR  UL  FL  UR  UF  DB  DR  BL  UB  BR  DL  DF 
+EO(F/B):              x   x   x   x       x           x   x   x     
+
+                           UFR  UFL  UBL  UBR  DFR  DFL  DBL  DBR 
+CP:                      UBR  UFR  DFL  DBL  UFL  UBL  DBR  DFR 
+CO(U/D):             ccw                  cw       ccw   cw
+
diff --git a/docs/pre.txt b/docs/pre.txt
new file mode 100644
index 0000000..c2cfd96
--- /dev/null
+++ b/docs/pre.txt
@@ -0,0 +1,18 @@
+
+HELP PAGE FOR COMMAND pre
+
+SYNTAX
+pre [MOVES|$ID1|@ID1] $ID2
+
+DESCRIPTION
+Prepends either MOVES, the scramble memorized under $ID1 or the output sequence
+memorized under @ID1 at the beginning of the scramble memorized under $ID2. If
+none of MOVES, $ID1 or @ID1 is specified, the user will be asked to type the
+moves.
+Menmonic: "pre(pend) x to y" or just "pre(pend) to y".
+
+EXAMPLES
+add $1
+  The user is required to type the moves that will be prepended to $1.
+add F R B $1
+  Prepends the moves F R B to scramble $1. Now scramble $1 begins with F R B.
diff --git a/docs/print.txt b/docs/print.txt
new file mode 100644
index 0000000..6c6c032
--- /dev/null
+++ b/docs/print.txt
@@ -0,0 +1,19 @@
+
+HELP PAGE FOR COMMAND print
+
+SYNTAX
+print [$ID|@ID]
+
+DESCRIPTION
+Prints memorized sequences. If no argument is given, it prints all memorized
+scrambles ($ only). If $ID or @ID is specified, it only prints the relative
+memorized sequence.
+
+EXAMPLES
+print
+  Prints a list of all memorized scrambles (only $).
+print $2
+  Prints the second memorized scramble.
+print @13
+  Prints the 13th sequence that was part of the output of the last command.
+
diff --git a/docs/quit.txt b/docs/quit.txt
new file mode 100644
index 0000000..5866358
--- /dev/null
+++ b/docs/quit.txt
@@ -0,0 +1,9 @@
+
+HELP PAGE FOR COMMAND quit
+
+SYNTAX
+quit
+
+DESCRIPTION
+Exits nissy.
+
diff --git a/docs/replace.txt b/docs/replace.txt
new file mode 100644
index 0000000..f147584
--- /dev/null
+++ b/docs/replace.txt
@@ -0,0 +1,22 @@
+
+HELP PAGE FOR COMMAND replace
+
+SYNTAX
+eo [OPTIONS] [MOVES|$ID|@ID]
+
+DESCRIPTION
+Looks for non-optimal subsequences and replaces them to shorten the given
+sequence. By default it tries to shorten every subsequence of up to 10 moves,
+but this can be change with the "b" option.
+It outputs at most 10 equivalent optimal sequences for each replaceable part.
+
+OPTIONS
+b=N                Finds non-optimal subsequences of up to N moves.
+
+EXAMPLES
+replace D2 F' D2 U2 F' L2 R2 U' D B2 D B2 U B2 F L2 R' F' D U' 
+  Produces the following output:
+Replace [ R2 U' D B2 D B2 ] (moves 7-12) with: [ D R2 D U' ] (-6+4)
+Replace [ R2 U' D B2 D B2 U ] (moves 7-13) with: [ D R2 D ] (-7+3)
+Replace [ U' D B2 D B2 U ] (moves 8-13) with: [ R2 D R2 D ] (-6+4)
+
diff --git a/docs/save.txt b/docs/save.txt
new file mode 100644
index 0000000..a19dc18
--- /dev/null
+++ b/docs/save.txt
@@ -0,0 +1,22 @@
+
+HELP PAGE FOR COMMAND save
+
+SYNTAX
+save [MOVES|@ID|$ID]
+
+DESCRIPTION
+Memorizes the scramble specified by MOVES, given as input or temporarily saved
+as @ID, where ID is a number ('help nissy' for for more on IDs). If an $ID is
+given, it makes a copy of the scramble. An identifier of the form $ID, where ID
+is a number, is assigned to the memorized scramble.
+
+EXAMPLES
+save R U R' U'
+  Saves the scramble R U R' U'.
+save F (B)
+  Saves the scramble F (B) (NISS notation).
+save @3
+  Saves the third output sequence of the last command.
+save $2
+  Makes a copy of the second saved scramble.
+
diff --git a/docs/solve.txt b/docs/solve.txt
new file mode 100644
index 0000000..1d83094
--- /dev/null
+++ b/docs/solve.txt
@@ -0,0 +1,33 @@
+
+HELP PAGE FOR COMMAND solve
+
+SYNTAX
+solve [MOVES|$ID|@ID]
+
+DESCRIPTION
+Solves the given scramble, which can be given as a sequence of moves or as $ID
+or @ID. If none is given, the user can type it on the next line.
+The algorithm first tries to find a short (<=10 moves) solution, and then
+switches to a 2-step algorithm (unless the option "o" is specified, in which
+case it keeps looking for an optimal solution).
+The first time it uses the 2-step algorithm it needs to load some tables, which
+can take a few seconds. It runs much faster after that. If the option "o" is
+specified, the first time it loads some large tables, which can take a minute
+or two.
+
+OPTIONS
+b=N                Only looks for solutions up to N moves.
+n=N                Tries to find multiple solutions, at most N. Multiple
+                   Solutions will only be found if they are <=10 moves.
+o                  Looks for optimal solution.
+
+
+EXAMPLES
+solve R' U' F
+  Solves the scramble R' U' F.
+solve o b=14 $1
+  Tries to solve the scramble $1 optimally, but stops if no solution of 14
+  moves or shorter is found.
+solve n=16 R L' U2 R' L F2
+  Finds the 16 shortest solutions for the scramble above.
+
diff --git a/docs/unniss.txt b/docs/unniss.txt
new file mode 100644
index 0000000..399dd74
--- /dev/null
+++ b/docs/unniss.txt
@@ -0,0 +1,14 @@
+
+HELP PAGE FOR COMMAND unniss
+
+SYNTAX
+unniss [MOVES|$ID|@ID]
+
+DESCRIPTION
+Removes NISS from a sequence of moves, which can be given also as $ID or @ID.
+A sequence of the form A (B) is translated to B' A.
+
+EXAMPLES
+invert F R (D' L2)
+  Prints L2 D F R
+