PROGRAM "cruci" - PUBLIC DOMAIN CROSSWORD PUZZLE GENERATOR
Written by Fernando Pardo, Last version September 1994


INTRODUCTION
============

The  program  "cruci"  fills a defined  grid  table  with  words  taken  from a
dictionary.  The  program is also able to generate  random grid  patterns.  The
generated grid is symetrical  horizontal and  vertically.  The program  options
are:

Usage: cruci [-x size_x] [-y size_y] [-s seed] [-l maxlong]
             [-d dic_file] [-o out_file] [-g grid_file]

Where:
   size_x    is the X size of the puzzle. (default 9)
   size_y    is the Y size of the puzzle. (default 9)
   seed      is a the seed for the random generator. (default 1)
   maxlong   is the maximun word lenght allowed. (default 9, max 14)
   dic_file  is the dictionary with words. (default "cruci.dic")
   out_file  is where the final result is stored. (default "cruci.tbl")
   grid_file if specified, it is the grid table.
                         (default: internally generated grid table)

cruci  always  generate  two files,  the  out_file  and a special  file  called
"cruci.grid"  where the grid pattern is always saved.  This  cruci.grid  can be
edited an can be used as  grid_file  to feed the cruci  program.  In any  case,
these two files  overwrite any existing files with the same names.  The program
writes to out_file the current state, in this way it is possible to monitor the
puzzle at any time during execution.  The out_file is updated from time to time
when some progress has been made.

The format of the  grid_file  is as  follows:  a white  indicates  spaces to be
filled, and the '#' character all other places.  Different horizontal lines are
indicated  by new  lines.  The size of the  resulting  puzzle is  indicated  by
size_x  and  size_y  and not by the grid  pattern  that can be bigger.  Run the
program and see the file  "cruci.grid", it gives an impression on the format of
the grid for input.


LIMITATIONS
===========

The maximun word length allowed is 14, it can be changed in the source, but, is
it really necessary???

The limit  for the  puzzle is a 50x50  table,  though  it could be easily  more
changing  the source.  This limite is not a program  limit, it has been made on
purpose.

You need a stack.  A rough  calculation  for it is  something  like (8 x WORD x
VERPALNUM)  where  WORD is the  length  in bytes  of your  computer  word,  and
VERPALNUM is the number of vertical words.  You will need more than this number
since you never know....

The memory has to be huge enough to keep you  dictionary, so you will need disk
swap and thing  like that.  The  "pasa"  program,  take out some  words when it
thinks that there is too much words.  This limit can be changed.

It takes time to calculate a puzzle, and it is specially  dependent on the grid
pattern  or the seed for the  random  number  generator.  The  algorithm  grows
exponentially  with the maximun  word length,  lineally  with X, and  something
between exponentially and linealy with Y.

PC is not the  fastest  architecture  in the world, be  patient.  Only 80386 or
superior can be used, but you can try with something smaller.

With a HP700 hp-ux it takes from seconds to minutes to calculate puzles between
10 and 15, but it really depends a lot on the grid, more than in the size.


DICTIONARIES
============

Two  dictionaries   are  provided  with  the  program,  a  spanish   dictionary
"cru_esp.dic" and an english dictionary  "cru_eng.dic".  Both are codified in a
special  format  for the  program  "cruci".  To use  different  dictionaries  a
utility  called "pasa" is also  provided.  This program takes any ASCII list of
words  delimited by new lines and transform it to a dictionary in the format of
"cruci".  The program has no  arguments,  it takes a file called  "diccion.cru"
with the list of words,  and  creates  the file  "cruci.dic"  with the  "cruci"
format.  So, you only  have to copy  your  file to  "diccion.cru"  and then run
"pasa", it will create "cruci.dic" that can be used with "cruci".


FILES
=====

"cruciPC.zip" and "cruci_hp_ux_700.tar.Z"  contains the executables "cruci" and
"pasa"  and the read me file  "README".  The file  "cruciPC.zip"  is for PC and
compatibles, and "cruci_hp_ux_700.tar.Z" is for HP series 700 with hp-ux.

"diction.zip" and "diction.tar.Z"  contains the dictionaries  "cru_esp.dic" and
"cru_eng.dic",   the   spanish   and  the   english   dictionaries.  As   usual
"diction.zip" is for PC and compatibles, and "diction.tar.Z" for Unix.


INFORMATION
===========

The  executables  of this  program are public  domain,  only the  sources  have
restricted  access.  If you want the C sources  send a message  to the  address
bellow.

If you find the program useful send gifts,  postcards,  comments, a girlfriend,
whatever, to the address bellow.  If you can make money with the program or the
sources, do not send postcards, DO SEND MONEY!!!!

Fernando Pardo
C/ Maestro Serrano, 15-1
46950 Xirivella (Valencia)
SPAIN

e-mail:  pardo@glup.eleinf.uv.es

(I read the e-mail everyday and always answer, if you get nothing from me try
again)
