.TH cwc 6 1999/07/20 "." "Crossword Compiler"
.SH NAME
.B cwc
- a crossword compiler to produce filled crossword grid from
a pattern file and word list as input.
.SH SYNOPSIS
.BR "cwc [-vs] [-w walker] [-p pattern-file] [-i index-style] [-r seed]"
.br
.BR "cwc -b"
.SH OPTIONS

.TP
.BR "-b"
Benchmark the dictionaries. This will benchmark the binary tree index
and the letter index by loading the word lists and querying the indices
with random patterns.

.TP
.BR "-d dictionary"
Use another dictionary (word list) than the default which is
/usr/dict/words. Word list files are simply a file with a word on each
line.

.TP
.BR "-g grid-file"
Load the grid pattern from a \fBgeneralized grid pattern file
format\fR (see section \fBGENERALIZED GRID PATTERN FILE FORMAT\fR).
Note: You'll probably want to use the normal square grid format
instead. See the \fB-p\fR option.

.TP
.BR "-i index-style"
Sets the word list index method to use. Possible index methods are
\fIbtree\fR and \fIletter\fR. The default is \fIletter\fR. Generally,
the \fIletter\fR index is much faster than the \fIbtree\fI index, but
it also require more memory. 

.TP
.BR "-p pattern-file"
Load normal grid pattern file (square grids). Load the specified grid
pattern file which specifies the grid to be filled with letter. See
\fBGRID PATTERN FILE FORMAT\fB for the pattern file format. A number
of example pattern files are located in the \fIpatterns\fR
subdirectory of the distribution. The default pattern is a 4x4 grid.

.TP
.BR "-r seed"
Set the random seed to \fIseed\fR. By default the random set will be
set pseudo randomly using the timer, but with this option you can set
it to a specific value. Setting the random seed will make the
crossword compile act deterministic and thus always generate the same
filling when you use the same random seed. Useful for benchmarking.

.TP
.BR "-s"
Print the current grid regularly during the compilation. Useful to
monitor the progress.
.TP
.BR "-S"
Print each step. Each time a letter has been inserted into the grid
the entire grid will be printed in \fIsimple\fR format.

.TP
.BR "-v"
Be verbose. \fBcwc\fR will print a lot of information about the
decisions made while running the algorithm. Mostly useful for
debugging.

.TP
.BR "-w <walker>"
Choose walking heuristics. The \fIprefix\fR walker walks each line
from left to right from the top to the bottom. The \fIflood\fR walks
to the next cell adjacent to an already filled cell each step. The
default walker is the \fIflood\fR walker. See the section \fBWALKING
HEURISTICS\fR for further explanation.

.SH "GRID PATTERN FILE FORMAT"
By default \fBcwc\fR will attempt to fill a grid with 4 by 4
cells. You can make \fBcwc\fR fill other grid patterns using the
\fB-p\fR option. \fB-p\fR takes on parameter which is the named of the
pattern file. A set of example patterns is located in the
\fBpatterns\fR subdirectory of the distribution archive.
.SS Example Pattern File
.RS

6 4
.br
++++++
.br
++ +++
.br
+++ ++
.br
++++++
.RE
.SH GENERALIZED GRID PATTERN FILE FORMAT
The normal grid pattern file allow only for regular square grids. In
order to compile other grid formations, e.g. hexagon grids, \fBcwc\fR
can load a generalized grid format file. The file consists of a number
of lines each representing a word in the grid. Each line consists of a
set of integers each denoting a cell number in the grid. For example,
lets consider a regular 3x3 square grid.
.PP
.RS
1 2 3
.br 
4 5 6
.br
7 8 9
.RE
.PP
The words in this grid are (each line lists the cell numbers of the word):
.PP
.RS
1 2 3
.br
4 5 6
.br
7 8 9
.br
1 4 7
.br
2 5 8
.br
3 6 9
.br
.RE
.PP
The lines in above represent the grid in the generalized format. This
format allow very special grids to be formed. The following grid is a
circle where the two first and two last letters in each word overlap
with the previous and next words.
.PP
.RS
1 2 3 4 5
.br
4 5 6 7 8
.br
7 8 9 10 11
.br
10 11 12 1 2
.RE
.SH WALKING HEURISTICS
The Walking heuristics scheme defines how to algorithm propagates
through the grid pattern.
.SS Prefix walking
The prefix walking heuristics walk each word from left to right
starting at the top. (May vary a little for generalized grids).
.SS Flood walking
The flood walker choose the next cell adjacent to any of the already
filled cells. If none is found, it chooses the top-left-most cell
which has not yet been filled. This is the default walking heuristic
and also the most efficient according to my tests.

.SH DICTIONARY INDEX
Two different dictionary index styles have been implemented in
\fBcwc\fR. The default style is a binary search tree. The index is
fairly efficient and does not require too much memory. The other style
is the letter index which is a complete index of words having a
specific letter on a specific position. The letter index requires more
memory than the binary search tree index, but is generally faster. The
letter index also takes longer time to initialize due to its size. The
default dictionary style is the \fBletter index\fR.

.SH BUGS
Huh?

.SH SEE ALSO
Design and Implementation Crossword Compilation Programs (Using
Sequential Approaches) by Sik Cambon Jensen 1997.