




















                         Sandman Software presents the



                                   User Guide



                                      for



            Cword - The Portable Freeware Crossword Compiler/Builder.



                                 12 December 1995



        Copyright (c) 1995 James A. Lundon - jlundon@xstacy.enet.dec.com.


Contents
--------

Contents                                                           2

Acknowledgements                                                   3

Introduction                                                       4

General details                                                    5

Generate                                                          12

Fill                                                              22

Complete                                                          31

Word utilities                                                    39

Misc. other utilities                                             44

Technical appendices                                              49

        [The page numbers assumes 68 lines per printed page.]


Acknowledgements
----------------

I would like to thank the following people for their help during the
development and testing of Cword: 

* Dave Tuller.

* The rec.puzzles.crosswords community.

* Many others who shall remain nameless.


Revision History
----------------

Date                Description
+++++++++++++++++++++++++++++++

3 July 1995         First draft for V1.0b1.

19 October 1995     Second draft for V1.0.

12 December 1995    Final draft for V1.0.


Introduction
------------

Cword is a general purpose crossword compiler/builder.  It runs on
many Unix based systems (System V or BSD) and OpenVMS (VAX or AXP). 
It is coded using ANSI C and is being distributed, with full C
sources, as freeware. 

Features of Cword include the:

* Ability to create Blocked, Barred, American and Novelty crossword 
grids.

* Automatic filling of Blocked, Barred, American and Novelty crossword
grids with lights from user-defined word lists. 

* User generation of clues for all crossword types.

* Printing of grids and crosswords to postscript and text file formats.

* Provision of many word based utilities useful during the setting and
solving of crosswords puzzles. 

* Storage and retrieval of grids, crosswords, and clues, to and from a
relational database. 

* Provision of other useful administrative functions to ease the
difficulty of creating high quality crossword puzzles. 

Cword employs a simple hierarchial character cell user interface. Each
character cell main menu section has its own chapter in the user 
guide.

It is hoped to make Cword available via the Usenet news group
comp.sources.misc and through other freeware distribution channels,
including DECUS and source code CD-ROMs.  Cword will also be made
available via FTP in the Crossword Archive located at:

host:      gatekeeper.dec.com 
directory: /pub/micro/msdos/misc/crossword-archive



General details
---------------

Building Cword
==============

For details about building/configuring Cword, please see the
appropriate README file in the distribution.  If you are to use Cword
on a Unix platform see UNIXREAD.ME.  If you are to use Cword on the
OpenVMS platform see OVMSREAD.ME.  Details about Cword on
MS-DOS/Windows are in DOSREAD.ME. 

All these files basically detail - step-by-step - what has to be done
to get Cword up and running from the distributed sources.  All the
README files cater for beginners and experienced people alike and are
fairly complete and easy to follow. 

Other overview information on Cword is available in the text file
READ.ME.

Running Cword
=============

Once you are happy that you have built and configured Cword correctly,
it is time to run the application.

To run Cword type:

$ cword

at the command line.

On OpenVMS, a foreign command has to be defined to allow Cword to
accept qualifiers/parameters from the command line.  Unless a foreign
command is defined, Cword will not be able to accept parameters.  This
is not necessarily a problem if you do not want to specify run-time
parameters.

Many command line parameters are available in Cword.  A full list of
possible Cword parameters follow below: 

-defaults 
-max 
-min 
-centre 
-webster 
-subanagram 
-superanagram 
-soundex 
-template 
-spell 
-addword 
-rot13 
-wordwild 
-text 
-postscript 
-intersect 

To get a list of the possible command line parameters available use
the following command: 

$ cword -help

or 

$ cword ?
Usage: cword [-defaults defaults_file] [-max n] [-min n] [-centre ch]
        [-webster word] [-subanagram word] [-superanagram word]
        [-soundex word] [-template template_str] [-spell word]
        [-addword word] [-rot13 string] [-wordwild string]
        [-text crossword/grid file] [-postscript crossword/grid file]
        [-intersect template1_str template2_str] [-help] [help] [-?] [?]

If a command line qualifier (except for -defaults) is provided, the
user interface will not be entered; Cword will try to execute the
command sequence entered, and return to the prompt when completed.  If
an incorrect or invalid command line sequence is entered, Cword will
inform the user and exit with an error. 

Most of the Cword command line qualifiers concern the execution of the
word utilities, which are also part of the user interface:

* Getting soundex equivalents (-soundex).

* Getting sub-anagrams (-subanagram, -max, -min, -centre).

* Getting super-anagrams (-superanagram, -max, -min).

* Getting template matches (-template).

* Getting template intersecting matches (-intersect).

* Getting wildcard matches (-wordwild).

* Checking the spelling of an inputted word (-spell).

* Getting Webster's dictionary server definition of an inputted word
(-webster).

* Decoding using ROT13 an input string (-rot13).

* Printing a Cword grid/crossword file to postscript (-postscript).

* Printing a Cword grid/crossword file to text (-text).

This functionality was implemented to give the user an opportunity to
use Cword without having to enter the user interface. 

Cword parameter examples include: 

++

$ cword -spell james
Matching taking place.
CWORD-I-SPELLR, The word "james" is found in word files

$ cword -min 5 -subanagram jamesisthe
CWORD-I-GENSUB, Generating sub anagrams using "jamesisthe"
CWORD-I-TARGET, No centre letter : anagram size > 4 : letters "jamesisthe"
Getting sub-anagrams.
CWORD-I-SUBFND, 20 sub or full anagrams found
List of words returned include :
amiss asset haste heist james jetsam sesame shame sheet siesta smash
smite smith steam tease theism theme these thesis times 

$ cword -webster clue
CWORD-I-WEBSTR, The word to search for in Websters is "james"
CWORD-I-WEBCON, Connecting to Webster server at IP address 16.1.16.1.
DEFINITION 0
1. clew or clue \'klu:\ n [ME clewe, fr. OE cliewen; akin to OHG kliuwa
   ball, Skt gl]au lump 1: a ball of thread, yarn, or cord usu clue  2:
   something that guides through an intricate procedure or maze of
   difficulties; specif : a piece of evidence tending to lead one toward the
   solution of a problem 3a: a metal loop attached to the lower corner of a
   sail pl  3b: a combination of lines by which a hammock is suspended
2. clew or clue vt or clewed or clued;  or clew.ing; or clue.ing;  or
   clu.ing 1: to roll into a ball usu clue  2: to provide with a clue 3: to
   haul (a sail) up or down by ropes through the clews

$ cword -rot13 wnzrf
CWORD-I-ROTSTR, The ROT'ed string : "james"

++

Note: all examples of Cword's screen output in this user guide will
be surrounded by two sets of "++", as seen above. 

Output from all the above command line parameters go to standard
output (stdout).  Therefore it is possible, if necessary, to capture
all output from these commands to a file using standard re-direction
techniques.  On Unix, it is simply a case of using the operator >.  On
OpenVMS, define SYS$OUTPUT, execute the command, and deassign
SYS$OUTPUT to capture Cword output into a text file of choice. 

If you have no need for this functionality and you just want to use
Cword to create crosswords then come along this way... 

To invoke the Cword character cell user interface, execute:

$ cword

Cword will attempt to open cword.ini in the same directory from which
Cword is being executed in order to obtain run-time user-configuation
information. 

If this file is not present, Cword will use default configuration
information.  The biggest effect of not having cword.ini defined is
probably the default choice of word files which Cword will attempt to
use. 

e.g. No cword.ini in the directory where Cword is executed: 

++

$ cword
CWORD-I-BLTWHN, Cword V1.0 was built at 19:03:21 Jun 20 1995
CWORD-W-SYSDEF, Using system defaults - configuration file unsuccessfully read

++

This message tells the user that cword.ini was not found (or was not
successfully read).  The main effect - as previously said - is the
word files Cword will attempt to use: ./words.* or []words.*. If the
word file series: words.[01-40] are not available, another error is
outputted as so: 

++

CWORD-E-CHKWRD, Valid word files *not* found - check defaults

++
 
Processing will continue as usual, but be warned: none of the grid
filling or word utilities will work as no "fuel" - words - have be
found by the application to use.

If cword.ini is found, and contains valid information, Cword will 
output:

++

$ cword
CWORD-I-TRCOPN, Trace file cword01.log opened on  4-JUL-1995 13:36
CWORD-I-BLTWHN, Cword V1.0 was built at 19:03:21 Jun 20 1995
CWORD-I-USRDEF, Using defaults found in defaults file cword.ini
Please press return to continue

--------------------------------------------------------------------------------
                Sandman Software presents : Cword V1.0
--------------------------------------------------------------------------------

                 1.  Generate grid
                 2.  Fill grid
                 3.  Complete crossword
                 4.  Word utilities
                 5.  Misc. other utilities
                 0.  Exit!

Please input user choice :

++

You are now ready to create the crosswords of your dreams, and even
solve a few at the same time, if that is what you want! 

Remember, the user interface is hierarchial in nature: menus within
menus within menus until you reach the functionality of your choice.
Cword's user interface has been divided into five distinct sections,
each of which represents a distinct step in the creation of a
completed crossword definition.  If you are interested only in the
word utilities Cword provides, main menu option 4 is the section you
will probably be most interested in. 

Main menu option 1 contains all the functionality necessary to create
and print an empty grid definition. 

Main menu option 2 contains all the functionality necessary to fill
an empty grid definition with lights. 

Main menu option 3 contains all the functionality necessary to
complete and print a filled grid definition. 

Main menu option 4 contains many word utilities useful during the
setting and solving of crosswords. 

Main menu option 5 contains miscellaneous utilities which may be
useful to users of Cword. 

Please refer to the particular chapter for more information on the 
chosen option. 

Menu commands
=============

Menu commands in Cword are quite straight forward to understand and
use.  For a list of all possible menu inputs type h or ? with a
carriage return at any point where a user choice is required: 

++

Please input user choice : h

The following commands can be used (upper/lower case) :

## E - Exit Cword completely
## B - Back up to the calling menu or exit if in main menu
## H, ? - Gets this screen
## D - Displays current defaults
## 1 to 5 - Valid menu options
## !, %, $ [OS command] - Execute an OS/shell command
## CD [directory] - Set directory into [directory]
## 0 - Back up menu or exit Cword

++

All user interface commands can be entered in mixed case, except when
changing a directory, or specifying a file, where case sensitivity is
essential on some systems e.g Unix.

Most commands in the menu command line are simple to understand,
except perhaps for the CD and !/%/$ commands. 

CD (or cd) is used to change Cword's current working directory:

++

Please input user choice : cd test
CWORD-I-CHDIRM, Attempting to change directory
CWORD-I-CHDIRS, Successfully changed directory to test

Please input user choice : cd testing
CWORD-I-CHDIRM, Attempting to change directory
CWORD-E-CHDIRE, Error changing directory to testing

++

To execute a shell/OS command from within Cword one of the following
characters must precede the shell/OS command: !, %, or $.

++

Please input user choice : !dir
CWORD-I-SYSTEM, Calling OS using "dir" - on your own from here

Directory USER$:[USERNAME]
...

CWORD-I-SYSBCK, Back from the wilds of system () safely

++

or:

++

Please input user choice : %ls *.xrd
CWORD-I-SYSTEM, Calling OS using "ls *.com" - on your own from here

...

CWORD-I-SYSBCK, Back from the wilds of system () safely

++

Menu navigation
===============

A few points to be kept in mind when using the Cword character cell
menu interface include: 

* No user commands can be understood by Cword until a carriage return
is entered to terminate input.

* The most important functionality in each of the sub-menus is usually
placed at option one. 

* For many of the input options, default values are provided.  The
default value will be within the square brackets - [] - and are used
if the user presses carriage return with no other input:

++

Please input name [this is the default name] : 

++

If return is pressed without entering anything, "this is the default 
name" is selected, otherwise what the user has entered is selected for 
further use.

When no default value is provided, input is expected.  If no input is
found, an error will be reported by Cword. 

Sometimes when input is restricted to being within certain limitations
Cword will display what these limitations are as part of the output
message.  The restrictions are usually placed within ordinary brackets 
"(" and ")" as so: 

++

CWORD-I-SYMCSN, Grid symmetry chosen : 90 degree symmetry
X (3 to 40) [13] :

++

This message tells the user that the allowable values go from 3 to 40
and that there is a default on this input of the value 13.  (This
message is taken from the grid creation phase and determines what the
X co-ordinate length of the grid will be.) 

* For many input options demanding a file specification, the file
suffix can usually be defaulted:

++

Please input file name [suffix .grd] : test_grid

++

Cword will try to find a file called test_grid.grd in the current
working directory.  If test_grid.grd is entered (and the file exists),
Cword will find the file.  If test_grid.xrd is entered, Cword will
concatenate .grd onto the user input and will search for the file
specification: test_grid.xrd.grd - probably unsuccessfully. 

* Many of Cword's word utilities return output spanning more than 1
screen.  Cword handles this scenario by displaying the matches one
terminal screen at a time.  Cword will prompt the user whether to
continue outputting or not, using the following message: 

++

Press <return> to continue or Q <return> to quit:

++

By pressing return (also known as carriage return - see previous
section) output from the option chosen will continue to be displayed. 
By pressing Q (case insensitive) output will cease and the user will
be returned to the user interface. 

Graphical representation of some grid/crossword definitions used in
Cword can also span more than one screen.  In cases like this the
following message will be displayed: 

++

Press return to continue

++

To continue displaying the grid/crossword definition a carriage return
must be entered by the user. 

This message will often be seen when traversing the user interface; it
controls how output from the interface is presented to the user. 

General Comments
================

The user guide presents a work flow paradigm to learning about Cword.
To learn how to effectively use Cword I suggest that the whole
document is read and then implemented to re-inforce the ideas dealt
with. 

A fully worked example is taken from grid creation to crossword
completion in this document.  The example grid and crossword are
printed to the various file formats supported by Cword.  The
intermediate grid and crossword are also inserted, retrieved and
deleted from the relational database backend.  All other Cword
functionality is described with fully worked examples too. 

                                  || ----- ||


Generate
--------

This section describes how to create an empty crossword grid, and also
describes the purpose of all the other functionality hanging off the
"Generate grid" menu. 

When option 1 is selected from the main menu, the following menu
should be presented to the user: 

++

--------------------------------------------------------------------------------
                Sandman Software presents : Cword V1.0
--------------------------------------------------------------------------------

        1.  Generate grid

                (1)  Generate grid

                (2)  List grids suitable for printing
                (3)  Report on grid definition
                (4)  Write grid to text file
                (5)  Write grid to postscript file

                (6)  Read grid from database
                (7)  Write grid to database
                (8)  Delete grid from database
                (9)  List grids in database
                (0)  Back to main menu!

Please input user choice :

++

Generate grid
=============

To create an empty crossword grid select option 1 in the "Generate
grid" menu.  You will be presented with a series of questions to be
answered.  These questions allow Cword to ascertain what kind of grid
is to be created.  It also constrains the user to specifying - where
possible - a valid grid definition.

++

Please input user choice : 1

CWORD-I-GRDBGN, Grid creation starting with grid definition

Please input grid dimensions to be used in construction of grid :

Select the grid type from the list of choices :
1. Block grid
2. Barred grid
3. American grid
4. Novelty grid
Please input selected grid type [1] : 1
CWORD-I-GRDPKD, Block grid format chosen

Select the grid symmetry from the list of choices :
1. 90 degree symmetry
2. 180 degree symmetry
3. axial - (top Left to bottom Right) symmetry
4. axial - (top Right to bottom Left) symmetry
5. no symmetry

Please input selected grid symmetry [1] : 1
CWORD-I-SYMCSN, Grid symmetry chosen : 90 degree symmetry
X (3 to 40) [13] : 15
CWORD-I-DIMSET, X dimensions of grid set to 15
Y (3 to 40) [15] : 15
CWORD-I-DIMSET, Y dimensions of grid set to 15

You will create a 15 by 15 Block grid using 90 degree symmetry

++

You are about to create a blocked grid, with 90 degree grid symmetry
whose dimensions are 15 by 15.  This type of grid is probably the most
popular format of both definition and cryptic crosswords in Europe. 

This specification step constraints the user to creating grids which 
are valid for the grid type selected.  By this I mean, if a barred 
grid is selected for creation, only 90 degree or 180 degree symmetry
will be allowed to build this grid type with.  If an American grid is 
selected for creation, Cword will only allow the user create a squared 
shaped grid.  With the Novelty grid type almost anything goes, so if 
you aren't sure what kind of grid you're trying to create, this might 
be the best place to start.

When the grid specifications have been successfully established, it is
time to start defining what the grid will actually look like! 

You will now be presented with a screen like this:

++

Current cell/grid details - blank (-), unch (*), checked (#)
Using : 90 degree symmetry

15>---------------
14>---------------  No lights so far created
13>---------------
12>---------------
11>---------------
10>---------------
09>---------------
08>---------------
07>---------------
06>---------------
05>---------------
04>---------------
03>---------------
02>---------------
01>---------------
--+^^^^^^^^^^^^^^^
Y/|000000000111111
/X|123456789012345

       ***** Press H for help on all commands available *****
Enter grid creation command [A] :

++

Press H for all commands available from this command line:

++

Enter grid creation command [A] : h

Here is a short description of each command available:

## S - Save the completed grid to Cword grid file
## Q - Quit current grid creation without saving
## A - Add light (or lights) to evolving grid definition
## D - Delete light (or lights) from evolving grid definition
## L - List the lights currently created
## R - Reset/delete all light definitions in evolving grid
## V - Verify that the current grid conforms to selected grid properties
## H - Get this screen :-)

++

If no specific command is chosen in this menu, the command for adding 
a light definition to the grid is automatically chosen by pressing 
carriage return.

++

Enter grid creation command [A] :
Input X co-ordinate of light to be created (1-15) : 1
Input Y co-ordinate of light to be created (1-15) : 15
Input the proposed light direction (A/D) : a
Input the proposed light length (1-15) : 7
CWORD-I-ADDING, Adding lights using : 90 degree symmetry
CWORD-I-ADDLIG, Adding light - loc: (1,15) dir: Across len: 7
CWORD-I-ADDLIG, Adding light - loc: (15,15) dir: Down len: 7
CWORD-I-ADDLIG, Adding light - loc: (9,1) dir: Across len: 7
CWORD-I-ADDLIG, Adding light - loc: (1,7) dir: Down len: 7

Current cell/grid details - blank (-), unch (*), checked (#)
Using : 90 degree symmetry

15>*******-------*
14>--------------*  Total lights so far created: 4
13>--------------*  Made up of:
12>--------------*  2 Across lights
11>--------------*  2 Down lights
10>--------------*
09>--------------*  Latest addition: (1,15) dir: A
08>---------------
07>*--------------
06>*--------------
05>*--------------
04>*--------------
03>*--------------
02>*--------------
01>*-------*******
--+^^^^^^^^^^^^^^^
Y/|000000000111111
/X|123456789012345

++

As can be seen from the grid above, four light definitions have been
added in the newly defined grid.  Even though only one light
definition was specified, four lights are created because of the grid
symmetry chosen earlier.  If 180 degree symmetry had been chosen two
lights would have been added to the grid definition. 

If a cell in the grid contains a '-' it means that the cell is still
blank (blank cell).  If a cell contains a '*' it means it has been
filled by a light going in only one direction, either down or across,
not both (an unch - short for unchecked cell).  If a cell contains a
'#' it means that lights bisects the cell in both directions (checked
cell). 

Using this step-by-step method, it is possible to see the grid being
built up right before your eyes. 

You can continue adding lights to the grid by inputting valid X and Y
co-ordinates, a valid direction, and a valid light length.  Cword does
indepth checking to verify that the light(s) being added fit into the
grid without breaking any predefined grid creation rules, or the
previously selected grid definition properties.  If a grid creation 
rule is broken:

++

Enter grid creation command [A] :
Input X co-ordinate of light to be created (1-15) : 7
Input Y co-ordinate of light to be created (1-15) : 15
Input the proposed light direction (A/D) : a
Input the proposed light length (1-9) : 6
CWORD-E-DBLLIG, Multiple lights defined at location (7,15)
CWORD-E-INVLGH, Invalid light co-ordinates entered

++

The light starting at the (7,15) [(X,Y) co-ordinates] - direction:
Across - length: 6 is invalid as part of the light (1,15) - direction:
Across - length: 7 is already defined at location (7,15). 

Sometimes it is not enough to see the grid visually, you need to see
what lights are defined and where.  To get a text list of the lights
currently defined in the grid select L (to List) as so: 

++

Enter grid creation command [A] : L

Clues already defined in the evolving grid include:

 Clue      Co-ords - Len Clue      Co-ords - Len Clue      Co-ords - Len

  1 Across ( 1,15) -  7   4 Across ( 9, 1) -  7   2   Down (15,15) -  7
  3   Down ( 1, 7) -  7

 Highest Across clue is 4  -  Highest Down clue is 3

++

The above option can be very useful when trying to finish the creation
of a grid.  It can be difficult to figure out what lights are missing
when transcribing a crossword grid definition from a newspaper or
magazine. 

If you want to delete a light(s) definition from the grid select D (to
Delete) as so: 

++

Enter grid creation command [A] : d
Input X co-ordinate of light to be created (1-15) : 1
Input Y co-ordinate of light to be created (1-15) : 15
Input the proposed light direction (A/D) : a
Input the proposed light length (1-15) : 7
CWORD-I-DELING, Deleting lights using : 90 degree symmetry
CWORD-I-DELLIG, Deleting light - loc: (1,15) dir: Across len: 7
CWORD-I-DELLIG, Deleting light - loc: (15,15) dir: Down len: 7
CWORD-I-DELLIG, Deleting light - loc: (9,1) dir: Across len: 7
CWORD-I-DELLIG, Deleting light - loc: (1,7) dir: Down len: 7

++

This option will only work if the light being deleted already exists
in the grid.  If the light does not exist, an error will be outputted.
Remember all associate lights will also be deleted to maintain grid 
integrity - as was the case when adding lights to the grid.

If you want to delete all defined lights in the grid to start from
scratch again, you can do one of two things: 

* Type Q (to Quit) to quit grid generation and re-enter with the same
grid specification.

* Type R (to Reset) to bring the grid back to its original empty form.

++

Enter grid creation command [A] : R
CWORD-I-RESET, Resetting grid definition containing 4 lights

++

To check whether the grid complies with the previously defined grid
properties select V (for verify): 

++

Enter grid creation command [A] : v
CWORD-I-VALIDG, Grid definition is valid for type sought

++

Whether the defined grid is valid depends upon a series of fairly
complex grid creation rules.  For blocked grids almost any grid
definition will be valid at any time during grid creation.  There is 
only one property which may be checked of a block grid: adjacent
unches.  Adjacent unches (connected cells from a light which are
unchecked by a bisecting light) are frowned upon in many circles for a
few reasons.  Whether adjacent unches are checked depends upon whether
the configuration parameter UNCHES_CHECK is true or not. 

For barred grids, specific rules about what constitutes a correctly
formed barred grid come into play (see glossary of terms).  The most
important of these rules is that all cells in a barred grid must have
at least one light bisecting them.  If this rule is not satisfied,
when the grid is being verified, Cword will return an error saying the
grid is not valid with reference to the original grid properties. 

In the case of an American grid, the grid is only valid if at least
83% of the cells are checked and contain no unches.  The other main
American grid characteristic will have been established when defining
the grid: that of specifying that the grid is square in shape i.e. X
dimensions equal Y dimensions of grid.

A novelty grid is a grid which does not adhere to any of the rules
that constrain the other grid types.  This grid type is useful when
creating unconventional grid types which don't easily fit into the
other three categories dealt with in Cword.  The most subtle
difference between a Novelty grid definition and a Block grid
definition is whether Cword checked for adjacent unches in a Block
grid definition. 

Once the grid has been built, and hopefully verified, it is time to
save it for later use: 

++

Current cell/grid details - blank (-), unch (*), checked (#)
Using : 90 degree symmetry

15>*#*#*#*#*-*-*-*
14>-*-*-*-*-*#*#*#  Total lights so far created: 32
13>*#*#*#*#*-*-*-*  Made up of:
12>-*-*-*-*-*#*#*#  16 Across lights
11>*#*#*#*#*-*-*-*  16 Down lights
10>-*-*-*-*-*#*#*#
09>*-*-*-###-*-*-*  Latest addition: (7,9) dir: A
08>#*#*#*#-#*#*#*#
07>*-*-*-###-*-*-*
06>#*#*#*-*-*-*-*-
05>*-*-*-*#*#*#*#*
04>#*#*#*-*-*-*-*-
03>*-*-*-*#*#*#*#*
02>#*#*#*-*-*-*-*-
01>*-*-*-*#*#*#*#*
--+^^^^^^^^^^^^^^^
Y/|000000000111111
/X|123456789012345

Enter grid creation command [A] : l

Clues already defined in the evolving grid include:

 Clue      Co-ords - Len Clue      Co-ords - Len Clue      Co-ords - Len

  1 Across ( 1,15) -  9   9 Across (10,14) -  6  10 Across ( 1,13) -  9
 11 Across (10,12) -  6  12 Across ( 1,11) -  9  13 Across (10,10) -  6
 17 Across ( 7, 9) -  3  19 Across ( 1, 8) -  7  20 Across ( 9, 8) -  7
 21 Across ( 7, 7) -  3  23 Across ( 1, 6) -  6  27 Across ( 7, 5) -  9
 28 Across ( 1, 4) -  6  29 Across ( 7, 3) -  9  30 Across ( 1, 2) -  6
 31 Across ( 7, 1) -  9   2   Down ( 2,15) -  6   3   Down ( 4,15) -  6
  4   Down ( 6,15) -  6   5   Down ( 8,15) -  7   6   Down (11,15) -  9
  7   Down (13,15) -  9   8   Down (15,15) -  9  14   Down ( 1, 9) -  9
 15   Down ( 3, 9) -  9  16   Down ( 5, 9) -  9  17   Down ( 7, 9) -  3
 18   Down ( 9, 9) -  3  22   Down ( 8, 7) -  7  24   Down (10, 6) -  6
 25   Down (12, 6) -  6  26   Down (14, 6) -  6

 Highest Across clue is 31  -  Highest Down clue is 26

++

When ready to save the grid you have just created, simply enter S (to
Save) and press return as before. 

You will now be prompted for a title and name for the grid.  You can
accept the default name for the grid (tmp_grd) by simply pressing
return.  Check the configuration parameter TEMP_GRID_NAME for more 
details.

The user will then be asked for a file specification in which to save
the completed grid definition.  If no name is entered, tmp_grd.grd
will store the completed grid definition. 

++

Enter grid creation command [A] : s
CWORD-I-CRETIM, Time taken to create grid was 151 seconds
CWORD-I-VALIDG, Grid definition is valid for type sought
CWORD-I-GRDEND, Grid creation phase finished
What is the grid to be called [tmp_grd] : Test 15x15 grid
CWORD-I-GRDCAL, Grid is to be called "Test 15x15 grid"
Please input name of file to save grid definition to [tmp_grd.grd] : test_grid
CWORD-I-GRDWRT, Grid file test_grid.grd written

++

If, for some reason, you are unhappy with the grid you are creating,
and want to quit grid creation, you can do so by pressing Q (to Quit).
Quitting the grid generation phase will allow the user save the
partially created grid, if there are lights already defined on the
grid definition.  If no lights exist, quitting will immediately return
the user back into the "Generate grid" menu. 

Note: Cword currently cannot reload a partially created grid 
definition for further definition.

If, when saving a completed grid definition, the grid does not conform
to the grid properties originally decided upon by the user e.g. the
user wanted to create a barred grid but has left some cells in the
grid blank in the completed definition, the grid will have its defined
grid properties altered to those that correctly specify the grid e.g.
in the case above have the grid re-defined to being a block grid.  At
the end of each grid creation mechanism, Cword will check the completed
grid against the criteria originally selected by the user and will
display a message to the user in the event that the grid being created
is not of the type previously selected for creation by the user. 

Precedence: Barred grid -> American grid -> Block grid -> Novelty
grid. 

The creation process for an American grid is the same as that
undertaken for a Block grid except that all cells that contain light
data have to be checked and that at most 17% of the total grid cells
are to be blank. 

Because Cword is implemented using a simple character cell interface
some users may have problems correctly interpreting the grid as it is
being built up.  As has already been said, it is suggested that the
user employ the List mechanism to get a better idea what the grid is
constituted of.

List grids suitable for printing
================================

This option searches the current working directory and returns some 
information about each of the grid files it finds therein.

++

Info on grid file(s) *.grd from default directory:
--------------------------------------------------------------------------------
File name         | Grid Name    X dims   Y dims   Light no  Grid Type
--------------------------------------------------------------------------------
CROSSWRD.GRD;1    | Crossword...   21       21       104     180 American
TEST_GRID.GRD;1   | Test 15x1...   15       15        32     90 Block
TMP_GRD.GRD;2     | tmp_grd        13       13         4     90 Block

++

File name: file name of grid definition.

Grid Name: name of grid definition - truncated to 14 characters, if
necessary. 

X dims: horizontal dimensions of grid definition.

Y dims: vertical dimension of grid definition.

Light No: Number of light definition in the grid definition.

Grid Type: type of grid specification i.e. type and symmetry of grid
created. 

Report on grid definition
=========================

This option is used to obtain more information about the grid
definition the user has selected.  In this example, information about
the grid just created is displayed. 

++

Report on grid definition [suffix .grd] : test_grid

Report on grid definition "Test 15x15 grid" :

Dimensions are 15 by 15

Block grid found

Inputted grid is 25 percent checked, 48 percent unchecked and 27 
percent blank

Light lengths     :   3  6  7  9
Light frequencies :   4 12  4 12

Total number of lights defined is 32

Grid is not disjoint

Press return to view the current grid definition

+---------------+
|*#*#*#*#*-*-*-*|
|-*-*-*-*-*#*#*#|
|*#*#*#*#*-*-*-*|
|-*-*-*-*-*#*#*#|
|*#*#*#*#*-*-*-*|
|-*-*-*-*-*#*#*#|
|*-*-*-###-*-*-*|
|#*#*#*#-#*#*#*#|
|*-*-*-###-*-*-*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
+---------------+

++

(A definition of disjoint in the context of crossword grids can be
found in the glossary of terms in the appendices of this document.) 

Write grid to text file
=======================

This option will print a grid definition to an output text file.  This
functionality should be used if the user wants to view a text
representation of the grid definition.  The text grid representation
is useful, but is of inferior quality to the postscript representation
described below.  This option should really only be used if a
postscript printer/interpreter is not available. 

++

Please input user choice : 4
Please input name of file to output [suffix .grd] : test_grid
CWORD-I-GRDOUT, Grid file selected for outputting is test_grid.grd
CWORD-I-SLCTPS, Selecting output option - Block
CWORD-I-GRDOUT, Grid file test_grid.dat written

++

The output text file will look something like: 

++

Grid : Test 15x15 grid

         +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
         |1  |2  |   |3  |   |4  |   |5  |   |###|6  |###|7  |###|8  |
         |   |   |   |   |   |   |   |   |   |###|   |###|   |###|   |
         +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
         |###|   |###|   |###|   |###|   |###|9  |   |   |   |   |   |
         |###|   |###|   |###|   |###|   |###|   |   |   |   |   |   |
         +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
         |10 |   |   |   |   |   |   |   |   |###|   |###|   |###|   |
         |   |   |   |   |   |   |   |   |   |###|   |###|   |###|   |
         +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
         |###|   |###|   |###|   |###|   |###|11 |   |   |   |   |   |
         |###|   |###|   |###|   |###|   |###|   |   |   |   |   |   |
...

++

The outputted text file should be understood by any printer connected
to your local Unix or OpenVMS system. 

Write grid to postscript file
=============================

This option will print a grid definition to an output postscript file.
This functionality should be used if the user wants to view a
postscript representation of the grid definition.  This is the preferred 
method of creating a hardcopy version of the grid definition.

++

Please input user choice : 5
Please input name of file to output [suffix .grd] : test_grid
CWORD-I-GRDOUT, Grid file selected for outputting is test_grid.grd
CWORD-I-SLCTPS, Selecting output option - Block
CWORD-I-GRDOUT, Grid file test_grid.ps written

++

An example of the output from this option is not possible in the text
version of this guide.  However, the postscript file - when viewed as
a text file - should begin with the following lines: 

++

%!PS-Adobe-1.0
%%Creator: USERNAME
%%Title: Test 15x15 grid
%%BoundingBox: 0 0 612 792
%%CreationDate: Thu Jul  6 10:50:27 1995
%%EndComments
%!

++

The outputted Postscript file will *only* be processed by a printer
connected to your local Unix or OpenVMS system which understands
Postscript. 

Note: the next four options may or may not appear depending upon
whether Cword has been built with relational database support enabled.

Read grid from database
=======================

This option will take a grid definition - which has been previously
stored in the database - and create a grid file in the current working
directory containing the grid.  The file specification is user
supplied. 

++

Please input user choice : 6
Input name of grid to be read from database : Test 15x15 grid
CWORD-I-DBXRSC, grid "Test 15x15 grid" read successfully from database
Input file spec to save grid to [suffix .grd] : db_grid
CWORD-I-GRDWRT, Grid file db_grid.grd written

++

This grid file is now ready for any operations which are normally
associated with grid definitions. 

Write grid to database
======================

This option will take a grid definition and store it in the database. 
The grid will now be referenced in the database only by the grid
definition's name. 

++

Please input user choice : 7
Input grid file to write to database [suffix .grd] : test_grid
CWORD-I-DBADGR, Added grid_descriptions successfully
CWORD-I-DBADCL, Added light_descriptions successfully
CWORD-I-DBSUCC, grid "Test 15x15 grid" added successfully to database

++

Delete grid from database
=========================

This option will delete a user-defined grid definition from the 
database. 

++

Please input user choice : 8
Input name of grid to be deleted from database : Test 15x15 grid
CWORD-I-DBXDSC, grid "Test 15x15 grid" deleted successfully from database

++

List grids in database
======================

This option will display the names of all the grid definitions 
currently in the database.

++

Please input user choice : 9
The following grids are currently in the database:
Test 15x15 grid

++

                                  || ----- ||
 

Fill
----

This section describes how to fill with lights an empty crossword grid
and also describes the purpose of all the other functionality hanging
off main menu option 2. 

When option 2 is selected from the main menu, the following menu
should be presented to the user: 

++

--------------------------------------------------------------------------------
                Sandman Software presents : Cword V1.0
--------------------------------------------------------------------------------

        2.  Fill grid

                (1)  Fill grid with lights
                (2)  List grids suitable for filling

                (3)  List crossword files suitable for printing
                (4)  Report on crossword definition
                (5)  Write crossword to text file
                (6)  Write crossword to postscript file
                (0)  Back to main menu!

Please input user choice :

++

Fill grid with lights
=====================

This is the single biggest and most complex piece of functionality in
Cword.  For filling to begin, a grid file specification has to be
specified. 

Once the grid file has been found, and validated, Cword checks to see
if grid seeding (explained below) had been previously attempted.
Whether previous seeding attempts were successful or not, Cword will
then present the user with a menu interface where it will be possible
to seed lights in the grid before automatic grid filling can begin. 

Seeding in this context is the process of specifying user-defined
lights into an empty - or partially filled - grid definition.  This is
an invaluable feature for thematic and many other crossword types. 

Example where no previous seeding attempts were successful:

++

Please input user choice : 1
Input grid file to fill with answers [suffix .grd] : test_grid
CWORD-I-LGTSTR, Light generation beginning on grid "Test 15x15 grid"

++

If a previous attempt at seeding the grid is found, the seeds from the
previous attempt will be used, if the user so wishes. 

++

Please input user choice : 1
Input grid file to fill with answers [suffix .grd] : test_grid
CWORD-I-LGTSTR, Light generation beginning on grid "Test 15x15 grid"
Read file containing seeds for grid (Y/N) [Y] :
CWORD-I-SEDRED, Seed file test_grid.sed read successfully
CWORD-I-SEDADD, Adding seed "banana" to 9 Across

++

Once this step is overcome, further seeding of the input grid can now
take place.  A menu interface similar to that found in the "Generate
grid" for creating a grid is then presented to the user: 

++

The following lights can be seeded :

  1 Across (-)  9 Across (S) 10 Across (-) 11 Across (-) 12 Across (-)
 13 Across (-) 17 Across (-) 19 Across (-) 20 Across (-) 21 Across (-)
 23 Across (-) 27 Across (-) 28 Across (-) 29 Across (-) 30 Across (-)
 31 Across (-)  2   Down (-)  3   Down (-)  4   Down (-)  5   Down (-)
  6   Down (-)  7   Down (-)  8   Down (-) 14   Down (-) 15   Down (-)
 16   Down (-) 17   Down (-) 18   Down (-) 22   Down (-) 24   Down (-)
 25   Down (-) 26   Down (-)

       ***** Press H for help on all commands available *****
Enter seed generation command [A] :

++

Get a list of all possible commands that can be used at this time by
pressing h or ?: 

++

Enter seed generation command [A] : h

Here is a short description of each command available:

## A - Add a new seed to the grid
## D - Delete an existing seed from the grid
## L - List all seeded lights in the grid
## R - Reset all seeded lights to NULL in the grid
## V - View grid with seeded lights
## F - Finish seeding and start filling
## Q - Quit seeding and return to menu
## H - Get this screen :-)

++

To add a seed to the grid, you must first specify the light to be
seeded and then provide a valid light:

++

Enter seed generation command [A] :
Clue number which to seed (1-31) [no default] : 9
CWORD-I-DEFDIR, Across direction chosen for light
Input seed light (6 letters long) : banana?
Matching taking place.
CWORD-I-SEED+, Light "banana" seeded at 9 Across

++

The seed "banana" has been successfully added to the grid.  This can be
seen when the menu command line is again displayed: 

A message is sometimes outputted if the light being seeded cuts
through an existing light definition.  The template - which the light
being inputted has to satisfy - is displayed to aid the user in
making a valid selection.

++

The following lights can be seeded :

  1 Across (-)  9 Across (S) 10 Across (-) 11 Across (-) 12 Across (-)
 13 Across (-) 17 Across (-) 19 Across (-) 20 Across (-) 21 Across (-)
 23 Across (-) 27 Across (-) 28 Across (-) 29 Across (-) 30 Across (-)
 31 Across (-)  2   Down (-)  3   Down (-)  4   Down (-)  5   Down (-)
  6   Down (-)  7   Down (-)  8   Down (-) 14   Down (-) 15   Down (-)
 16   Down (-) 17   Down (-) 18   Down (-) 22   Down (-) 24   Down (-)
 25   Down (-) 26   Down (-)

Enter seed generation command [A] 

++

Notice beside 9 Across the "S" (Seeded) between the brackets.  This
tells the user that 9 Across has been seeded.  If you try to seed 9
Across again, look what happens: 

++

Enter seed generation command [A] : a
Clue number which to seed (1-31) [no default] : 9
CWORD-I-DEFDIR, Across direction chosen for light
CWORD-W-DELFRT, Light selected is already seeded - delete first

++

If you are not happy with 9 Across holding "banana", and you want to
insert another light there, you must first delete the seed before
adding a new one.  Select D (to Delete) as so: 

++

Enter seed generation command [A] : d
Clue number which to seed (1-31) [no default] : 9
CWORD-I-DEFDIR, Across direction chosen for light
CWORD-I-SEED-, Light "banana" unseeded at 9 Across
...
Enter seed generation command [A] :
Clue number which to seed (1-31) [no default] : 9
CWORD-I-DEFDIR, Across direction chosen for light
Input seed light (6 letters long) : redrum?
Matching taking place.
CWORD-W-SEEDSP, Seed spelt incorrectly - Continue (Y/N) [Y] :
CWORD-I-SEED+, Light "redrum" seeded at 9 Across
...
Enter seed generation command [A] :
Clue number which to seed (1-31) [no default] : 6
CWORD-I-DEFDIR, Down direction chosen for light
CWORD-I-LIKTHS, User input light has to match template: " e       "
Input seed light (9 letters long) : bedazzled?
Matching taking place.
CWORD-I-SEED+, Light "bedazzled" seeded at 6 Down

++

The word "redrum" will probably not be found in your dictionary.  If
not, Cword will ask you whether it is an acceptable light or not. 

Note: by adding "bedazzled" at 6 Down you bisected the previously
user-defined light at 9 Across.  Cword outputs the match template that
has to be inputted to create a valid seed to 6 Across.  If the light 
for 6 Across does not contain an e in the second letter of the word, 
Cword will not accept the light.

Note: Cword will question most multi-worded lights and will expect the
user to pass them as valid before continuing. 

To list all seeds in the grid, press L (to List): 

++

Enter seed generation command [A] : l

Lights that have been seeded include:

Seed for  9 Across is "redrum"

++

If you are interested in a graphical representation of the grid as
currently defined, select V (to View): 

++

Displaying current seeds in grid view:

+---------------+
|*#*#*#*#*-*-*-*|
|-*-*-*-*-redrum|
|*#*#*#*#*-*-*-*|
|-*-*-*-*-*#*#*#|
|*#*#*#*#*-*-*-*|
|-*-*-*-*-*#*#*#|
|*-*-*-###-*-*-*|
|#*#*#*#-#*#*#*#|
|*-*-*-###-*-*-*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
+---------------+

++

Remember: '-' is a blank cell - '*' is an unch (unchecked cell) - '#'
is a checked cell. 

If you have added many seeds to the grid and are unhappy with the
overall effect, you can do a global delete of them to return to a
blank grid by selecting R (to Reset): 

++

Enter seed generation command [A] : r
CWORD-W-DELALL, Delete all seeded lights from current grid (Y/N) [N] : y
CWORD-I-SEED-, Light "redrum" unseeded at 9 Across

++

Once you are happy with the work you have done seeding the grid you
can start *automatically* filling the grid by selecting F (to Fill): 

++

Enter seed generation command [A] : f
CWORD-I-FILLNW, Finished seeding - start grid fill immediately
Crossword has been updated - save seeds for later use (Y/N) [Y] : y
CWORD-I-WRTSED, Writing user generated seeds to test_grid.sed
CWORD-I-SEDWRT, Seed file test_grid.sed written successfully

CWORD-I-HOWGRD, The grid will be filled using:
## Dicstats weighted ## Randomly found words and
## Computer selected lights ## from word files

++

You will first be prompted whether to save the seeds you have used to
a separate file for possible later use (this is the file that will be
read upon startup of another seeding of test_grid.grd - as seen
above).  Once you have decided, Cword outputs some pertinent automatic
filler configuration parameters which might be of interest to the
user. 

Note: once grid filling has started, it cannot be stopped except by
using Control-C.  If Control-C is not used, Cword will attempt to fill
(within a predefined limited number of iterations) the grid. 

Note: pressing Control-C will exit Cword and will cause any work in 
progress to be lost.  It will not be possible to recover any lights 
previously filled before Control-C was pressed.

++

...
CWORD-I-SWRDIS, Selected word for 14 Down from generator is "statement"
CWORD-I-PERFIL, 96 percent of grid filled
CWORD-I-ITRNUM, Started iteration 112 of light generation phase
CWORD-I-CHKSRH, Need to search word file for "n e l " - yes
CWORD-I-PICKWD, Picking word for 30 Across with template: "n e l "
CWORD-I-TMPWRD, Template search using "n e l " in word file
Matching taking place.
CWORD-I-CHANGE, Changing selection mechanism for "n e l " to random
CWORD-I-SWRDIS, Selected word for 30 Across from generator is "needle"
CWORD-I-FILTIM, Time taken to fill grid was 234 seconds
CWORD-I-LGTEND, Light generation completed

+---------------+
|colorfast-m-d-a|
|-r-b-o-t-redrum|
|editorial-m-o-e|
|-u-a-e-u-dolmen|
|croissant-r-e-d|
|-e-n-t-c-tandem|
|s-u-m-she-b-a-e|
|tonneau-aileron|
|a-a-d-net-e-y-t|
|tidbit-x-p-p-e-|
|e-o-c-negotiant|
|merman-g-o-e-i-|
|e-n-b-headdress|
|needle-t-l-c-l-|
|t-d-e-telemeter|
+---------------+

Input a title for the completed crossword [test_grid] : Test 15x15
Input some remarks for the completed crossword [none] :
Input name of file to save crossword definition to [test_grid.xrd] :
CWORD-I-XRDWRT, Crossword file test_grid.xrd written

++

Once the grid has been successfully filled with lights by Cword, the
"bell" (ASCII character 7)  will ring to alert the user of the event
(filling may take some time and output much logging to the screen). 
Cword will then ask the user to input a title for the completed
crossword.  If none is inputted, the string "test_grid" will be used. 
test_grid is the name of the grid file used to generate the crossword.

It is also possible to add some remarks that will accompany the
crossword just created.  If no remarks are entered, none (i.e. no
remarks) will be used.  Cword also prompts the user to input a name in
which to store the completed crossword definition.  If none is chosen 
the default name for the crossword definition is used.

A completely different paradigm for inserting lights into the grid is
also supported by Cword: the concept of user-prompted lists.  
User-prompted lists is basically a cross between automatic filling 
and user seeding except that the automatic grid filler selects a list 
of lights which are valid for the current light being filled.  This 
list is then displayed to the user.  The user then selects the light
which he/she thinks is most appropriate for that particular location
and it gets inserted into that light location.  Filling continues like 
that until the grid is filled as before.

Note: the whole grid has to be completely filled in this manner if the 
method is selected before filling begins! 

++

CWORD-I-HOWGRD, The grid will be filled using:
## Dicstats weighted ## Randomly found words and
## User selected lights ## from word files
...

+---------------+
|*#*#*#*#*-?-*-*|
|-*-*-*-*-redrum|
|*#*#*#*#*-?-*-*|
|-*-*-*-*-*?*#*#|
|*#*#*#*#*-?-*-*|
|-*-*-*-*-*?*#*#|
|*-*-*-###-?-*-*|
|#*#*#*#-#*?*#*#|
|*-*-*-###-?-*-*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
+---------------+

CWORD-I-CHKSRH, Need to search word file for " e * * * " - yes
CWORD-I-PICKWD, Picking word for 6 Down with template: " e * * * "
CWORD-I-TMPWRD, Template search using " e       " in word file
Matching taking place.
CWORD-I-CHOICS, 426 possible matches found in word list
CWORD-I-PRUNEL, Prune matches list to manageable size
CWORD-I-PRNRAN, Pruning matching list using randomly selected words
CWORD-I-RNDLST, Obtained random selection of matches from list
List of lights obtained from template matcher for selection "
aerialist aesthetic beryllium celebrity centigram deathblow decadence
deciduous demulcent deodorant derringer designate desultory headstall
heartache heartless hemstitch herculean heritable jellyfish leastwise
leitmotiv mechanics melodious menagerie mercenary mezzanine necrology
negotiate recommend rectangle religious reminisce repertory reputable
reservoir retaliate reverence revulsion secession secretion semantics
semifluid separator servility tellurium venturous vermiform vertebral
wearisome
CWORD-I-RANDWD, Random word chosen indexed (9 of 50)
Accept the generated light "religious" (Y/N) [Y] : Y
CWORD-I-SWRDIS, Selected word for 6 Down from generator is "religious"
CWORD-I-PERFIL, 6 percent of grid filled
CWORD-I-ITRNUM, Started iteration 2 of light generation phase

+---------------+
|*#*#*#*#*-r-*-*|
|-*-*-*-*-redrum|
|*#*#*#*#*-l-*-*|
|-*-*-*-*-?i????|
|*#*#*#*#*-g-*-*|
|-*-*-*-*-*i*#*#|
|*-*-*-###-o-*-*|
|#*#*#*#-#*u*#*#|
|*-*-*-###-s-*-*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
|#*#*#*-*-*-*-*-|
|*-*-*-*#*#*#*#*|
+---------------+

CWORD-I-CHKSRH, Need to search word file for " i * *" - yes
CWORD-I-PICKWD, Picking word for 11 Across with template: " i * *"
CWORD-I-TMPWRD, Template search using " i    " in word file
Matching taking place.
CWORD-I-CHOICS, 340 possible matches found in word list
CWORD-I-PRUNEL, Prune matches list to manageable size
CWORD-I-PRNRAN, Pruning matching list using randomly selected words
CWORD-I-RNDLST, Obtained random selection of matches from list
List of lights obtained from template matcher for selection "
airman bikini biopsy circle dickey dimity dipper
divert fillet finish fitful gibber gifted gimlet
jiggle kitten lichen lineup liquid lively midden
midway miscue misuse nicker piddle pigeon pigsty
pillar pinion pipkin pirate riband sickle siesta
simian simony single ticket tights tinker tippet
victim virile vitals wiggle willow winkle wisdom
zinnia
CWORD-I-RANDWD, Random word chosen indexed (14 of 50)
Accept the generated light "gimlet" (Y/N) [Y] :
...

++

List grids suitable for filling 
===============================

This is exactly similar to the functionality described in "List grids
suitable for printing" in the "Generate grid" section. 

List crossword files suitable for printing
==========================================

This option searches the current working directory and returns some
information about each of the crossword files it finds therein.

++

Please input user choice : 3
Info on crossword file(s) *.xrd from default directory:
--------------------------------------------------------------------------------
File name         | Crossword Name    X dims  Y dims   Clue no    Completed
--------------------------------------------------------------------------------
TEST_GRID.XRD;2   | Test 15x15          15       15       32         No

++

The only header that is different from those already discussed in
"List grid files suitable for printing" in "Generate grid" is: 

Completed: tells the user whether the crossword has been fully user
defined i.e. whether all clues in the crossword have been filled by
the user or not.  If the crossword has just been filled it will return
a not completed status as no clues have yet been added by the user.

Report on crossword definition
==============================

This option is used to obtain more information about the crossword the
user has selected.  In this example, information about the crossword
just filled is displayed. 

++

Report on crossword definition [suffix .xrd] : test_grid

Report on crossword definition Test 15x15" : 

Dimensions are 15 by 15

Block grid found

Inputted grid is 25 percent checked, 48 percent unchecked and 27 percent blank

Light lengths     :   3  6  7  9
Light frequencies :   4 12  4 12

Total number of lights defined is 32

Inputted crossword is not fully specified

Press return to view the current crossword grid

+---------------+
|colorfast-m-d-a|
|-r-b-o-t-redrum|
|editorial-m-o-e|
|-u-a-e-u-dolmen|
|croissant-r-e-d|
|-e-n-t-c-tandem|
|s-u-m-she-b-a-e|
|tonneau-aileron|
|a-a-d-net-e-y-t|
|tidbit-x-p-p-e-|
|e-o-c-negotiant|
|merman-g-o-e-i-|
|e-n-b-headdress|
|needle-t-l-c-l-|
|t-d-e-telemeter|
+---------------+

++

Write crossword to text file
============================

This option will print a crossword definition to an output text file.
This functionality should be used if the user wants to view a text
representation of the crossword definition.  The text crossword
representation is useful but is of inferior quality to the postscript
representation described below.  This option should really only be
used if a postscript printer/interpreter is not available. 

++

Please input user choice : 5
Please input name of file to output [suffix .xrd] : test_grid
CWORD-I-XRDOUT, Crossword file selected for outputting is test_grid.xrd
CWORD-I-SLCTPS, Selecting output option - Block
test_grid.dat already exists.  Overwrite (Y,N) [Y] : y
CWORD-W-OVWFIL, *Warning* overwriting file test_grid.dat
CWORD-I-TXTWRN, Text file test_grid.dat written

++

Note: because a file called test_grid.dat already exists in the
current working directory, Cword will prompt the user whether
test_grid.dat should be overwritten with the output of the crossword
definition or not.  If you type N, Cword will give you the option to
give the output text file a new name.  (Remember what is in the
original test_grid.dat?) 

This text file will take a form similar to the grid definition text
file.  Extra information will, of course, be provided similar to the 
format in which a real crossword is usually presented.

This text output will usually take the form: 

Page 1: Empty grid and clues.

Page 2: Completed grid.

With bigger grids, Cword will print the grid on a separate page with
the clues following on another page.  The solution grid will be
printed on a third logical page. 

Write crossword to postscript file
==================================

This option will print a crossword definition to an output postscript
file.  This functionality should be used if the user wants to view/use
a postscript representation of the crossword definition.  This is the
preferred method of creating a hardcopy version of the crossword
definition. 

Output from this option will take a form similar to that seen above in 
"Write crossword to text file".

Note: the next three options may or may not appear depending upon
whether Cword has been built with relational database support enabled.

                                  || ----- ||



Complete
--------

This section describes how to complete - with clues - a filled
crossword grid.  The section also describes the purpose of all the
other functionality hanging off main menu option 3. 

When option 3 is selected from the main menu, the following menu
should be presented to the user: 

++

--------------------------------------------------------------------------------
                Sandman Software presents : Cword V1.0
--------------------------------------------------------------------------------

        3.  Complete crossword

                (1)  Complete crossword definition
                (2)  List crossword files suitable for completion

                (3)  Write crossword to text file
                (4)  Write crossword to postscript file

                (5)  Read crossword from database
                (6)  Write crossword to database
                (7)  Delete crossword from database
                (8)  List crosswords in database

                (9)  Add clue to database
                (10) Get clue from database
                (11) Delete clue from database
                (0)  Back to main menu!

Please input user choice :

++

Complete crossword definition
=============================

This option should be chosen once the crossword has been filled with
lights (either from seeding, user or automatic filling).  This
functionality allows the user to add valid clues to the crossword. 
After filling, the crossword contains only default clues.  Default 
clues are clues that contain the light data until otherwise defined by
the crossword setter. 

++

Please input user choice : 1
Input crossword definition for clue generation [suffix .xrd] : test_grid

Input clue descriptions for any part of the following crossword:

  1 Across (-)  9 Across (-) 10 Across (-) 11 Across (-) 12 Across (-)
 13 Across (-) 17 Across (-) 19 Across (-) 20 Across (-) 21 Across (-)
 23 Across (-) 27 Across (-) 28 Across (-) 29 Across (-) 30 Across (-)
 31 Across (-)  2   Down (-)  3   Down (-)  4   Down (-)  5   Down (-)
  6   Down (-)  7   Down (-)  8   Down (-) 14   Down (-) 15   Down (-)
 16   Down (-) 17   Down (-) 18   Down (-) 22   Down (-) 24   Down (-)
 25   Down (-) 26   Down (-)

       ***** Press H for help on all commands available *****
Enter clue generation command [A] :

++

You will immediately see that the user interface for this option is
similar to that presented during seeding.  This is because the
mechanisms for seeding and clue completion are very similar.

To gain a little help about each of the options available type h (to
Help): 

++

Enter clue generation command [A] : h

Here is a short description of each command available:

## A - Add a clue description
## Q - Quit the clue generation phase
## S - Save the crossword description with the clue descriptions added
## V - View grid filled with light definitions
## L - List clue descriptions that have been user-defined
## R - Reset description of selected user-defined clue
## H - Get this screen :-)

++

All lights will have been defined at this stage.  It will not be
possible to undefine lights using this menu.  This menu interface is
designed only to create clues for lights already in the grid being
completed. 

To add clue definitions is as simple as pressing return at the menu
command line since the default command is A (to Add/Alter): 

++

Enter clue generation command [A] :
Please input valid clue number (1-31) [1] :
CWORD-I-DEFDIR, Across direction chosen for light

Adding/Altering clue descriptions

Processing clue : 1 Across

Light to clue : colorfast
Default clue description is : "colorfast"

Processing clue : 1 Across

Please input a valid clue description :
 -> Hue quick together for something that never fades


Now getting light characteristics:

Input light dimensions to be used in clue description (1 to 9) [9] :

Total clue description is now : "Hue quick together for something that 
never fades (9)"
CWORD-I-VLDCLU, Valid clue description found for 1 Across

++

Note: many of the questions Cword poses contains default values which
the user can accept, if required.  In this case the user has defined a
clue for colorfast (1 Across).  The clue is "Hue quick together for
something that never fades".  When this clue is added to the light
information, the full clue will look like:

Hue quick together for something that never fades (9)

If the light is made up of two distinct words, the user can define the
dimensions of the light in the menu presented after the clue input
phase as so: 

++

Enter clue generation command [A] :
Please input valid clue number (1-31) [9] :
CWORD-I-DEFDIR, Across direction chosen for light
 
Adding/Altering clue descriptions

Processing clue : 9 Across

Light to clue : redrum
Default clue description is : "redrum"

Processing clue : 9 Across

Please input a valid clue description :
 -> possibly a drink and certainly a horse
CWORD-W-1STCHR, First character 'p' converted to uppercase

Now getting light characteristics:

Input light dimensions to be used in clue description (1 to 6) [6] : 3
Input light dimensions to be used in clue description (1 to 3) [3] : 3

Total clue description is now : "Possibly a drink and certainly a horse (3,3)"
CWORD-I-VLDCLU, Valid clue description found for 9 Across

++

Note: Cword does some error checking on the inputted clue description. 

It checks:

* Whether the inputted clue starts with an upper case letter.

* Whether the clue description contains the clue answer (or light).

If you type 0 when inputting light dimensions, Cword will interpret
this clue as being special and will not append any light information
onto the clue definition:

++

Input light dimensions to be used in clue description (1 to 6) [6] : 0
CWORD-I-ZERLEN, Special case: no light info will be added to clue

Total clue description is now : "Possibly a drink and certainly a horse"

++

As the crossword definition evolves, the menu interface will display
this fact in a manner very similar to that seen during seeding.  This
is done with the use of the letter "C" (Clued / Completed) within the
brackets when the crossword definition statistics are displayed: 

++

Input clues descriptions for any part of the following crossword:

  1 Across (C)  9 Across (C) 10 Across (-) 11 Across (-) 12 Across (-)
 13 Across (-) 17 Across (-) 19 Across (-) 20 Across (-) 21 Across (-)
 23 Across (-) 27 Across (-) 28 Across (-) 29 Across (-) 30 Across (-)
 31 Across (-)  2   Down (-)  3   Down (-)  4   Down (-)  5   Down (-)
  6   Down (-)  7   Down (-)  8   Down (-) 14   Down (-) 15   Down (-)
 16   Down (-) 17   Down (-) 18   Down (-) 22   Down (-) 24   Down (-)
 25   Down (-) 26   Down (-)

Enter clue generation command [A] :

++

Notice how 1 Across and 9 Across have both been completed!  It is
possible to change the clue definitions by simply inputting A (to
Add/Alter) again.  Altering the clue description will override the 
previous clue description.

To view the clues currently defined type L (to List):

++

Enter clue generation command [A] : L

Reviewing current clue definitions:

1 Across: "Hue quick together for something that never fades ..." - "colorfast"
9 Across: "Possibly a drink and certainly a horse (3,3)" - "redrum"

CWORD-I-NOTALL, Not all the clue descriptions have been defined

++

The clue for 1 Across is too long to display correctly so Cword
displays as much as it can of it and append "..." to signify that
there is more to the clue than currently can be displayed. 

"..." are used in circumstances when the output data will not fit into
the text box allocated to it. 

If you are not happy with a clue definition you can reset it back to 
its default form by pressing R (to Reset):

++

Enter clue generation command [A] : r
Resetting user-defined contents of clue description to default

Please input valid clue number (1-31) [9] :
CWORD-I-DEFDIR, Across direction chosen for light
CWORD-I-RESETS, Resetting clue description for 9 Across

++

If you want to view the grid and the lights within press V (to View): 

++

Enter clue generation command [A] : v

+---------------+
|colorfast-m-d-a|
|-r-b-o-t-redrum|
|editorial-m-o-e|
|-u-a-e-u-dolmen|
|croissant-r-e-d|
|-e-n-t-c-tandem|
|s-u-m-she-b-a-e|
|tonneau-aileron|
|a-a-d-net-e-y-t|
|tidbit-x-p-p-e-|
|e-o-c-negotiant|
|merman-g-o-e-i-|
|e-n-b-headdress|
|needle-t-l-c-l-|
|t-d-e-telemeter|
+---------------+

++

You can exit this phase, with the clues partially completed, by simply
saving the crossword, selecting S (to Save): 

++

Enter clue generation command [A] : s
CWORD-I-CLUESV, Save and quit clue generation phase
CWORD-I-SAVCLU, Saving crossword definition as it has changed

CWORD-W-NOTCOM, Crossword not fully defined 

test_grid.xrd already exists.  Overwrite (Y,N) [Y] : y
CWORD-W-OVWFIL, *Warning* overwriting file test_grid.xrd
CWORD-I-XRDWRT, Crossword file test_grid.xrd written

++

The updated crossword can be re-read and updated at a later stage as
so: 

++

Please input user choice : 1
Input crossword definition for clue generation [suffix .xrd] : test_grid

Input clues descriptions for any part of the following crossword:

  1 Across (C)  9 Across (-) 10 Across (-) 11 Across (-) 12 Across (-)
 13 Across (-) 17 Across (-) 19 Across (-) 20 Across (-) 21 Across (-)
 23 Across (-) 27 Across (-) 28 Across (-) 29 Across (-) 30 Across (-)
 31 Across (-)  2   Down (-)  3   Down (-)  4   Down (-)  5   Down (-)
  6   Down (-)  7   Down (-)  8   Down (-) 14   Down (-) 15   Down (-)
 16   Down (-) 17   Down (-) 18   Down (-) 22   Down (-) 24   Down (-)
 25   Down (-) 26   Down (-)

       ***** Press H for help on all commands available *****
Enter clue generation command [A] :

++

Remember how 1 Across was previously defined when the clue completion
phase was exited on the first occasion?  It retains its clue
definition upon being first saved. 

It is possible to quit clue generation without saving any work in
progress by selecting Q (to Quit): 

++

Enter clue generation command [A] : q
CWORD-W-CHGMAD, Changes have been made to crossword definition
Do you want to continue quitting (Y/N) [Y] : y
CWORD-W-QUTUNS, Quitting clue generation without saving result

++

If Q is selected and no changes have been made to the crossword
definition, Cword will quietly return to the main user interface.

If new clues have been added to the crossword definition, Cword will
prompt the user whether to overwrite the current crossword definition
file or create a new file containing the updated crossword definition.

Once all the clues have been defined, Cword will output the following
message: 

++

CWORD-W-ALLCUD, ** All clues have been user defined **

++

Once the user is happy with the crossword, the definition should be
immediately saved and printed for checking.  The crossword can
continue to be refined the crossword using this functionality until
the user is completely satisfied with the crossword. 

List crossword files suitable for completion
============================================

This option is exactly similar to "List crossword files suitable for
printing" in "Fill grid". 

Write crossword to text file
============================

This option is exactly similar to "Write crossword to text file" in 
"Fill grid".

Write crossword to postscript file
==================================

This option is exactly similar to "Write crossword to postscript file" 
in "Fill grid".

Note: the next four options may or may not appear depending upon
whether Cword has been built with relational database support enabled.

Read crossword from database
============================

This option will take a crossword definition - which has been
previously stored in the database - and create a crossword file in
the current working directory containing the crossword.  The file
specification is user supplied. 

++

Please input user choice : 5
Input name of crossword to be read from database : test_grid
CWORD-I-DBXRSC, crossword "test_grid" read successfully from database
Input file spec to save crossword to [suffix .xrd] : test_cross
CWORD-I-XRDWRT, Crossword file test_cross.xrd written

++

Write crossword to database
===========================

This option will take a crossword definition and store it in the
database.  The grid will now be referenced in the database only by the
crossword definition's name. 

++

Please input user choice : 6
Input crossword file to write to database [suffix .xrd] : test_grid
CWORD-I-DBADCR, Added crossword_description successfully
CWORD-I-DBADCL, Added clue_descriptions successfully
CWORD-I-DBSUCC, crossword "test_grid" added successfully to database

++

Delete crossword from database
==============================

This option will delete the user-defined crossword definition from the
database. 

++

Please input user choice : 7
Input name of crossword to be deleted from database : test_grid
CWORD-I-DBXDSC, crossword "test_grid" deleted successfully from database

++

List crosswords in database
===========================

This option will display the names of all the crossword definitions
currently stored in the database. 

++

Please input user choice : 8
The following crosswords are currently in the database:
test_grid

++

Add clue to database
====================

This option allows the user to add a user-defined clue to the
database. 

++

Please input user choice : 9
CWORD-I-PUTCLU, Put a clue into database
Please input clue answer to be inserted into database : james
Please input clue to be inserted into database : Who is the man?
## Clue/answer pair added successfully

++

Get clue from database
======================

This option allows the user to fetch a single clue definition from the 
database.

++

Please input user choice : 10
CWORD-I-GETCLU, Get a clue from the database using clue answer
Please input clue answer which to search for : james
## Clue found in db for "james" is "Who is the man"

++

Delete clue from database
=========================

This option allows the user delete a user-defined clue from the 
database.

++

Please input user choice : 11
CWORD-I-GETCLU, Delete a clue from the database using clue answer
Please input clue answer which to search for : james
## Clue successfully deleted

++

                                  || ----- ||


Word utilities
--------------

This section describes how to execute all the word utilities hanging
off main menu option 4. 

When option 4 is selected from the main menu, the following menu should 
be presented to the user:

++

--------------------------------------------------------------------------------
                Sandman Software presents : Cword V1.0
--------------------------------------------------------------------------------

        4.  Word functions

                (1)  Spell check
                (2)  Template match
                (3)  Intersect template match
                (4)  Wildcard match
                (5)  Sub-anagram generator
                (6)  Total anagram generator
                (7)  Super-anagram generator
                (8)  ROT 13 decoder
                (9)  Soundex generator
                (10) Webster definition
                (0)  Back to main menu!

Please input user choice :

++

Note: all matches found in the following utilities are uniquely
obtained from the series of word files defined in the configuration 
file. 

Note: if output from any of these options is over one page in size,
Cword allows the user to scroll through the return data in a
structured manner as described in an earlier section. 

Spell check
===========

This option checks the correctness of a user-defined word against the 
user-defined word files. 

++

Please input user choice : 1
Please input word to be spell checked : james
Matching taking place.
CWORD-E-SPLERR, The word "james" is *not* found in word files

++

Does this mean I do not exist ;-)?

Template match
==============

This option allows the user to input a word template.  This template
is then matched against the user-defined word files and successful
matches are returned to the screen for viewing. 

Spaces (' '), question marks ('?'), dots ('.'), and percent ('%')
characters can be used to signify characters that are unknown in the
template.  Alphabetic input to this option is case insensitive. 

++

Please input user choice : 2
Please input string template to search for : j?.% S
CWORD-I-TMPWRD, Template search using "j    s" in word file
Matching taking place.
List of words returned include :
joyous

++

Intersect template match
========================

This option is a variation of "Template match" except that instead of
operating with a single word - or template - you work with two words -
or templates - which intersect at some known point.  This option is
particularly useful when solving a crossword if you are left with an
intersecting couplet of lights, of which you have got some of the
checked letters.  Pop the light information into Cword and let it
return to you with a list of couplets which fit the input parameters. 

++

Please input user choice : 3
Intersect: Input two words with the character ? where they cross
Please input intersect string 1 : s.?.s
Please input intersect string 2 : w..?.
CWORD-I-INTERS, Intersect "s ? s" with "w  ? "
Matching taking place.
Matching taking place.
CWORD-I-NUMINT, 6 matching pairs of words found
List of intersects include :
sinus-weeny sinus-whine sinus-wound sinus-wring
sinus-wrong sinus-wrung

++

The question mark character ('?') denotes the location of the
intersection.  The question mark can only be used in this context; 
other characters (percents, spaces, dots) have to be used otherwise to
specify unknown characters. 

In the crossword puzzle the two lights might look something like this:

            w                                   s
            .                                   .
            .                or              w..?.
          s.?.s                                 .
            .                                   s

Wildcard match
==============

This option will match the inputted string against the user-defined
word files.  It allows wildcard ('*') string matching along with the
more usual question mark, space, percent and dot character matching
mechanisms. 

++

Please input user choice : 4
Please input string to search for : j*s?
Getting strwild words.
List of words returned include :
jackass jellyfish jess jest jingoism jitters jocose joist josh joss
journalese journalism joust jujitsu jurist just juxtapose 

++

Sub-anagram generator
=====================

This option will generate all sub-anagrams of a user-defined word
which are greater than or equal to a user-defined length.  The user
can also specify a letter which must be present in the output
sub-anagrams.  This feature is especially useful for some newspaper 
word puzzles.  If you happen to win anything using this generator, I
think I deserve at least 10% of the winnings ;-). 

++

Please input user choice : 5
Please input min expected length of returned anagrams : 5
Please input string from which to obtain anagrams of : jamesalundon
Please input letter from string which will be in all anagrams [none] :
CWORD-I-GENSUB, Generating sub-anagrams using "jamesalundon"
CWORD-I-TARGET, No centre letter : anagram size > 4 : letters "jamesalundon"
Getting sub-anagrams.
CWORD-I-SUBFND, 66 sub or full anagrams found
List of words returned include :
almond adman alone aloud alumna amend amends amuse anadem annals anneal
annual annul anode daemon damsel damson demon dolmen douse duenna jealous
jeans laden landau landsman lemon louse maenad manes manna manned manse
manual mason medal melon model module mould mound mouse mundane nasal nausea
nelson nodule nomad nones olden salad salmon salon sandal sandman seaman
sedan seldom senna solemn sound sundae unlade unload unman unseal

++

Total anagram generator
=======================

This functionality has not been implemented yet.  See the section on 
Limitation of Cword in the Appendices.

Super-anagram generator
=======================

This option generates all words which contain each of the letters of
the user-defined string at least once. 

++

Please input user choice : 7
Please input string for super-anagram : james
Getting super anagrams.
List of words returned include :
jessamine jasmine jetsam majesty majuscule maladjusted

++

Me maladjusted - never!

ROT 13 decoder
==============

This option implements the simple decryption algorithm ROT13 commonly
used on Usenet.  For those of you who do not know what Usenet is, it
is a world-wide bulletin board system layered on top of the Internet or
more correctly on top of TCP/IP.  Usenet allows people of common
interests to electronically discuss their favourite pastimes e.g.
crosswords.  ROT13 is used to conceal certain information or messages
that a user might not like to immediately understand.  Be assured that 
many people find this facility useful in certain contexts.

++

Please input user choice : 8
Please input word to ROT13 decode : wnzrf vf gur zna
CWORD-I-ROTSTR, The ROT'ed string : "james is the man"

++

Soundex generator
=================

This option will display all words which the Soundex Algorithm selects
as sounding most like the user-defined string (otherwise known as
homophones). 

The Soundex Algorithm is a simple algorithm which determines whether
the reference word "sounds" like all other words presented to it.  This
algorithm is frequently used by telephone operators to get matches for
surnames which "sound" similar to an inputted surname (probably
phonetically spelled).  It has other uses such as to return all 
similar sounding words given a good reference word, as below.

Note: many of the choices the Soundex Algorithm generates may not be
accurate, or correct, such as junk from the reference word james. 

++

Please input user choice : 9
Please input string which to generate soundex equivalents of : james
CWORD-I-SOUNDX, Getting soundex equivalents of "james" (same starting letter)
CWORD-I-SNDEX2, Selected word is james - soundex template is J520
Getting soundex words.
List of soundex matches include :
jeans jinx jounce junco junk

++

Webster definition
==================

This option is only available if you have direct TCP/IP access to the
Internet and have correct access to a remote Webster's dictionary
server i.e. through your local corporate firewall or via your local
Internet provider etc. 

A remote Webster's dictionary server is accessed and queried with a
user-defined word.  The definition of the word inputted is returned
and displayed on screen. 

++

Please input user choice : 10
Please find the Websters definition of which word : word
CWORD-I-WEBSTR, The word to search for in Websters is "word"
CWORD-I-WEBCON, Connecting to Webster server at IP address 16.1.16.1.
DEFINITION 0
1. word \'w*rd\ n [ME, fr. OE; akin to OHG wort word, L verbum, Gk eirein
   to sa] often attrib y, speak 1a: something that is said pl  1b1: TALK,
   DISCOURSE 1b2: the text of a vocal musical composition 1c: a brief remark
   or convrsation 2a1: a speech sound or series of speech sounds that 
   symbolizes and communicates a meaning without being divisible into smaller
   units capable of independent use 2a2: the entire set of linguistic forms
   produced by combining a single bse with various inflectional elements
   without change in the part of speech elements 2b: a written or printed
   character or combination of characters representing a spoken word 2c: a
   combination of electrical or magnetic impulses conveying a uantum of
   information in communication and computer work 3: ORDER, COMMAND often cap
   4a: LOGOS 4b: GOSPEL 4c: the expressed or manifested mind and will of God
   5a: NEWS, INFORMATION 5b: RUMOR 6: the act of speaking or of making verbal
   ommunication 7: SAYING, PROVERB 8: PROMISE, DECLARATION 9: a quarrelsome
   utterance or conversation - usu. used in pl. 10: a verbal signal : PASSWORD
2. word vi archaic  : SPEAK to express in words : PHRASE

CWORD-I-WEBCON, Disconnected from Webster

++

                                  || ----- ||



Misc. other utilities
---------------------

This section describes how to execute all of the miscellaneous Cword
functionality hanging off main menu option 5. 

When option 5 is selected from the main menu, the following menu
should be presented to the user: 

++

--------------------------------------------------------------------------------
                Sandman Software presents : Cword V1.0
--------------------------------------------------------------------------------

        5.  Misc. other utilities

                (1)  Alter defaults
                (2)  Break up input dictionary
                (3)  Add word to word file
                (4)  Estimate size of word files
                (5)  Database statistics
                (0)  Back to main menu!

Please input user choice :

++

Alter defaults
====================

This option allows the user to interactively alter many of Cword's
user-configuration parameters. 

Operation of this functionality is through a simple interactive menu.
The user is presented with the current configuration data and is
prompted to select one of the parameters to be altered.

++

Please input user choice : 1

Select a user default to be altered from the following list:

 1. SMALLEST_ALLOWABLE_LIGHT - 3  2. SYMMETRY_TYPE - 1
 3. X_DIMENSIONS - 13  4. Y_DIMENSIONS - 13  5. TEMP_GRID_NAME - tmp_grd
 6. UNCHES_CHECK - FALSE  7. SYMMETRY_CHECK - TRUE

 8. WORD_FILE_PREFIX - [-.words]pocket

 9. LIGHT_GENERATION_ALGORITHM - 1 10. AUTOMATIC_LIGHT_GENERATION - TRUE
11. LETTER_WEIGHT_ALGORITHM - 2 12. NEXTLIGHT_SELECT_ALGORITHM - 1
13. FILL_FROM_WHERE - 1 14. RESET_AFTER_NUM_ITERATIONS - 1000
15. TEMP_CROSSWORD_NAME - tmp_xrd 16. MAX_LIGHT_CHOICES - 50
17. MAX_LIGHT_ITERATIONS - 5000

18. WEBSTER_SERVER_NAME - 16.1.16.1 19. WEBSTER_SERVER_PORT - 10300
20. WRITE_LOG_FILE - TRUE 21. LOG_FILE_PREFIX - cword 22. TRACE_LEVEL - 1

23. SOUNDEX_ALGORITHM - 1 24. WORDS_PER_DOT - 10000 25. RING_BELL - TRUE
26. CHECK_SPELLING - TRUE 27. USERNAME - "James" 28. MAX_MATCHES - 1000

Please input default no. to alter (0 to return to the menu) :

++

Type h (to Help) for a list of valid options:

++

Please input default no. to alter (0 to return to the menu) : h

The following commands can be used (upper/lower case) :

## E - Exit Cword completely
## B - Back up to the calling menu or exit if in main menu
## H, ? - Gets this screen
## D - Displays current defaults
## 1 to 28 - Valid menu options
## !, %, $ [OS command] - Execute an OS/shell command
## CD [directory] - Set directory into [directory]
## 0 - Back up menu or exit Cword

++

To select a configuration parameter (or default) to alter, type the
number of the selection and press return.  Once the configuration
parameter is chosen you will be able to input a new value, providing
the value being inputted is valid. 

Any values changed using this interface are only applicable for the
lifetime of the *current* Cword process.  None of the changed values
are written to the configuration file. 

++

Please input default no. to alter (0 to return to the menu) : 1

## Please refer to cword.ini for more information about user defaults

## Current smallest allowable light is length 3
## Input smallest allowable light [3] : 5
## Changing smallest allowable light to 5

++

This default is used when creating a crossword grid.  Cword will now
make sure that no light smaller than 5 characters will be allowed to 
be created for the lifetime of this Cword process. 

++

Please input default no. to alter (0 to return to the menu) : 7

## Please refer to cword.ini for more information about user defaults

## Check for symmetry is TRUE
## Change symmetry check to FALSE (Y/N) [N] : y
## Changing symmetry check to FALSE

++

This default determines whether grid symmetry is checked when
verifying a grid's properties. 

++

Please input default no. to alter (0 to return to the menu) : 27

## Please refer to cword.ini for more information about user defaults

## Username is James
## Input new username [James] : Lundon
## New username is "Lundon"

++

This default is used when creating a Postscript file of a grid or
crossword definition.  The name defined here will be included in the 
header of the postscript file.

++

Please input default no. to alter (0 to return to the menu) : 8

## Please refer to cword.ini for more information about user defaults

## Add/Delete word file prefix (A/D) : a
## Please input word file prefix to be added : [-.words]allwords
## New word file prefix is "[-.words]allwords"

...
 8. WORD_FILE_PREFIX - [-.words]allwords, [-.words]pocket
...

++

This option allows word lists to be added to, or deleted from, the
existing list of word files Cword uses.  Cword verifies the existence
of any word files before adding them to the word file list.  If the
word file series does not exist, an error message is displayed as so: 

++

CWORD-E-NOWORD, No word files found for prefix "allwords"

++

All other defaults are based on one of the examples shown above. 

Note: Cword will not accept a value for a configuration parameter
without first checking that it is valid.

++

Please input default no. to alter (0 to return to the menu) : 22

## Please refer to cword.ini for more information about user defaults

## Current output trace level is 1
## Input new output trace level [1]: 7
## Error getting allowable value for option

Break up input dictionary
=========================

This option is functionally equivalent to breakdic (the standalone
executable that creates a Cword compliant word list from an input
dictionary - see Cword Adjuncts section in the appendices for more 
details).  The user specifies an input dictionary file specification. 
Cword will then create a series of word files - from the input
dictionary - in the *same* directory as the dictionary itself. 

++

Please input user choice : 2
Break up which input dictionary file : [-.dict]allwords.dic
BREAKDIC-I-CREATE, Creating temporary dictionary: clean.dic
BREAKDIC-I-INFO, Processed  10000 words - current word is "ananas"
...
BREAKDIC-I-INFO, Processed 310000 words - current word is "wingspreads"
BREAKDIC-I-INFO, All 314555 words written successfully
BREAKDIC-I-INFO, Word file prefix is [-.dict]allwords
BREAKDIC-I-INFO, [-.dict]allwords.01 word file created
...
BREAKDIC-I-INFO, [-.dict]allwords.24 word file created
BREAKDIC-I-INFO, Total number of words processed was 314555

Please input user choice : !dir [-.dict]allwords.*
CWORD-I-SYSTEM, Calling OS using "dir [-.dict]allwords.*" - on your
own from here 

Directory USER$:[USERNAME.CROSSWRD.DICT]

ALLWORDS.01;1              0  11-JUL-1995 15:09:10.88
...
ALLWORDS.28;1              0  11-JUL-1995 15:09:17.73
ALLWORDS.Z;1            2589  28-OCT-1992 18:35:14.43
ALLWORDS.DIC;2          6351  14-FEB-1994 19:53:16.95

Total of 28 files, 8940 blocks.
CWORD-I-SYSBCK, Back from the wilds of system () safely

++

Add word to word file
=====================

This option allows a user to add a word to the user-defined word
files.  It will inform the user if the word already exists in the word
files.  If more than one word file set is currently in use, Cword will
add the word to the first word file set (of requisite size) it finds.

++ 

Please input user choice : 3
## Please input word to add to word file : james
Matching taking place.
CWORD-I-ADDWRD, Adding word james to word file length 5
CWORD-I-WRDADD, Successfully added james to word file [-.words]pocket.05

Please input user choice : 3
## Please input word to add to word file : james
Matching taking place.
CWORD-I-SPELLR, The word "james" is found in word files

++

Estimate size of word files
===========================

This option outputs some statistics about the series of word files
currently defined for use in Cword. 

++

Please input user choice : 4
Outputting word file statistics:

Word file   [-.words]pocket.01 has    26 words
 Total number of words in word file(s) of length  1 is     26
...
Word file   [-.words]pocket.19 has     3 words
 Total number of words in word file(s) of length 19 is      3

  Total words currently accessible in word files is 21112

++

Note: the next option may or may not appear depending upon whether
Cword has been built with relational database support enabled. 

Database statistics
===================

This option displays some simple quantitative statistics about the
current contents of the Cword relational database.  The information
provided includes: 

1. number of grids currently stored in database.
2. number of crosswords currently stored in database.
3. number of unattached clues currently stored in database.

++

Please input user choice : 5

Please wait while polling the database...

There is 1 crossword in the database

There are 2 grids in the database

There are 2 unattached clues stored in the database

++

Note: unattached clues, in this context, are any clues which are not
associated with any crosswords already stored in the database. 


                                  || ----- ||


Technical appendices
--------------------

Cword Adjuncts
==============

A standalone program called breakdic (BREAKDIC.EXE on OpenVMS) is
provided as part of the Cword distribution.  This program allows the
user create Cword compatible word files which can then be used by the
application proper.  breakdic is built as part of Cword's build
procedure on all platforms.  Equivalent functionality to breakdic is
provided in the user interface of Cword. 

There is another program available from the author (not part of the
Cword distribution) which allows the user re-create dicstats.h from an
input dictionary.  The version of dicstats.h shipped as part of the
Cword kit was created one of the author's own dictionary files using
this program.  dictstats.h is used by the automatic grid filler to
obtain some important probability data useful during light filling. 



Configuration File
==================

cword.ini is the usual name given to Cword's configuration file.  It
contains approx. 28 configuration parameters, each of which can alter
the operation of specific parts of Cword.  Areas which are most
affected by the configuration file include: 

* grid creation.
* grid filling.
* word file processing.
* trace file processing.

For more information see the configuration file itself or Cword's
menu option 5.1.  The configuration file is fully documented and 
should contain enough information for the user to understand its 
functions.



Cword Related File Formats
==========================

The following section details the internal format of the files created
or used by Cword. 

The following file formats are discussed:

* Cword grid file format.

* Cword crossword file format.

* Cword seed file format.

* Cword word file format.

Cword grid file format
----------------------

The basic format of a Cword grid file is as follows:

The first line of the grid file contains the title of the grid
definition. 

The second line contains five values:

* X dimensions of grid
* Y dimensions of grid
* Number of lights in grid
* Cword grid type identifier - more information in main.h
* Cword symmetry type identifier - more information in main.h

For example:

15 15 32 1 1

This signifies that this grid is 15x15, contains 32 light definitions
and is a block grid with 90 degree symmetry. 

(More information on grid and symmetry types is available in the Cword
source code.)

The third to last lines of the grid file contains the light
definitions - one per line of the following format: 

Light-direction X-dimension Y-dimension Light-length

For example:

A 1 15 9

This signifies that this light definition is for an across light, is
located at (1,15) and is of length 9. 

Cword crossword file format
---------------------------

The basic format of a Cword crossword file is as follows:

The first line contains the title of the crossword definition. 

The second line contains the remarks text of the crossword definition.

The third line contains five values: 

* X dimensions of grid
* Y dimensions of grid
* Number of lights in grid
* Cword grid type identifier
* Cword symmetry type identifier

For example:

15 15 32 1 1

This signifies that the crossword is 15x15, contains 32 clue
definitions and is a block grid with 90 degree symmetry. 

(More information on grid and symmetry types is available in the Cword
source code.)

The fourth to last lines of the crossword file contain the clues -
three lines of text per clue with the following format: 

Line 1 format - Clue co-ordinates

The format of this line is:

Clue-number Clue-direction X-dimension Y-dimension Light-length 

For example:

1 A 1 15 9

This signifies that the clue is 1 across, is located at (1,15) and is
of length 9. 

Line 2 format - Clue description

For example:

Hue quick together for something that never fades (9)

Line 3 format - Light contents

For example:

colorfast

Cword seed file format
----------------------

The basic format of a Cword seed file is as follows:

The first line contains four values:

* Name of grid 
* X dimensions of grid
* Y dimensions of grid
* Number of lights in grid

For example:

test_grid 15 15 32

This signifies that the seed file is for a grid called test_grid.  The
grid is 15x15 and contains 32 lights.  This extra information is
provided so as to make sure that this seed file is as uniquely
identified with the corresponding grid file as possible. 

The second to last lines contains the seed information - one seed per
line. 

For example:

9 A 10 14 6 redrum

This signifies that the seed is for 9 across, is at location (10,14),
is 6 letters long and contains the seed "redrum".  To Cword, "redrum"
is a light of six letters.  Cword does not really understand the
concept of multi-word lights as yet - but that is a different story 
(see Limitations of Cword point 4). 

Cword word file format
----------------------

The word file format Cword uses is very straightforward to understand.
Every word file contains words only of a specific length; so a word
file named word.05 will contain only words of 5 characters in length. 

All words (or phrases) have a line to themselves in the file.  All
words are separated by a carriage return and/or line feed. 

All word files are readable with any text editor.

No other Cword application specific information is encoded in any
Cword word files, so any word files used by Cword could, in theory, be
used by any other applications that use straight text format word
files. 

No characters other than the characters 'a' to 'z' inclusive are
allowed in Cword word files. 



Cword Trace Log File
====================

The trace log file is a useful adjunct to Cword's operations.  This
file, if enabled, will encapsulate much data about Cword's current
operations.  It can be very useful for debugging purposes! 

Incremental levels of information can be written to the log file.  The
amount of information written to the trace log file depends on the
value of TRACE_LEVEL defined in cword.ini (this value can be changed
via the user interface or in cword.ini itself). 

Each invocation of Cword creates a different log file, so that no log
file will be overwritten.  Cword's trace log file naming convention
is: 

LOG_FILE_PREFIXnn.LOG 

where LOG_FILE_PREFIX is defined in cword.ini and 01 <= nn <= 99.

If trace log file processing is enabled, many log files may build up
in Cword's working directory.  If you are not interested in an audit
trail of Cword, set WRITE_LOG_FILE to FALSE.  No more trace log files
will be created until WRITE_LOG_FILE is set to TRUE again. 

If you find a bug, I would appreciate it if you could try to
re-produce it with full logging enabled.  By sending the log file to
me, together with a description of the bug, I will have a much better
chance of fixing it than just by a description alone. 

 

Cword File Extensions
=====================

Many different files are used in (and by) Cword.  The following is a
list of all the possible file suffixes you may come across in Cword. 
A short explanation of each will be provided, where necessary. 

.c /.sc / .h / .mms / .com / .sh / .sql / .txt / .1st / .me / .prj /
.mak / .opt / makefile. / .obj / .exe / .o

All the above suffixes are found in the sources of Cword.

.sed / .grd / .xrd 

These are respectively the seed, grid and crossword file prefixes
generated by Cword. 

.dat / .ps

These are the print file suffixes generated by Cword.  Respectively
they contain text and postscript output.

.log

Cword's trace log file suffix.

.01-.40

Cword's word file suffixes.

.ini

Cword's configuration file suffix.



Glossary of Crossword Terms
===========================

Cell: location in grid into which an individual character from the
associated light(s) is assigned.  A cell that is not assigned to any
light is known as a blank. 

Light: sequence of adjoined cells (horizontal or vertical) in a grid
corresponding to the (transformed) answer of the associated clue. 

Grid: arrangement of cells that together form a grid or crossword
diagram. 

Clue: word or series of words provided by the crossword compiler which
leads to an answer that may be directly (or indirectly through some
defined transformation) inserted into the grid provided. 

Crossword: combination of grid and clues. 

Solution: grid filled with completed lights.

Answer: word or series of words which form the answer to the
associated clue.  The answer may have be transformed before being
inserted into the grid. 

Direction: the orientation of the specified answer or light.  The
direction may be either across (horizontal) or down (vertical). 

Blank: cell in a grid that is not related to any light.  Such cells
are usually blackened out when displayed. 

Unch: cell in a grid that is part of one light (and only one).  The
light can be either across or down in orientation. 

Checked: cell in a grid that is part of two (and only two) lights. 
The cell will be part of only one across and one down light. 

Disjoint: grid posessing one or more lights that do not bisect any
other lights in the specified grid. 

Seed: light inserted, by the crossword compiler, into the grid before
automatic filling of the crossword is initiated. 

Compiler: person who creates or compiles crosswords (with Cword?).
This person can also be known as a crossword builder or crossword
composer. 

Cryptic: clue or crossword where the answer(s) emerge from the clue
text using standard or non-standard word play techniques. 

Definition: clue or crossword where the answer(s) emerge from the clue
text as definitions. 

Fill: action where the grid is filled with lights either by the human
crossword compiler or automatically by Cword. 

Anagram: word or words made up by transposing the letters of another 
word or words.

Homophone: one of two or more words pronounced alike but different in
meaning or spelling. 



Bibliography
============

Books, papers and programs referenced during Cword development can be
found on the WWW (World Wide Web) from either of the sources detailed
below: 

* URL for latest version of the rec.puzzles.crosswords FAQ:

    http://rtfm.mit.edu/pub/usenet-by-hierarchy/rec/puzzles/crosswords

* URL for Crossword Archive:

    ftp://gatekeeper.dec.com/pub/micro/msdos/misc/crossword-archive



Contacting the Author
=====================

I may be contacted electronically (via the Internet) at
jlundon@xstacy.enet.dec.com or jlundon@ilo.dec.com.  If this address
is invalid, check with postmaster@xstacy.enet.dec.com or
postmaster@ilo.dec.com for another address. 

My snail mail business address can be found in READ.ME.  If I cannot
be accessed using either of the E-mail addresses given above, it is
also unlikely that I will be reached at my snail mail business address
either. 

However, I can always be reached at: 

James A. Lundon,
Pallasbeg,
Cappamore,
Co. Limerick.
Ireland.

Note: this address truly contains no numbers of any type. 

I look forward to hearing about your experiences with Cword! 
Remember, if you have found a bug please try to include the Cword log
file. 



Limitations of Cword
====================

The following is a list of the major limitations currently in Cword. 

1. Grid filler.

Before you get excited, the grid filler will only work on blocked
grids, and then probably only with a good sized word file set.  The
grid filler is one piece of functionality I have major plans for the
next release.  At the moment, It is functionally very limited and very
slow. 

2. American grid support. 

At a fairly late stage of development my attention was drawn to the
lack of American grid support I was providing.  This is true!  
Currently, I cannot optimally create American grids, fill them, or
even print them in the manner usually expected of such definitions. 

3. Clue generation integration.

During the clue generation phase, it is not possible to call any of the
other word/light utilities developed in Cword.  For example it should
be possible to access the Webster's dictionary server or anagram
generation during this phase.

4. Multi-word lights.

Cword currently does not support proper multi-word lights.  Cword
assumes all lights are single words.  It is not currently possible for 
Cword to understand multi-word lights obtained from the word files.

5. Static/Dynamic data structures.

Cword is not memory optimised.  This results in Cword unnecessarily
wasting huge globs of the memory.  The same is true of Cword's message
file processing.  Both these issues are probably preventing a proper
and complete port to MS-DOS. 

6. Full anagram generator. 

This is a piece of functionality that is potentially very useful but
Not yet included in Cword.  It has not been implemented yet for a few
reasons: 

* I did not want to make Cword any bigger without including more
necessary functionality first.

* Too many other people are working on this problem to start
re-inventing the wheel from scratch.

I am waiting for someone to come along and provide an API like
mechanism which I can then plug into Cword ;-).  Wordplay comes to
mind as a possible candidate, but I have not investigated this
possibility fully yet. 

7. Windows/X-Windows/Motif interface. 

I made a conscious decision early in development to go for full
portability of Cword, but without the extra complexity of Curses or
(X-)Windows. This has served me relatively well upto now.  However, I
feel that Cword is quite limited without some sort of graphical user
interface; crossword creating is such a visual skill. 

8. Port to MS-DOS/Windows platform.

I have made half-hearted attempts to port Cword to MS-DOS using both 
Visual C++ and Borland C++.  At one stage, it was possible to compile
and link Cword in either IDE, but in the past 12 months the
application has grown too large for the latter step to be successful. 

There are probably many reasons why I have not been able to port Cword
properly to MS-DOS/Windows.  The primary reason is the use of a large
static struct containing most Cword text messages (in messages.h).  I
have very little understanding about how memory management works in
MS-DOS and this is one result :-(.  I would be eternally grateful for
some expert help in this area? 

A Visual C++ .MAK file and Borland C++ .PRJ file are included in the
Cword distribution.  If anyone is interested in porting Cword to
MS-DOS, please feel free to contact me for more details. 



Future Plans for Cword
======================

The following is a list of proposed enhancements to Cword for the next
major release. 

1. Grid filler.

The functionality, as is, needs to be completely overhauled.  There is
much I need to do to make the filler more robust, faster, and most of
all, smarter.  I have read a few technical papers on the subject and
will try to implement their findings, together with my own heuristics
(which I have formulated over the past few years looking at the 
problem) into the next release.  Much of this work will centre around
how to most effectively read and store all the word files contents in
memory.  At the moment the word files are read from disk each time
they are required, so as to cut down on the amount of memory used by
the program!  Other work to improve the actual grid filling algorithm
is also urgently needed to improve the percentage of grids fully
filled. 

2. American grid support.

I have a lot of good ideas about how to improve the process of
creating, filling and printing American grids.  The creation
process of American grids can be quickened up substantially.  The
grid filling aspects of American grids are dealt with in point 1
above.  How American grids are outputted to text or postscript differ
slightly to that used for other grid types.  All these aspects will be
updated in the next release. 

3. Clue generation integration.

There are a lot of possibilities in this area which have occupied my
mind for a while now e.g. the integration of the anagramming
functionality and Webster's dictionary server access to the clue
generation phase. 

4. Multi-word lights. 

This will take a deal of work as Cword is based on the premise that
all lights are single worded.  The process how word files are read and
used will have to be updated to allow Cword understand and deal with
multi-word lights better. 

5. Flat file clue database.

At the moment it is possible to store single clues (not part of a
crossword definition) in the Rdb database back-end.  This feature is
of no use to people who have built Cword without database support.  I
hope to add some scheme where it will be possible to read and write
individual clues from flat text file(s).  Remember this functionality
will only be used during grid filling. 

6. Speed improvements in Cword.

I have done very little performance analysis on Cword V1.0.  I know
there are many algorithm improvements possible but will not commit to 
implementing them until post V1.0.

7. Upgrade DB functionality.

The database code works fine using DEC/Oracle Rdb, on both OpenVMS and
OSF/1, but has not been tested with any other rdb engines yet.  I need
to check that this code works with other database vendors!  I also
need to implement changes that will make the interface with the
backend database more flexible and user friendly. 

8. Port Cword to other platforms.

I would like to port Cword to operating systems other than those
mentioned earlier in the user guide.  Examples of such operating
systems include Linux, IRIX, etc.

9. Misc. enhancements.

* Add other word utilities.
* Add full anagram generation.
* Add extra analysis/checking of Barred and American grids.
* Add ability to dynamically toggle the symmetry of selected grids.
* Add ability to seed individual cells in grid.
* Add ability to reload a partially completed grid definition.
* Add user-defined light killing mechanism for grid filler.
* Add ability to re-direct output from Cword to file instead of screen.
* Improve print output to both TXT/PS formats.
