<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kubrick "<application>Kubrick</application>">
  <!ENTITY kappname "&kubrick;"><!-- Do *not* replace kappname-->
  <!ENTITY package "kdegames"><!-- kdebase, kdeadmin, etc -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
  
  
  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>
<!-- kdoctemplate v0.8 October 1 1999 
     Minor update to "Credits and Licenses" section on August 24, 2000
     Removed "Revision history" section on 22 January 2001
     Changed to Installation/Help menu entities 18 October 2001
     Other minor cleanup and changes 18 October 2001 -->


<!--
This template was designed by: David Rugge davidrugge@mindspring.com
with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
of the KDE DocBook team.

You may freely use this template for writing any sort of KDE documentation.
If you have any changes or improvements, please let us know.

Remember:
- in XML, the case of the <tags> and attributes is relevant ;
- also, quote all attributes.

Please don't forget to remove all these comments in your final documentation,
thanks ;-).
-->

<!-- ................................................................ -->

<!-- The language must NOT be changed here. -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &kubrick; Handbook</title>

<authorgroup>
<author>
<firstname>Ian</firstname>
<othername></othername>
<surname>Wadham</surname>
<affiliation>
<address><email>iandw.au at gmail com</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>



<copyright>
<year>2008</year>
<holder>Ian Wadham</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>2008-03-19</date>
<releaseinfo>0.3</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kubrick; is a game based on the <trademark>Rubik's Cube</trademark> puzzle.
The cube sizes range
from 2x2x2 up to 6x6x6, or you can play with irregular <quote>bricks</quote>
such as 5x3x2 or <quote>mats</quote> such as 6x4x1 or 2x2x1.  The game has a
selection of puzzles at several levels of difficulty, as well as demos of
pretty patterns and solution moves, or you can make up your own puzzles ...
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdegames</keyword> <!-- do not change this! -->
<keyword>game</keyword> <!-- do not change this! -->
<keyword>Kubrick</keyword>
<keyword>one player</keyword>
<keyword>Rubik</keyword>
<keyword>Cube</keyword>
<keyword>Rubik's Cube</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<note><title>Gametype:</title><para>Logic</para></note>

<note><title>Number of possible players:</title><para>One</para></note>

<para>&kubrick; is based on the famous <trademark>Rubik's Cube</trademark>
puzzle, invented by
Professor Erno Rubik in Hungary in the 1970s.  His original puzzle was a cube
that appeared to consist of 27 smaller colored cubes, called
<quote>cubies</quote>,
arranged in a 3x3x3 stack. When you turned the faces of the cube, the
colors of the cubies became shuffled and the challenge was to unshuffle
them, so that each face of the cube contained a single color.</para>

<para>In &kubrick; the cube sizes range from 2x2x2 (easy) up to 6x6x6 (very
hard), or you can play
with irregular <quote>bricks</quote> such as 5x3x2 and <quote>mats</quote>
(one cubie thick) such as 6x4x1.
The game has a selection of puzzles at several levels of difficulty,
as well as some demonstrations of pretty patterns and solution moves.  It is
also possible to make up your own puzzles.</para>

</chapter>

<chapter id="howto"><title>How to Play</title> <!-- do not change this! -->

<note><title>Objective:</title><para>Return all the pieces of the cube to
their starting positions after the computer has made several shuffling moves.
</para></note>

<para>&kubrick; starts with an animated demonstration that randomly chooses
cubes of various dimensions, shuffles them and solves them.  If you have
never seen a <trademark>Rubik's Cube</trademark> before, the demonstration
will give you
a general idea of how to play.  Just click anywhere with the mouse to
stop the demonstration and start playing.  You will then see a new puzzle
or the puzzle you were last working on, exactly as it was when you left it.
</para>

<para>&kubrick; has a choice of three views, showing one, two or three cubes,
all of which are the same cube viewed from different angles.  Use the
<guimenu>View</guimenu> menu or toolbar buttons to switch between views.</para>

<para>Use <menuchoice><guimenu>Game</guimenu><guisubmenu>Choose Puzzle Type
</guisubmenu></menuchoice> to choose the size of cube and degree of difficulty
for the type of puzzle you wish to try.  Then use <menuchoice><guimenu>Game
</guimenu><guimenuitem>New Puzzle</guimenuitem></menuchoice> each time you
wish to re-shuffle the cube and start a new puzzle of that type.</para>

<sect1 id="making-moves">
<title>Making Moves</title>

<para>You can use either the mouse or the keyboard to move the cube.</para>

<para>Use the left mouse-button or keyboard to rotate single slices of the
cube around any axis, as when solving a puzzle.  Square slices (e.g. 4x4 cubies)
rotate by 90 degrees at a time.  Rectangular slices (e.g. 5x3 cubies) rotate
by 180 degrees.</para>

<para>Use the right mouse-button to rotate the whole cube around any axis.
Or use the <keycap>C</keycap> key, within a keyboard sequence.  Such moves
do not lead to a solution of the puzzle, but you might use them to
examine the current position more closely or to get the cube into position for
a sequence of solution moves, such as untwisting two corners.</para>

<para>All moves, however they are made, are displayed progressively in
the toolbar using the widely-recognized Singmaster Notation. See the section
<link linkend="singmaster-moves">Singmaster Moves</link> for more details.
</para>
</sect1>

<sect1 id="mouse-moves">
<title>Using the Mouse to Move</title>

<para>To move using the mouse, click the left or right mouse button on
any colored sticker on any cubie in the view, hold the button down, drag
and let go.</para>

<para>When using the left button, the sticker and a whole slice
of the cube will move in the direction you indicated.  The slice tilts
slightly to help you see what will happen when you let go.  If you are
not happy with that, just move the mouse back to where you started.</para>

<para>If you are using the right button, the mouse pointer sticks to the
cube and the whole cube rotates with it until you release the button.
</para>
</sect1>

<sect1 id="keyboard-moves">
<title>Using the Keyboard to Move</title>

<para>There are two styles of keyboard moves: XYZ moves, described here, and
Singmaster moves, which are described in the section
<link linkend="singmaster-moves">Singmaster Moves</link>.</para>

<para>To move the cube with XYZ, first use key <keycap>X</keycap>,
<keycap>Y</keycap> or <keycap>Z</keycap> to select an axis.
On the screen, the X axis runs from left to right, the Y axis from bottom
to top and the Z axis towards you from behind the screen.  Now, to move the
whole cube use key <keycap>C</keycap> or to move a slice use keys
<keycap>1</keycap> to <keycap>6</keycap> (to select a slice number).</para>

<para>Finally use the left-arrow key for anti-clockwise rotation and
right-arrow for clockwise.  The slice that is going to move (numbered
1 to 6) will blink, until you hit an arrow key.</para>

<para>You can make further moves by using one, two or
three of the above keys.  For example, to move the same slice again,
just hit an arrow key.</para>

<para>If you have used the right mouse button to rotate the cube, the meanings
of X, Y and Z may have changed, so the cube is automatically realigned, using
the <menuchoice><guimenu>Move</guimenu>
<guimenuitem>Realign Cube</guimenuitem></menuchoice> action, before the
keyboard move you have requested can be executed.</para>
</sect1>

<sect1 id="singmaster-moves">
<title>Singmaster Moves</title>

<para>Professor David Singmaster, an English mathematician, was one of the
first to investigate <trademark>Rubik's Cube</trademark> and its relationship
to the branch of mathematics known as Group Theory.  In his book,
<quote>Notes on Rubik's 'Magic Cube'</quote>, Fifth Edition, published
in 1980, he sets out a way of describing sequences of cube moves briefly.
Mathematicians call this a <quote>notation</quote> and Singmaster's Notation
is now widely used internationally in books and on websites when discussing
problems and solutions in <trademark>Rubik's Cube</trademark> puzzles.  For
example, see the Wikipedia article and its links on the subject of
<trademark>Rubik's Cube</trademark>.</para>

<para>The &kubrick; program uses a modified form of Singmaster Notation to
display all moves, by whatever method they are made, using an area of the
toolbar. It also allows moves to be entered from the keyboard in Singmaster
Notation. The notation has been modified for use on larger cubes, bricks and
mats than the original size 3 cube and to allow convenient entry from the
keyboard, without clashing with &kubrick; shortcuts or other actions.</para>

<para>Briefly, Singmaster imagines that you are looking at the cube from
slightly above and to the right of it, exactly as in the standard Front View
of &kubrick;.  You can see three faces at the top, front and right of the cube
and these Singmaster has called (in English) <quote>Up</quote>,
<quote>Front</quote> and <quote>Right</quote>, or <quote>U</quote>,
<quote>F</quote> and <quote>R</quote> for short. The three faces you cannot
see, which are on the Back View in &kubrick;, are at the bottom, back and left
of the cube and Singmaster calls these (in English) <quote>Down</quote>,
<quote>Back</quote> and <quote>Left</quote>, or <quote>D</quote>,
<quote>B</quote> and <quote>L</quote> for short. Singmaster uses U and D
for the top and bottom faces because B is reserved for the back face.</para>

<para>This is all summarised in the table below: now to the moves. A single
letter or keystroke from UFRDBL represents a clockwise move of that face
through a right angle (90 degrees) for a square face or through 180 degrees
for a rectangular face (as on a brick or mat).  Here is where it gets tricky.
</para>

<para><quote>Clockwise</quote> means clockwise when you are looking directly
at that face. That is easy enough with the UFR faces you can see, but the
faces you cannot see appear to move anti-clockwise when you use DBL moves.
That is because you are looking at them from behind. On &kubrick;'s Back
View, the DBL moves will be seen to go clockwise, as expected. Rather than
trying to imagine yourself looking at the back of the cube when making DBL
moves, it might be easier to think of them going anti-clockwise in the
normal Front View.</para>

<para>
<segmentedlist><title>Singmaster Notation (Modified)</title>
<?dbhtml list-presentation="table"?>
<segtitle>Key</segtitle><segtitle>Meaning</segtitle>
<seglistitem><seg>R</seg><seg>Right face. In English, R is for
				<quote>Right</quote>.</seg></seglistitem>
<seglistitem><seg>L</seg><seg>Left face. In English, L is for
				<quote>Left</quote>.</seg></seglistitem>
<seglistitem><seg>U</seg><seg>Up or top face. In English, U is for
				<quote>Up</quote>.</seg></seglistitem>
<seglistitem><seg>D</seg><seg>Down or bottom face. In English, D is for
				<quote>Down</quote>.</seg></seglistitem>
<seglistitem><seg>F</seg><seg>Front face. In English, F is for
				<quote>Front</quote>.</seg></seglistitem>
<seglistitem><seg>B</seg><seg>Back face. In English, B is for
				<quote>Back</quote>.</seg></seglistitem>
<seglistitem><seg>'</seg><seg>Suffix for a reverse or anti-clockwise move. R'
				is the reverse of R.</seg></seglistitem>
<seglistitem><seg>2</seg><seg>Suffix for double move. R2 rotates R twice.
				</seg></seglistitem>
<seglistitem><seg>+</seg><seg>Suffix for two-face move. R+ is RL' in another
				form.</seg></seglistitem>
<seglistitem><seg>-</seg><seg>Suffix for anti-two-face move. R- is RL in another
				form.</seg></seglistitem>
<seglistitem><seg>.</seg><seg>Prefix for inner-slice move. <quote>.R</quote> is
				one step in from the R face.</seg></seglistitem>
<seglistitem><seg>C</seg><seg>Prefix for whole-cube move. In English, C is for
				<quote>Cube</quote>.</seg></seglistitem>
</segmentedlist>
</para>

<para>Singmaster uses a letter followed by an apostrophe to represent an
anti-clockwise or reverse move of a face. Mathematicians would say F' as
<quote>F prime</quote> or <quote>F dash</quote> and it indicates an
anti-clockwise move of the front face.</para>

<para>&kubrick; cannot tell if you are going to type an apostrophe,
another letter or some other symbol after a letter, so it will not make a
clockwise move of a face immediately after you type the letter. You can force
&kubrick; to move by hitting the Return or Enter key.
You can also use the space bar and it will leave a space in the display of
moves, allowing you to separate groups of moves for readability.</para>

<para>On cubes, bricks or mats of size 3 or more, you might wish to
move an inner slice, rather than a face. To do this, type one or more periods
or dots before the face letter. For example, ..F moves the slice that is two
layers behind the front face and ..B would move the slice two layers in
front of the back face, assuming there are 5 or 6 layers that can move. The
reverse of those moves would be ..F' and ..B'.</para>

<para>Finally, the C prefix moves the whole cube in the same way as a face.
For example, CF moves the cube clockwise along with the front face and CF'
moves it anti-clockwise.</para>

<para>If you have previously rotated the cube by hand, using the right mouse
button, and you then make a Singmaster or other keyboard move, the cube will
be realigned automatically to standard UFR view and some C moves will be
generated and displayed. This ensures that you and &kubrick; have the same
idea of top, front and right. Similar moves are generated when you use the
<menuchoice><guimenu>Move</guimenu><guimenuitem>Realign Cube
</guimenuitem></menuchoice> menu item or the Home icon on the toolbar.</para> 
</sect1>
</chapter>

<chapter id="rules_and_tips"><title>Game Rules, Strategies and Tips</title> <!-- do not change this! -->

<sect1 id="rules">
<title>Rules</title>

<para>There are no rules in &kubrick; other than having to move one slice at
a time until all the cubies and their stickers are back in their original
positions.  No other rules are necessary, because the way the cube is built
makes it almost impossible to perform any other moves.</para>

<para>In the original 3x3x3 <trademark>Rubik's Cube</trademark>, the inside
of the cube contained an
ingenious mechanism that made it possible to turn groups of 9 cubies (3x3)
called <quote>slices</quote>, all at once as a group.  To make any other
moves you had to physically break the cube or take it apart and re-assemble
it.  The equivalent in &kubrick; would be to change the source program.</para>
</sect1>

<sect1 id="complexity">
<title>The Complexity of the Puzzle</title>

<para>The outside faces of the cubies have stickers of 6 different colors,
one for each of the 6 faces of the main cube.  As you rotate the slices, the
stickers become shuffled and the faces of the main cube become a jumble
of colors.  It looks like a simple puzzle, but as you move further away
from the starting position, you begin to realise, as one writer put it,
that you are like a small child who has let go of a helium balloon only
to see it move more and more beyond reach or hope of return.</para>

<para>Mathematicians calculate that a 3x3x3 cube can be shuffled into
43,252,003,274,489,856,000 different patterns, yet they conjecture that all
positions can be solved in 20 moves or less.  The method that can do that
(as yet undiscovered) is called God's Algorithm.  Practical methods can take
more than 100 moves.  As there are 12 face-move possibilities at each
step, the chances of solving the cube by trial and error are rather remote.
Some cubes have 9-part pictures on the faces and that makes them even more
complex, because you then have to get the orientations of the stickers
correct as well as the positions.</para>
</sect1>

<sect1 id="strattips">
<title>Strategies and Tips</title>

<para>&kubrick; shuffles the cube by a pre-selected number
of random moves when setting a puzzle.  The difficulty depends on how many
cubies there are in your cube, how many shuffling moves there are and whether
you can view the shuffling moves as they happen.</para>

<para>One kind of puzzle has a small number of shuffling moves (3, 4 or 5) and
the idea is to solve the cube in that number of moves (or less).  This is fun,
challenging and quite quick to play.</para>

<para>Then there is the traditional puzzle, with 10 to 20 or more shuffling
moves.  The 3x3x3 cube has been very well explored and written about, but
other sizes are not so well known and understood.</para>

<para>&kubrick; also has bricks and mats you can play with.  Some of them are
easier to solve than cubes and could be fun for children too.</para>

<para>Another game you can try is to find pretty patterns for sizes other
than 3x3x3.</para>

<para>&kubrick; can be used as a <quote>laboratory</quote> for studying cubes
and finding sequences of solution moves, since all moves can be
undone or redone to any degree, either instantaneously or at a selectable
speed of animation.</para>

<para>It is also possible to save and restore a partly
solved cube at any time and the current state of the cube is automatically
saved and restored when you quit and restart &kubrick;.</para>

<para>On a cube with an odd number of cubies per face, the stickers at the
centres of the six faces maintain their positions relative to each other,
regardless of how you move.  You can use those centres as anchors or guide
posts for your moves.</para>

<para>The <guimenu>Settings</guimenu> menu has options to turn animations
on or off and to vary the speed of animations.  These can be useful when
trying to follow a sequence of moves and understand what is happening.</para>

<para>If you are in real trouble, &kubrick; has a <quote>solve</quote> action
which appears to show God's Algorithm in animated form then reshuffles the
cube.  Actually the computer cheats.  It remembers the shuffling moves and
then just undoes and redoes them.</para>

<para>Another source of ideas is the <menuchoice><guimenu>Demos</guimenu>
<guisubmenu>Solution Moves</guisubmenu></menuchoice> menu item.  One
systematic way to solve a cube is to solve the bottom layer first, then
the edge cubies in the middle layer and finally the top layer.  The demos
show sequences of moves on the 3x3x3 cube that will rearrange a few cubies
at a time, without messing up parts of the cube you have already solved.
One of the demos plays a complete solution of an example cube, using these
methods, but it requires over 100 moves.</para>
</sect1>

</chapter>

<chapter id="interface"><title>Interface Overview</title> <!-- do not change this! -->
<!-- This section has to do with menubar. Describe every single entry in order. Use <variablelist> and <varlistentry>. Split the chapter into sections using <sect1(2,3)> for better viewing.-->

<sect1 id="game-menu">
<title>The <guimenu>Game</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycap>N</keycap></shortcut>
<guimenu>Game</guimenu><guimenuitem>New Puzzle</guimenuitem>
</menuchoice>
<menuchoice> <!-- Alternate shortcut, empty guimenu text to satisfy parser.-->
<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
</shortcut><guimenu></guimenu>
</menuchoice></term>
<listitem><para><action>Generate a new puzzle of the type currently selected.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu><guimenuitem>Load Puzzle...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Load a previously saved puzzle, with all of its
dimensions, settings, current state of the cube and history of moves, using
a file selection dialog box to locate the required file.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Shift;<keycap>U</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu><guimenuitem>Restart Puzzle</guimenuitem>
</menuchoice></term>
<listitem><para><action>Undo all previous moves and start again.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu><guimenuitem>Save Puzzle...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Save the current puzzle, with all of its
dimensions, settings, current state of the cube and history of moves, using
a file selection dialog box to name a new file if the puzzle has not
previously been saved and loaded.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Game</guimenu><guimenuitem>Save Puzzle As...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Save the current puzzle under a new file name, with
all of its dimensions, settings, current state of the cube and history of
moves, using a file selection dialog box.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Game</guimenu><guisubmenu>Choose Puzzle Type</guisubmenu>
</menuchoice></term>
<listitem><para><action>Choose a type of puzzle to play from a series of
sub-menus graded by difficulty, based on cube dimensions and number of
shuffling moves, or use sub-menu item Make your own...
to create your own puzzle, using a dialog box.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>Game</guimenu><guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quit</action> &kubrick;, automatically saving the
current puzzle's dimensions, settings, state of the cube and history of moves.
</para></listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="move-menu">
<title>The <guimenu>Move</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu><guimenuitem>Undo</guimenuitem></menuchoice></term>
<listitem><para>Undo a previous move (repeatedly if required).</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu><guimenuitem>Redo</guimenuitem></menuchoice></term>
<listitem><para>Redo a previously undone move (repeatedly if
required).</para></listitem>
</varlistentry>

<!--Main Demo Ctrl+D -->

<varlistentry>
<term><menuchoice><shortcut><keycap>S</keycap></shortcut>
<guimenu>Move</guimenu><guimenuitem>Solve</guimenuitem></menuchoice></term>
<listitem><para>Solve the cube.  This shows all your moves being undone,
then all the shuffling moves being undone and then the shuffling moves
being re-done, leaving you set up to have another go at the
puzzle.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Shift;<keycap>U</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu><guimenuitem>Restart Puzzle</guimenuitem>
</menuchoice></term>
<listitem><para><action>Undo all previous moves and start again.
</action></para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut> 
<keycombo action="simul">&Shift;<keycap>R</keycap></keycombo>
</shortcut>
<guimenu>Move</guimenu><guimenuitem>Redo All</guimenuitem></menuchoice></term>
<listitem><para>Redo all previously undone moves.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><shortcut><keycap>Home</keycap></shortcut>
<guimenu>Move</guimenu><guimenuitem>Realign Cube</guimenuitem>
</menuchoice></term>
<listitem><para>Adjust the orientation of a rotated cube by the minimum amount
needed to make the rotations a combination of 90 degree moves, thus setting
the axes parallel to the XYZ axes.  In addition, some whole-cube 90 degree
moves are inserted in your list of moves to achieve the desired effect.</para>

<para>This is to standardise the view's perspective so that the top, front
and right sides are visible together and keyboard moves become properly
meaningful.  The inserted moves can be undone and redone, exactly as if
you had made them directly yourself.</para>

<para>For example, if you have used the right mouse-button to turn the cube
upside-down, the top or Up (U) face is now what used to be the bottom or
Down (D) face and what used to be the Y axis is pointing downwards.
In this situation, <menuchoice><guimenu>Move</guimenu>
<guimenuitem>Realign Cube</guimenuitem></menuchoice> will redefine the
faces and axes so that the new top face is known as Up (U) and the Y axis is
again the one that points upwards.</para></listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="view-menu">
<title>The <guimenu>View</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu><guimenuitem>1 Cube</guimenuitem>
</menuchoice></term>
<listitem><para>Show a view of the front of the cube.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu><guimenuitem>2 Cubes</guimenuitem>
</menuchoice></term>
<listitem><para>Show views of the front and back of the cube.  Slice moves
and rotations can be performed on either picture and the other will move
simultaneously.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu><guimenuitem>3 Cubes</guimenuitem>
</menuchoice></term>
<listitem><para>Show a large view of the front of the cube and two smaller
views of the front and back.  Slice moves can be performed on any of the
pictures and the others will move simultaneously, but only the large one can
be rotated.</para></listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="demos-menu">
<title>The <guimenu>Demos</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>
</shortcut>
<guimenu>Demos</guimenu><guimenuitem>Main Demo</guimenuitem>
</menuchoice></term>
<listitem><para>Run the Main Demo, in which a cube changes shape, shuffles
and solves itself as it rotates at random.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Demos</guimenu><guisubmenu>Pretty Patterns</guisubmenu>
</menuchoice></term>
<listitem><para>Show a sub-menu in which pretty patterns on the 3x3x3 cube
can be selected and the moves to create them are demonstrated.  There is also
an Info item that tells you a little more about such patterns.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Demos</guimenu><guisubmenu>Solution Moves</guisubmenu>
</menuchoice></term>
<listitem><para>Show a sub-menu in which sequences of moves used to solve the
3x3x3 cube can be selected and the sequences are demonstrated.  There is also
an Info item that tells you a little more about such solution moves.
</para></listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="settings-menu">
<title>The <guimenu>Settings</guimenu> Menu</title>
<variablelist>

<varlistentry>
<term><menuchoice><shortcut><keycap>W</keycap></shortcut>
<guimenu>Settings</guimenu><guimenuitem>Watch Shuffling</guimenuitem>
</menuchoice></term>
<listitem><para>Show animations of shuffling moves as they occur.  This is
an aid for beginners, but might be a form of cheating for experienced players.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice><shortcut><keycap>O</keycap></shortcut>
<guimenu>Settings</guimenu><guimenuitem>Watch Your Own Moves</guimenuitem>
</menuchoice></term>
<listitem><para>Show animations of your own moves as they occur.  This is
an aid for beginners, because it slows down the animations.  Experienced
players can turn this option off and moves are then animated at high speed,
taking about a tenth of a second to turn 90 degrees.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Show Toolbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the display of the toolbar.</action>
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Show Statusbar</guimenuitem>
</menuchoice></term>
<listitem><para><action>Toggle the display of the status bar.</action>
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Open a dialog where you can configure the shortcut
keys</action> for &kubrick;.</para></listitem>
</varlistentry>

<varlistentry id="settings-menu-toolbar">
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>Configure Toolbars...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Open a dialog where you can configure the toolbar
actions</action> for &kubrick;.</para></listitem>
</varlistentry>

<varlistentry id="settings-menu-configure">
<term><menuchoice>
<guimenu>Settings</guimenu><guimenuitem>&kubrick; Game Settings</guimenuitem>
</menuchoice></term>
<listitem><para>Open a game settings dialog. See
<link linkend="configuration">Game Configuration</link> section for more
details.</para></listitem>
</varlistentry>

</variablelist>
</sect1>

<sect1 id="help-menu">
<title>The <guimenu>Help</guimenu> Menu</title>

<!-- Assuming you have a standard help menu (help, what's this, about -->
<!-- &kubrick;, about KDE) then the documentation is already written. -->
<!-- The following entity is valid anywhere that a variablelist is -->
<!-- valid.  -->

&help.menu.documentation;

</sect1>
</chapter>

<chapter id="faq"><title>Frequently Asked Questions</title> <!-- do not change this! -->
<!--This chapter is for frequently asked questions. Please use <qandaset> <qandaentry> only!-->

<qandaset>
<!--Following is a standard list of FAQ questions.-->

<qandaentry>
<question><para>How do I pause the game?</para></question>
<answer><para>&kubrick; does not have a <quote>Pause</quote> feature, because
none is required.  If a demo is running, just click anywhere to stop it.</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>Can I change the way this game looks?</para></question>
<answer><para>Currently you can change the view, using the <guimenu>View
</guimenu> menu, the amount and speed of animation and the bevel on the edges
of the cubies, using the <guimenu>Settings</guimenu> menu.</para></answer>
</qandaentry>

<qandaentry>
<question><para>I have made a mistake. Can I undo?</para></question>
<answer><para>Yes. This is one of the strengths of &kubrick; as compared to
a real puzzle.  You can undo and redo moves to any level, or undo
all moves and start again.  To undo and redo moves, use the
<guimenu>Move</guimenu> menu or the corresponding keyboard shortcuts and
toolbar buttons.
</para></answer>
</qandaentry>

<qandaentry>
<question><para>Can I use the keyboard to play this game? </para></question>
<answer><para>Yes. &kubrick; has keyboard moves based on the X, Y and Z axes
and others based on Singmaster notation, which uses one-letter abbreviations
for Front, Back, Left, Right, Up and Down faces of the cube.</para></answer>
</qandaentry>

<qandaentry>
<question><para>I cannot figure out what to do here! Are there hints?</para>
</question>
<answer><para>No. However, the 3x3x3 <trademark>Rubik's Cube</trademark>
has been extensively
analysed and you can find solution methods on the Internet and in menu item
<menuchoice><guimenu>Demos</guimenu><guisubmenu>Solution Moves</guisubmenu>
</menuchoice> (<quote>Info</quote> item and demonstrations of moves).</para>
</answer>
</qandaentry>

<qandaentry>
<question><para>I have to quit the game now.  Can I save my position?</para>
</question>
<answer><para>Yes. In fact your position is saved automatically when you quit,
just as when you put a real cube back on the shelf. You can also save a
particular position by using menu item <menuchoice><guimenu>Game</guimenu>
<guimenuitem>Save Puzzle...</guimenuitem></menuchoice> and the corresponding
shortcut keys and toolbar button.</para></answer>
</qandaentry>

<qandaentry>
<question><para>How do I restore the game I saved?</para></question>
<answer><para>Your automatically saved game is restored automatically when you
start &kubrick;. To load other saved games, use <menuchoice><guimenu>Game
</guimenu><guimenuitem>Load Saved Puzzle...</guimenuitem></menuchoice> and the
corresponding shortcut keys and toolbar button.</para></answer>
</qandaentry>

<qandaentry>
<question><para>Where are the high scores?</para></question>
<answer><para>&kubrick; does not have such a feature.</para></answer>
</qandaentry>

</qandaset>

</chapter>

<chapter id="configuration"><title>Game Configuration</title> <!-- do not change this! -->

<para>To open a configuration (settings) dialog use one of the menubar items:
<menuchoice><guimenu>Settings</guimenu><guimenuitem>&kubrick; Game
Settings...</guimenuitem></menuchoice> or <menuchoice><guimenu>Game</guimenu>
<guisubmenu>Choose Puzzle Type</guisubmenu></menuchoice>, sub-menu
<guimenuitem>Make Your Own...</guimenuitem> Only the latter dialog has the
options to change the cube dimensions and shuffling difficulty. Below is
a list of the options available.</para>

<variablelist>

<varlistentry><term><guilabel>Watch shuffling in progress?</guilabel></term>
<listitem><para><action>Provides an animated view of the cube
when it is being shuffled by the &kubrick; program.</action>  You can
select the speed of animation.</para>
</listitem></varlistentry>

<varlistentry><term><guilabel>Watch your moves in progress?</guilabel></term>
<listitem><para><action>Provides an animated view of your own
moves at a speed you can select.</action></para>
</listitem></varlistentry>

<varlistentry><term><guilabel>Speed of moves:</guilabel></term>
<listitem><para><action>Sets the speed at which animations go.
</action>  The range is 1 to 15 degrees of turn per animation frame.</para>
</listitem></varlistentry>

<varlistentry><term><guilabel>% of bevel on edges of cubies:</guilabel></term>
<listitem><para><action>Sets the percentage of bevelled edge on
each cubie, relative to the size of the colored stickers.</action>  It affects
the overall shape of each cubie.  The range is from 4% to 30%.</para>
</listitem></varlistentry>

<varlistentry><term><guilabel>Cube dimensions:</guilabel></term>
<listitem><para><action>Sets the three dimensions of the cube,
brick or mat in cubies per side.</action>  Dimensions can range from 2x2x1
up to 6x6x6: the larger the dimensions, the harder the puzzle.  Only
one of the dimensions can be 1, otherwise the puzzle becomes too easy.</para>
</listitem></varlistentry>

<varlistentry><term><guilabel>Moves per shuffle (difficulty):</guilabel></term>
<listitem><para><action>Sets the number of moves the
&kubrick; program will use to shuffle the cube.</action>  The number can range
from 0 to 50: the more moves, the harder the puzzle.  2, 3 or 4 shuffling moves
make for relatively easy puzzles, especially if the shuffling moves can be
watched.</para>

<para>Selecting zero moves can be useful if you wish to experiment with
different sequences of moves and what they do to the cube, such as when you
are searching for pretty patterns or new solving moves.</para>
</listitem></varlistentry>

</variablelist>

</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&kubrick; is Copyright 2008 Ian Wadham <email>ianw@netspace.net.au</email>
</para>

<para>
&kubrick; was inspired by Professor Erno Rubik's famous <trademark>Rubik's Cube
</trademark> puzzle.
</para>

<para>
The programming is original work in C++ but owes several good ideas to the
Rubik XScreensaver, a C program by Marcelo Vianna, and GNUbik, a C program
by John M. Darrington.
</para>

<para>
Documentation Copyright 2008 Ian Wadham <email>ianw@netspace.net.au</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->
&underGPL;        	 <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

&install.intro.documentation;

<sect1 id="Compilation">
<title>Compilation and Installation</title>

&install.compile.documentation;

<para>
&kubrick; uses OpenGL 3-D graphics and requires the GL and
GLU libraries.  These are available with most &Linux; distributions and are
often installed by default.
</para>

</sect1>
</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab 
-->

