package Games::Sudoku::Trainer::General_info;

use version; our $VERSION = qv('0.02');    # PBP

1;

__END__

=head1 NAME

SudokuTrainer

This program helps to train the detection of successful Sudoku solution strategies.
It may also be used to get over an obstacle in a partially solved Sudoku puzzle.

=head1 VERSION

This documentation refers to SudokuTrainer version 0.01.5.

=head1 PURPOSE

SudokuTrainer helps the user in solving classical 9x9 Sudoku puzzles.
It does this in two areas:

1. Help to train a Sudoku strategy

2. Help to overcome an obstacle while solving a Sudoku puzzle

SudokuTrainer is not a Sudoku teacher.
The user must know the strategy that he wants to train.
People who don't know about Sudoku strategies may still use SudokuTrainer for 
the second purpose, just to get a new value for continuation.

=head1 USAGE

C<sudokutrainer [Sudoku_file] [--prio=priority-list]>

=head1 OPTIONS

=over 4

=item * Sudoku_file

The path of a Sudoku file to be used for training.

If this option is omitted,
SudokuTrainer will ask for it.
You will get the following choices:

    Read from file
    Insert manually
    Read example file

A doubleclick on a choice will select it and 
close the selection window. When you select the choice 
I<Insert manually> the utility program
B<enter_presets.pl> gets started. To see the documentation of 
it, use "perldoc enter_presets.pl". 
After you entered the initial puzzle manually, 
you should better save it. Chances are good that 
you will need it several times. Corrections to 
the initial puzzle can also be made with 
B<enter_presets.pl>.

=item * --prio=priority-list

The path to a file where a I<priority list> has been stored.

=back

=head1 TERMINOLOGY

=over 4

=item * cell

A cell is one of the 81 squares in a Sudoku board that will each finally
show a digit from 1 to 9.

=item * row

A row is a horizontal line of 9 cells. Rows are numbered from 1 to 9,
top to bottom.

=item * column

A column is a vertical line of 9 cells. Columns are numbered from 1 to 9,
left to right.

=item * block

A block is one of the 9 3x3 subsquares of a Sudoku board. Blocks are
numbered according to the following scheme:

    1 2 3
    4 5 6
    7 8 9

=item * line

A line is either a row or a column.

=item * unit

A unit is either a line or a block.

=item * candidate

A digit is a candidate of a cell if it is currently not yet forbidden
to use it as the value of the cell.

For more difficult Sudoku puzzles it may be helpful to inspect a list of
all still possible (or already excluded) candidates. You may 
view the internal candidate list of SudokuTrainer for this purpose 
(see section L<Games::Sudoku::Trainer::Training/View>).

=item * strategy

A strategy is a systematic collection of patterns which 
the player of a Sudoku puzzle tries to detect in the 
current state of the puzzle. The strategy is named 
successful if its detection allows for the exclusion of 
one or more candidates from some cells.

=item * priority

Each strategy has a priority assigned. The priorities give 
the sequence in which SudokuTrainer tries the stragegies. 
Stragegies that are considered as easy by the user are 
usually assigned a high priority.

A B<priority list> is a list of all strategies (exept 
I<Full house>), ordered by their priorities. The user may 
rearrange the strategies, thus changing their priorities 
(see section L<Games::Sudoku::Trainer::Training/Priorities>). 
He may also save the priority list for later reuse.

=back


=head1 NAMES OF CELLS AND UNITS

These names are used in communications with the user.

=over 4

=item * units

Units are named by a character that gives the unit type 
(I<r> for row, I<c> for column, I<b> for block), 
followed by the unit number. 
E. g. c1 is the leftmost column of the Sudoku board.

=item * cells

Cells are named by concatenating the names of the 
row and column that cross at the cell. 
E. g. r1c9 is the upper right cell of the Sudoku board.

=back



=head1 GUIDE TO DOCUMENTATION

The documentation for SudokuTrainer is broken up into sections:

=head2 General information

This is the document you are currently reading. It describes 
basic usage and the terminology that is needed for the 
communication with SudokuTrainer.

=head2 Train a strategy

The document L<Games::Sudoku::Trainer::Training> describes the 
operation of SudokuTrainer from a user point of view.

SudokuTrainer has a list of all strategies that it knows 
about. Easy strategies are near the top, the most difficult 
ones near the end of this list. SudokuTrainer starts the 
solution of a given puzzle with the easiest strategy and 
proceeds until it finds the strategy that the user wants 
to train. Here it pauses without showing the find. 
It's time to train.

=head2 Overcome an obstacle

The document L<Games::Sudoku::Trainer::Obstacle> 
describes how the user 
lets SudokuTrainer find the next value step by step. He can 
comprehend each step with minimum help by SudokuTrainer.

=head2 Get a further value

The document L<Games::Sudoku::Trainer::Nextvalue> 
describes how the user 
lets SudokuTrainer find value by value, until the find 
hasn't been found by the user before.
So it's above all well suited for users that aren't 
familiar with Sudoku strategies.

=head1 FILE FORMAT OF SUDOKU PUZZLES

The Sudoku files of the trainer are ASCII text files.

The B<input> format for Sudoku puzzles is rather flexible. At the 
top of the file,
lines starting with "#" are ignored (comment lines). In the puzzle itself,
there need not be 9 lines with 9 characters each: newlines are ignored.
The digits 1 - 9 represent known values. Exept for the blank, any other 
printable ASCII character is taken as a placeholder for an unknown value.
Blanks are taken as placeholders only when there are no other placeholders,
otherwise they are ignored. The sum of known values and placeholders must 
amount to 81. When the "#" is used as a placeholder, it is recommended 
that the comment lines are followed by an empty line.

On B<output>, "-" is used as the placeholder. The puzzle is stored as a 9x9 
grid, with blanks and empty lines added to separate the 3x3 subsquares 
for better human readability.

=head1 DIAGNOSTICS

Error messages are displayed in a message window. The window title shows 
the error type:

=over 4

=item * User error

The user made an error when running the trainer (e. g. entered an invalid 
cell name). In most cases he may correct his error.

=item * Data error

An error has been detected in the puzzle (e. g. a cell without a value and 
without candidates).

=item * Code error

A contradiction has been found in the internal state of the puzzle.


=item * Problem

These errors come from other sources, e. g. Perl/Tk or the Perl interpreter.

=back

Perl/Tk shows some of its error messages in its own message window.

The I<Run> button gets disabled when it's of no use to continue. The user
may still save files or investigate the history.

=head1 DEPENDENCIES

In addition to modules that are distributed with perl, the trainer
needs the following modules (available from CPAN):

=over 1

=item * L<http://search.cpan.org/perldoc?Tk> (PerlE<sol>Tk)

=item * L<http://search.cpan.org/perldoc?List::MoreUtils>

=back

=head1 TO DO

=over 1

=item * Add more strategies

=item * Add a restart feature

=back

=head1 BUGS

Please report any bugs or feature requests to bug-SudokuTrainer [at] rt.cpan.org, 
or through the web interface at 
https://rt.cpan.org/Public/Bug/Report.html?Queue=SudokuTrainer.

Please include the following material in the bug report:

=over 4

=item * 

the error message

=item * 

the puzzle (preferedly in its initial state)

=item * 

the priority list, if different from the default

=item * 

any output in the shell window (normally there is none, exept
for code errors)

=back

=head1 AUTHOR

Klaus Wittrock  (<Wittrock [at] cpan.org>)

=head1 ACKNOWLEDGEMENT

Alex Becker pointed out to me several passages in the code that
urgently needed improvement. He also encourages me repeatedly to
use more OO techniques.

=head1 LICENCE AND COPYRIGHT

Copyright 2014 Klaus Wittrock. All Rights Reserved.

This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.