DESIGN.TXT contains an outline of the design and implementation of
Cword, and is specifically for people who want to better understand how
Cword is structured and works. 

Module Configuration/Header Files
---------------------------------

Cword is made up of at least 25 distinct modules of code.   At least
23 of these modules will be used to build Cword on any particular 
platform.  Two modules will not be used depending upon what operating
system Cword is being built on (Only one of the OpenVMS, generic UNIX
or MS-DOS specific modules will be used). 

Each source code file has its own header file, which is included by any
other module using functions defined in that source code module.  OS.H
is used as a multiplexer to OS dependent code defined in the OpenVMS,
generic UNIX or MS-DOS modules. 

The interface between the modules is as clean as possible.  Any
function in the header file of the module can be called from any other
module.  All functions defined have either explicit extern (PUBLIC) or
static (PRIVATE) scope. 

Portability
-----------

Cword should compile on any ANSI C compiler environment.  Whether
Cword will link depends on the local machine configuration (see
DOSREAD.ME).  Cword uses ANSI C prototypes and some other non-K&R
constructs e.g. const, so it will not compile on a pure K&R compiler.
No C++ only constructs have been used in Cword. 

I have used lint and PC-lint quite a bit as I was developing, so the
code should be fairly clear of problems (give or take the rare
doubtful cast from long to int or double to float). 

Global/static Variables
-----------------------

The use of global and module static variables has been kept to a
minimum, as per good coding practice.  This does not mean that they are
not used, it means that they are used - in what I hope - is a
controlled manner. 

There are two main global/static data structures used in Cword:

1. cword_messages_l_msgs (defined in messages.h)
2. cword_g_defaults_record (defined in main.c)

cword_messages_l_msgs is a large array of character strings containing
Cword text messages.  This struct can only be accessed by functions
defined in MESSAGES.C. 

cword_g_defaults_record stores configuration data used to drive Cword.
This configuration data is obtained from CWORD.INI (or similar) and
all members of this structure should be accessible from any place in
the application. 

Module static and function static variables are to be found in other
modules, but they are well patrolled and take up as little memory as
necessary. 

Coding Standards
----------------

I follow my own internal group's C coding standard as much as
possible.  This standard is particularly useful when naming functions
in a standard way and helps define the most effective indentation
style.  This indentation style may not be seen in its best light
because it does not always travel well between operating systems.  
(The problem specifically refers to have tabs are translated from 
system to system.)

The code standard also covers how global/static variables and macros
are defined.  I also use some standard notation (Hungarian) when
defining automatic variables, with varying success though.  This
success is a function of the improvement in my coding style over the 3
years I have been working on the project. 

Limitations
-----------

There are a few major limitations in the overall design of Cword that
have stopped Cword being porting to other systems, in particular to
MS-DOS/Windows. 

They are: 

1. Automatic allocation of large structs
2. Messages array 

1. Coming from a mainframe environment, where the stack and heap are
almost infinite in size, automatically allocating large data structs
did not cost much.  This is the premise I used when I started work on
Cword.  Throughout the code I use one or two large structs frequently
namely: CROSSWORD_RECORD or GRID_RECORD.  Both can be largely
redundant depending on the grid/crossword being worked.  It would
be most optimal if I were to dynamically allocate memory for my
grid/crosswords than to automatically allocate the maximum possible
space and then not use most of it. 

2. The messages array has grown to over 30K bytes in size and is
probably the main reason why linking does not work any more on MS-DOS
(in either Borland or Visual C++).  I will have to do something to
break this struct up to allow the MS-DOS link to work (assuming that
this is the cause of the link problems in the first place). 

Test Harness Development
------------------------

During Cword development, I used test harnesses a lot to test isolated
pieces of functionality.  As I centralised all code under one UI, I
stopped using them as much.  Most older Cword modules have a section
at the end of the source modules which contains a main () function and
some commands.  These are the remnants of this activity.  Because the
application has gotten so complex, it is unlikely that a novice user
will find any of these test harnesses useful. 

Conditional Compilation
-----------------------

I have tried to keep this complex mechanism to an absolute minimum. 
It can be the cause of untold development confusion when it is over
used or badly implemented.  In Cword, I use it only twice: to delimit
Rdb specific code and Webster specific code. 

Other Symbols Used in Code
--------------------------

The symbol "##" is used quite a lot when outputting information to the
user.  It is used simply as a note that the text outputted is not yet
a proper part of the messages.h struct containing most Cword text
messages. 

The symbol "?????" is used in the Cword code to mark an area when a
major improvement is immediately needed or where a serious bug has
been identified!  Usually a pair of these symbols is seen 
encapsulating some text describing the improvement/bug.

The symbol "??" (quite common) is used in the Cword code to identify
where a minor improvement is suggested or a minor bug been uncovered. 
Usually a pair of these symbols is seen encapsulating some text
describing the improvement/bug. 
