\documentstyle{report}
\pagestyle{headings}
\parindent0cm
\parskip0.5ex plus0.2ex minus0.1ex
\textheight220mm
\textwidth145mm
\voffset-7mm
\sloppy
\raggedbottom
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{4}
\title{\Huge \bf Cross V5.1\\
             \bf Documentation}
\author{Jürgen Weinelt\\
        Zur Kanzel 1\\
        D-8783 Hammelburg\\
        Germany}
\date{May 20 1993}

\begin{document}
\maketitle
\begin{abstract}
  Cross V5.1 is a computer aided crossword construction program (I guess
  ``CACC'' might be a nice acronym for that :-). It should work with any
  Amiga configuration if you're using at least Kickstart~2.04 (37.175).
  Cross should work with all memory configurations, including 512~KB.
  However I recommend 1~MB of RAM or more.

  Currently Cross V5.1 supports four different languages: English, German,
  Italian and Esperanto. New translations can be added easily, because
  almost all the messages are collected in a single ASCII text file.
  I'm currently looking for additional translations.

  Cross V5.1 is Freeware. You may copy it freely as long as you are not
  making profits that way.

  Cross V5.1 is completely font sensitive and adapts to both the resoultion
  and color palette of your Workbench screen.
\end{abstract}

\tableofcontents

\chapter{Some legalese}
\section{Copyright}
Program and documentation are (C) Copyright 1991,92,93 by \\
\begin{quote}
  Jürgen Weinelt \\
  Zur Kanzel 1 \\
  D-8783 Hammelburg \\
  Germany
\end{quote}

Non-profit distribution is permitted. Any other distribution is a violation
of my copyright and will be prosecuted.

\section{Disclaimer}
Cross was carefully tested on several different Amiga configurations and
I'm currently not aware of any major bugs. You are however using this
software at your own risk; that is, if it breaks something, it's your
problem and NOT mine. I think this is a fair deal, because you
received this software for free.

\section{Bug reports}
If you find any bugs in this program, please contact me immediately. I will
try to fix problems as soon as possible. You can find my address in the copyright
notice above. If you have EMail access, you can also reach me as

\begin{verbatim}
   jow@sun.rz.uni-wuerzburg.de (preferred)
   jow@hcast.adsp.sub.org
   jow@hcast.franken.de
\end{verbatim}

I'm the proud owner of several different Amigas, including a brand new
A4000/040. I'm testing my programs with the latest OS beta versions and
I'm trying to avoid compatibility risks wherever I can. If you contact
me with a bug report, please be sure to include a detailed description
of your hardware and software configuration, as well as a detailed description
of ``your'' bug.

\subsection{Special rules for international mail}

German users are required to include return postage with their letters;
unfortunately this is almost impossible from outside Germany, because I
can't use foreign stamps, and trying to exchange small amounts of money
at a bank is quite expensive. Therefore I ask you to include a picture
postcard or a photograph of your home town with your first letter as a
substitute for the return postage. This is NOT a shareware fee or such.

\chapter{Program documentation}
\section{Starting Cross}
There are two possible command lines for starting Cross from the shell:

\begin{verbatim}
  Cross
\end{verbatim}

This is the usual way of starting cross. Use it whenever you just want to
work with the program normally.

\begin{verbatim}
  Cross -d
\end{verbatim}

If you start Cross with this command line, you enter a special message data
debug mode; messages will be displayed together with the corresponding message
number. This is only needed if you've created a new translation and you want
to debug obscure problems with it. More documentation on this will follow later.

You need to add a ``ASSIGN Cross: somewhere'' before starting the program,
where ``somewhere'' is the place where you installed the Cross main
directory. Cross needs this to find its additional files:

\begin{tabular}{|l|l|}
  \hline
  File or directory     & Meaning                                \\
  \hline
  \hline
  DATA                  & data directory                         \\
  \hline
  DATA/Cross.prefs      & contains user preferences              \\
  \hline
  DATA/msgtxt.data      & contains the mulitlingual messages     \\
  \hline
  DATA/words\_eng.crw   & German word data file                  \\
  DATA/words\_ger.crw   & English word data file                 \\
  DATA/words\_ita.crw   & Italian word data file                 \\
  DATA/words\_eto.crw   & Esperanto word data file               \\
  \hline
  DATA/ (\dots{}) .crd  & crossword data files                   \\
  \hline
\end{tabular}
\vspace{2ex}

\section{The menus}
Most of the menus are self-explanatory. Here's a short description
of their meaning:

\subsection{The Project menu}
This is where you find all the input and output operations.

\subsubsection{Project: New crossword}
After a safety check the old crossword puzzle is discarded and a
new (blank) one is prepared.

\subsubsection{Project: Load crossword}
A crossword data file will be read from disk.

The suggested file name extension for crossword data files is `.crd'.

The crossword that you're currently editing will be discarded
without an additional warning.

\subsubsection{Project: Load word data file}
A different word data file will be loaded.

The suggested file name extension for word data files is `.crw'.

\subsubsection{Project: save crossword}
The crossword that you're currently working on will be saved.

The suggested file name extension for crossword data files is `.crd'.

\subsubsection{Project: Save settings}\label{saveprefs}
The current language and the current crossword size will be saved to
``Cross:data/Cross.prefs''. Cross reads this file during its startup
and initializes according to what it finds there.

\subsubsection{Project: Printer}
All the printer functions are located in this submenu.

\subsubsection{Projekt: Printer: Print crossword (plain)}
I seriously hope you will never have to resort to this function; it does work
on almost any printer except for some really very exotic models, but what you
get is definitely not what one might call ``nice'' or ``good looking''.

\subsubsection{Project: Printer: Print crossword (\LaTeX{})}
If you're a \LaTeX{} user, you can use this function to write the current crossword
as a \LaTeX{} source file. You may have to experiment with the paper width and
paper height settings of your \LaTeX{} environment. Try changing
\verb+\oddsidemargin+, \verb+\textwidth+, \verb+\hoffset+ and \verb+\voffset+.
Change the \verb+\unitlength+ to resize the crossword globally.

\subsubsection{Project: Printer: Print crossword (pretty)} \label{genfancy}
This is the first choice for printing crosswords; it should work with every
graphics printer, if the printer was configured correctly through the printer
preferences. This mode requires relatively much RAM, there may be problems
with 512~KB Amigas.

\subsubsection{Project: Printer: Print crossword (pretty/numbers)} \label{genfancynum}
This function is identical to the previous one, but it will also insert a
clue number into the crossword grid wherever a word starts. If you create
a clue list (you'll have to do this manually, there's no support for that in
Cross), you get another popular type of crossword.

You will probably need a printer resolution of 300~DPI or better for this
feature. At lower resolutions the clue numbers may look ugly.

\subsubsection{Project: Printer: Print crossword solution}
Since there's no graphics to be printed here, this function is the same for
every printer.

\subsubsection{Project: About}
Cross displays a requester with its version number and copyright notice.
You can also find my postal and EMail address there.

\subsubsection{Project: Quit}
After a safety requester the program ends.

\subsection{The Edit menu}
Here you'll find all the editing functions you need to create crosswords.

\subsubsection{Edit: Auto search mode}
While the auto search mode is active, Cross tries to find words that
fit into the crossword. Two conditions must be met:

\begin{itemize}
  \item a word data file must be present (that is, in memory)
  \item at least one word must have been placed as a ``seed word'' from
        which the rest of the crossword can grow.
\end{itemize}

While the auto search is running, a progress requester with two progress bars
is displayed. The first bar corresponds to the ``limit'' variable, the second
one shows the progress of the current search attempt. The auto search mode is
finished by clicking on the ``Stop'' gadget, or when no more words can be placed.

\subsubsection{Edit: Place word manually} \label{epm}
Enter the word into the string requester and press return (or click on the
``Confirm'' gadget). Then select a grid position by placing your mouse pointer
over the desired position and clicking the left mouse button. A second requester may
appear if it's  not clear whether to place the word horizontally or vertically.

\subsubsection{Edit: Remove word manually}
Select the word to be removed by moving the mouse pointer over any of its
letters and then clicking the left mouse button. A second requester may then appear
if it's not clear which word to remove.

If you have selected this function by accident, you may cancel it by pointing at
an empty grid position and then clicking the left mouse button.

This menu item is selectable only when at least one word has been placed.

\it{}
Please be careful when using this function because there are some
nasty problems involved with it. Look at the following example:

\begin{verbatim}
     E
     V
     E
     N
   OUTDOOR
      U
      B
\end{verbatim}

If you delete the word OUTDOOR, you get the following situation:

\begin{verbatim}
       E
       V
       E
       N
       TD
        U
        B
\end{verbatim}

If you look closely now, you will notice that there's suddenly a new word TD
that has not been placed explicitly. Nasty, isn't it?
\rm{}

\subsubsection{Edit: Reset length limit}
Cross uses the limit variable to make sure that long words are placed
before Cross resorts to short words. Words must have at least the length
stated by ``limit'' or they will not be placed. ``limit'' is decremented
automagically when no more words can be placed. Use this function to
reset ``limit'' to any even value between 0 and 18.

\subsubsection{Edit: Set crossword size}
A requester asks for the width and height of your crossword. Please note
that width and height must be odd numbers. This function is only available
when no words have been placed.

\subsubsection{Edit: Put seed words}
Use this function to place the four seed words from which the rest of
your crossword will grow. You might also decide to place those seeds
manually instead, in this case use \ref{epm}~``Edit: Place words manually''.

This function is not available if words have already been placed.

\subsection{The Language menu}
For each language there is one menu item in this menu. Currently you
can choose from English, German, Italian and Esperanto.
Whenever you select a language from this menu, Cross reloads the corresponding
message texts and redraws its screen.

You can make a language selection permanent by selecting \ref{saveprefs}~``Project:
Save settings''. It will be then loaded as default whenever you start Cross.

\chapter{File documentation}
\section{The message data file}
This file contains virtually every text used by Cross, at the moment there
are messages in English, German, Italian and Esperanto. Other languages can be
added easily (up to 9 languages).

Each entry in the message data file uses exactly one line.

\subsection{Structure of the message data file}
The first line of the message data file contains one single digit; this is
the number of languages currently available. This is followed by the name of
each language (currently ENGLISH, DEUTSCH, ITALIAN and ESPERANTO).\footnote{
                 Have you added another language to the message data file?
                 Please send me a copy of your message data file on disk, I will
                 include it with the next release of Cross.}

The following entries are present once for each language, too. These are the
program messages.

\subsection{Additional informations}
If you want to add another language to the message data file, please make
sure that your translation has approximately the same size as the original
message, because some of them appear in requesters, menus or gadgets.

Each message must start with a three digit number. This number must be
itentical to the actual number of the message (actual maeans, what you'd
get by counting them). Just take a look at the message data file, this is
easier than it sounds.

The only exception to this rule is the message number ``999'' which signals
the ``end of file''.

\subsection{Debug mode}
If you encounter any problems after adding another language, just start
Cross with the message debug mode active (add parameter ``-d'' from
the shell). This causes the message numbers to be displayed along with the
messages. It will hopefully help you locate the problem.

\section{Word data files}
If you want to create your own word data files, please note:

\begin{enumerate}
  \item You may use every character you want to, including even national characters,
        blanks, dashes, etc. It's up to you to make sure that the words
        actually make sense
  \item The word length should always be odd,that is, 3,5,7, \dots{}, 25 (except for
        two letter words). This limitation is needed to improved the structure
        of the crossword. You're alolowed to use words with even length, but this
        will probably cause larger gaps in the crossword grid.
  \item Word length must be at least 2 characters, and no more than 25 characters.
  \item The word data file must not contain empty lines.
  \item The last entry may or may not be `***END***', without the quotation marks,
        of course.  The ``***END***'' is not needed, but will be ignored if present.
\end{enumerate}

\section{The PreProcessor}
Yes, you're right. There is an easier way of creating word data files\dots
Just run any standard ASCII text file through the ``PreProcessor'', which
should also be somewhere in the ``Cross'' drawer. PreProcessor will break it
down into single words and will remove anything illegal (PreProcessor still
uses the strict Version 3 rules for words). You'll have to use
your favourite editor though to delete all those words you don't want to use.
There may also be some ``crippled'' words that didn't survive the PreProcessor.

\subsection{Usage of the PreProcessor}
There are no command line parameters; file selection is done with file
requesters.

\subsection{Additional note}
The PreProcessor uses a recursive algorithm (builds a binary tree
to sort the words); please make sure there's enough stack space
available. You can increase the stack space with a CLI command
called ``STACK''. PreProcessor automatically allocates 50000 bytes
of stack space; if you need more than that, use the STACK command.
PreProcessor is very greedy anyway\dots{} there may be problems
with it on 512K Amigas if you try to convert large ASCII
text files.

\subsection{Large word data files}
Just a warning: if your word data file is very large, the creation of the
crossword will be slowed down considerably. In order to avoid this effect,
you might use several small word data files, loading the next when the
current file is used up.

\begin{tabular}{|l|c|}
  \hline
  File              & Word length \\
  \hline
  \hline
  words\_ger05.crw  & 25--17 \\
  words\_ger06.crw  & 15--9 \\
  words\_ger07.crw  &  7--5 \\
  words\_ger08.crw  &  3--2 \\
  \hline
\end{tabular}

\chapter{Miscellaneous}
\section{Known problems/bugs of Cross}
Using a very large font (about 40 points ore more) may cause error messages
or even fatal errors. I know how to fix this, but it is a major change and would
take quite some time to fix. I will eventually do it, but it was too much work
for this release. As a workaround, select a smaller font size from the
Workbench font preferences.

I know of no other bugs at the moment.

If you encounter any bugs, please send me a detailed description of the bug and
your hard- and software configuration.

\section{Future improvements and plans}
\begin{itemize}
  \item several patterns for setting the ``seed words''
  \item crosswords with custom layouts instead of rectangles
  \item AREXX port
  \item Support for the new Workbench~2.1 locale routines
\end{itemize}
\end{document}
