Sudoku: A plug-in for the Video Disk Recorder
---------------------------------------------

Copyright (C) 2005-2008, Thomas Günther <tom@toms-cafe.de>

Project's homepage: http://toms-cafe.de/vdr/sudoku

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

See the file COPYING for the full license information.


Requirements:
-------------

- VDR >= 1.3.47


Description:
------------

'Sudoku' is a VDR plug-in to generate and solve Number Place puzzles, so called
Sudokus.

A Sudoku puzzle consists of 9 x 9 cells subdivided into 9 regions with 3 x 3
cells. The rules are simple. There have to be the numbers from 1 to 9 in every
row, column and region. In the beginning some numbers are given. These cells are
painted with cyan background color. The aim of the puzzle is to find the missing
numbers. There is only one solution of a Sudoku puzzle.

The Sudoku puzzles are generated on-the-fly. The number of givens can be set in
the plug-in's setup page down to a minimum of 26 givens. The generation of
puzzles with less than 26 givens takes too long. By default the cells with
givens are symmetrically ordered. But this can be disabled in the setup.

To solve difficult Sudoku puzzles some hints can be used. Incorrect cells are
red and cells with ambiguous numbers are magenta. These hints can be disabled in
the setup. For further hints see the commands menu, which is opened with the
blue key.

Each time the plug-in is started from the main menu the same puzzle is shown. A
new puzzle is only generated on VDR startup or if it has been requested by
selecting this command in the commands menu.

In the commands menu you can load and save puzzles from/to the sudoku-list file.
This file is located at the plugins folder inside the configuration folder of
VDR. If you don't specify a configuration folder, your videodir is used (e.g.
/video0/plugins/sudoku/sudoku-list).

The sudoku-list file contains lines with a sudoku dump and an optional
description. The sudoku dump has to begin at the first position of the line.
The delimiter between sudoku dump and description is a space. All behind the
first space is considered as description.

A sudoku dump consists of up to three parts. The first part contains only the
givens, the second part all numbers set so far (including the givens), and the
third part the marked cells. They are delimited from each other by a colon. All
except of the first part is optional. The parts are strings with 81 digits or
underlines. An underline is considered as a zero. All other characters, except
of colons and spaces, which terminate the string, are ignored. They could be
used to structure the dump, e.g. plus signs after each 9 digits/underlines.


Setup:
------

- Givens count            Givens count of the generated puzzles.
                          Values: 26-81. Default: 36.
- Symmetric givens        Cells with givens are symmetrically ordered.
                          Values: yes/no. Default: yes.
- Mark errors             Incorrect cells are marked with red color.
                          Values: yes/no. Default: yes.
- Mark ambiguous numbers  Cells with ambiguous numbers are marked with magenta
                          color.
                          Values: yes/no. Default: yes.
- Show possible numbers as pattern
                          Show a pattern in all empty cells representing the
                          possible numbers. The pattern is structured by a small
                          3 x 3 grid featuring the numbers from 1 to 9 from top
                          left to bottom right. If a number is possible in this
                          cell the background of the corresponding grid section
                          is colored.
                          Values: yes/no. Default: no.
- Show possible numbers as digits (VDR >= 1.5.4)
                          Show digits in all empty cells representing the
                          possible numbers.
                          Values: yes/no. Default: no.
- Clear marks on reset    Unmark all cells when the puzzle is reset.
                          Values: yes/no. Default: no.
- Key Red                 Choose command for the red key.
                          Values: see commands menu. Default: Mark/unmark.
- Key Green               Choose command for the green key.
                          Values: see commands menu. Default: Undo last action.
- Key Yellow              Choose command for the yellow key.
                          Values: see commands menu. Default: Redo last action.
- Large font (VDR >= 1.5.4)
                          Choose font for the large digits.
                          Values: all installed fonts. Default: Sans Serif:Bold.
- Large font height (pixel) (VDR >= 1.5.4)
                          Font height for the large digits.
                          Values: 10-64. Default: 31.
- Large font width (pixel) (VDR >= 1.5.4)
                          Font width for the large digits.
                          Values: 10-64. Default: 42.
- Small font (VDR >= 1.5.4)
                          Choose font for the small digits.
                          Values: all installed fonts. Default: Sans Serif:Bold.
- Small font height (pixel) (VDR >= 1.5.4)
                          Font height for the small digits.
                          Values: 10-64. Default: 10.
- Small font width (pixel) (VDR >= 1.5.4)
                          Font width for the small digits.
                          Values: 10-64. Default: 14.
- Transparency (%)        Set the transparency of the menu.
                          Values: 0-100. Default: 50.


Keys:
-----

- Left/Right/Up/Down      Move the cursor in the puzzle.
- 1-9                     Set the number in the current cell.
- 0                       Remove the number from the current cell.
- Red                     Execute red key command.
- Green                   Execute green key command.
- Yellow                  Execute yellow key command.
- Blue                    Open the commands menu.
- Back                    Quit the plug-in.


Commands menu:
--------------

- Generate a new puzzle   Generate a random puzzle.
- Load a puzzle           Load a puzzle from the sudoku list. In the list menu
                          you can also delete sudokus from the list or edit the
                          descriptions.
- Save the puzzle         Add the puzzle to the sudoku list, together with an
                          optional description.
- Undo last action        Go one step backward in the history.
- Redo last action        Go one step forward in the history.
- Mark/unmark             Mark/unmark the current cell.
- Next cell               Move the cursor to the next free cell with minimal
                          possible numbers.
- Next number             Set the next possible number for the current cell -
                          reset the number if greater numbers are not possible.
- Reset the puzzle        Reset the numbers in all cells, excluding the givens.
- Open setup menu         Open the setup menu of the plug-in.
- Exit                    Quit the plug-in.


Cell colors:
------------

- Cyan                    Givens
- Green                   Marked cells
- Red                     Incorrect cells
- Magenta                 Ambiguous numbers