

Introduction
============


Word Hound is an application which provides the Risc-OS user with quick and
easy access to dictionary definitions and thesaurus entries. It comes with
two data files :

    Dictionary    With over 30,000 entries.

    Thesaurus     With over 33,000 keywords (over 60,000 indexes in total, and
                  almost 100,000 words and phrases in total).

Word Hound allows the user to add their own data files, and even edit the
supplied data files to contain new definitions or thesaurus entries. Word
Hound has been designed to allow communication between other applications,
including a special hotlink to Impression II (by Computer Concepts) whereby
words can be passed easily between the two applications.

Once you have installed Word Hound (instructions on how to do this should
have come with it) it is ready to use. To run simply double click on the
application, and it will install itself on your iconbar.

Clicking 'menu' over it's iconbar icon will bring up Word Hounds menu, which
contains 5 options (the usual Info and Quit options, plus a save setup file
sub-window, colours sub-menu and an entry marked 'Search'). 

Selecting 'Search' from the main menu, or simply clicking 'Select' over the
iconbar icon will bring up the 'Enter' window.


The 'Enter' Window
------------------
 
The 'Enter' window contains one writable icon, and three menu icons. The
writable icon (marked 'Find :') is where you can enter the word you wish to
search for. The three menu icons will make Word Hound take what ever word is
in the writable icon and perform one of three searches :

Normal 'Search' : 

This search, which is also started by simply pressing RETURN after entering
the word in the writable icon, will make Word Hound search all the available
index files for the word in the writable icon. When all the entries within
the index files have been located, they are displayed in the 'Selection'
window (see below).


'Wild Card' Search :

With this search you can use the two wild cards '#' and '*' to mean 'any
character' and 'any number of characters'. Word Hound will search all index
files for entries that match the given format, and will produce a list (in
the 'Display' window) of all the entries that match. Thus entering 'j#k*'
into the writable icon will produce the following output :


     Dictionary
 
     joke joker jukebox
 
     Thesaurus
 
     jakes joke joker joking


It is advised to fill in as much detail for the word you require as you can,
as some searches can produce quite a bit of output. In fact (because of a
minimum two character requirement for the search string) Word Hound will not
allow a search for '*'. If the search sting is such that the first letter is
not defined (the search string starts with either a star or a hash) Word
Hound will bring up the  hour glass during the search.

The 'Wild Card' search can search for entries containing all valid
characters within Word Hound, this includes foreign characters, apostrophe,
etc. To enter a start or hash character as themselves in the search string
you need to preceded that character with a back-slash character (ie. '\*' or
'\#'), and to enter a back-slash  you need to type two back-slashes (ie.
'\\').

'Sounds Like' Search : 

This search takes the word in the writable icon, and searches the index
files for all words that might sound like that word. All located words are
then listed in the 'Display' window (see below). This search can only cope
with letters within the normal alphabet. It can not cope with foreign
characters, punctuation, etc.

The 'Close' option, when selected, makes Word Hound close it's windows once
a word has been passed to another application (see below).

When you bring up the 'Enter' window by clicking 'Select' over it's iconbar
icon, Word Hound will remember where the caret currently is, and will return
it there every time you perform a search.


The 'Selection' window
----------------------

This window is used after a normal search to display a list of the entries
which contain the word searched for. This allows the user to then select
which entries they wish to look at in full.

To explain the 'Selection' window it is best to give an example. So if you
were to type "bellowing" into the writable icon and perform a normal search,
the 'Selection' window will contain :

   Dictionary   bellow       : bellow
   Thesaurus    bellow       : 404. Loudness.
   Thesaurus    bellow       : 411. Cry.
   Thesaurus    bellow       : 412. Ululation.

The first column tells you which data file the entry is in, ie. Dictionary
or Thesaurus. The next column tells you that actual word it located in the
index (see below), and the third column tells you about that entry.

To display any of the entries listed, simply move the mouse pointer over
that entry in the list and click 'Select' once. This will bring up the
selected entry in the 'Display' window. 

As you can see, although Word Hound found no entries for "bellowing" it did
find some under "bellow". This is because Word Hound performs a 'fuzzy'
search as it's normal search. This is explained in more detail later on in
this document.


The 'Display' window
--------------------

The 'Display' window is used for displaying entries from data files, as well
as the results from a 'Wild Card' or 'Sounds Like' search. When used for
entries in the data files, all occurrences of the word used in the search
are highlighted so that you can locate them easily. This is particularly
useful for thesaurus entries as these tend to be quite large, and contain
much that is irrelevant to your search. Relevant words tend to be located
around the word you searched for. The mouse buttons (and shift key) perform
the following functions when the mouse pointer is over this window :

Select        Word under pointer is passed to the application currently
              holding the caret. The word will selected will also be 
              highlighted.

Shift Select  Phrase, that the word under the pointer is in, is passed to
              the holder of the caret.

Adjust        Word under the pointer is looked up in all dictionary indexes
              (not thesaurus indexes) and the first located entry is shown 
              in the 'Quick Definition' window.

Shift Adjust  Word under the pointer is placed in the writable icon in the
              'Enter' window, and a normal search is performed on that word.

Menu          This will bring up a 'Save as' box which will allow you to 
              either save the contents of the window to a file, or drag the 
              contents to another application. This is useful if you want 
              to insert a definition into some text. Note, however, that 
              the complete contents (minus colours) will be saved (passed on) 
              and so you will probably need to edit out some of the text.


The 'Quick Definition' window
-----------------------------

This window is used a a second display window, and behaves just like the
display window. The only difference is that it will only be used to show
dictionary entries, and only used when you click 'Adjust' over a word in
either the 'Display' window, or the 'Quick Definition' window itself.

When you call up a quick definition, all the index files of dictionary data
files are searched (in order) to locate that word. If that word can't be
located, then a 'fuzzy' search will be performed on that word (see the
'Selection' window section for information about the fuzzy search).


The Word Hound 'Fuzzy' Search
-----------------------------

When Word Hound searches for a word, either by the normal search or when you
request a quick definition, it first builds up a list of variants on that
word. These variants are designed to compensate for different parts of
speech, and also to compensate between British and American spellings.

This is very useful, particularly when using the Impression hotlink (see
section 2) as it will increase the number of times Word Hound can locate the
word you are looking for without you having to change the word to, say, it's
singular version.

To give you an idea of what the fuzzy search can do, here is a list of
initial words, and some (not all) the fuzzy versions that will also be
searched for :

   Initial word     Fuzzy Versions

   colourise        colourize, colour, color, colourization
   fully            full
   fastest          fast
   sceptre          scepter
   defensive        defense, defence

This fuzzy search has nothing to do with the 'Sounds Like' search. It should
also be noted that this search can produce some strange results (because of
it's general nature). Thus searching for 'tree' the dictionary entries for
'tore' and 'treat' will also be listed. This should, however, not be a major
inconvenience as the correct word will always be listed if available.


When Word Hound can't locate a word, not even with the fuzzy search
-------------------------------------------------------------------

When Word Hound can't locate a word, it brings up the window you are
expecting (ie. either the 'Selection' or the 'Quick definition' window) but
simply places a message in that window telling you that it can't locate the
word you are looking for.


Notes
-----

When Word Hound passes words to the application holding the caret it does
not try to convert the words. For example, if you search for "tints" and
then look under the thesaurus entry containing the word "tint" (singular)
and then select the word "color" (American) to pass to your other
application, Word Hound will NOT compensate for either your selection being
singular (it does not add an extra 's') nor does is de-Americanise the word
to colour. The reason that this does not happen is that there is no way Word
Hound can know for sure whether the word can simply take an 's' ending, nor
can it know that 'color' is American. The reason that it can work the other
way during a search is that it searches for a whole list of possible
versions of a word (eg. colours, colour, color) and thus it does not matter
if some are not actually correct words).

Note also that although Word Hound only needs a 160k wimpslot to start up,
when it has to display a 'Selection' window, or a 'Display' window or a
'Quick Display' window it needs to grab extra memory. Thus it is advisable
to make sure that there is (at least) about 32k extra memory free for Word
Hound to grab when it needs to. Word Hound only grabs this extra memory when
it needs to, and also returns it as soon as it can (when the windows are
closed).

When you use 'Shift Select' to pass a phrase to another application, Word
Hound there are two things to note. First the pointer must be over a word in
that phrase (not a space character). Second, if the phrase is split over two
lines, then only that part which is on the line you click over will be
passed on. This means that if a phrase is split you might need to pass each
part separately.


Limiting the search
-------------------

It is possible to limit searches to only specific data files. If you bring
up the Word Hound main menu, bringing up the 'Search' submenu will list all
data files currently known by Word Hound (ie. listed in your startup file
(see below for details)). Any files currently not available (eg. due to
missing files) are greyed out, and all currently selected data files are
ticked. Selecting any of the (non greyed out) files will toggle whether or
not it will be used in searches.

When you start up Word Hound all available data files (data suites) are
'selected' unless their entry within the startup file starts with a '!'.
Thus, for example, the following portion of a  startup file :

    dicts: 3
    dict,1,Dictionary
    roget,0,Thesaurus
    !jargon,2,Jargon

will cause Word Hound to start up with 3 data suites, but only the
dictionary and thesaurus files will be selected, ie. searched, until the
user makes further selections/deselections from in the 'Search' sub-menu.


The Word Hound 'Startup' file
-----------------------------

When Word Hound starts up it looks for a special file, pointed to be the
system variable WordHound$Init. This file should contain all your
preferences for Word Hound, including window colours, hot-link-keys for the
Impression II hot-link and a list of all available data files.

Startup file commands have the following syntax :     COMMAND : PARAMETER(S)

and currently include :

Background : <num>  - Sets background colour for 'Selection', 'Display' and
                      'Quick Definition' windows.

Foreground : <num>  - Sets foreground colour for 'Selection', 'Display' and
                      'Quick Definition' windows.

Dictionary : <num>  - Sets colour for displaying dictionary names.

Word : <num>        - Sets the colour for highlighting the word searched for.

Select : <num>      - Sets the colour for highlighting selected text.

Hit-Search : <num>  - Sets hot-link key for searching for word selected in
                      Impression II.

Hit-Enter : <num>   - Sets hot-link key for passing word selected in 
                      Impression II to 'Enter' window.

Suits : <num>       - States how many data files (suites) are available. This
                      command line MUST be followed by the given number of 
                      data suite definition lines. These lines are described 
                      in section 4.

Any line starting with a '|' is taken as a comment, and is ignored. All
commands are case insensitive, and space characters are ignored if they
appear before, or after, commands.

The default startup file contains the following :

Hot-Search: 477
Hot-Enter:  509
Background: 5
Foreground: 0
Dictionary: 15
Word:       9
Select:     10
Suits:      2
dict,1,Dictionary
roget,0,Thesaurus

The 'Status' entry in the main menu leads to a standard 'save-as' window.
Using this window you can get Word Hound to create you a setup file, which
will contain all the options with their current settings.

With 'Hot-search' and 'Hot-enter' you can, instead of giving a number, give
a textual version of the key press. The format of this string should be a
list of the keys to be pressed separated by spaces. Valid entries are :

insert copyprintshiftctrltab

as well as 'ctrl-X' (where X is a key, eg. ctrl-a), and 'f0' to f12'.

So, for example, the default keys can be set by the following commands :

Hot-Search: shift insert
Hot-Enter:  ctrl shift insert

Note that when you get Word Hound to save a startup file for you (using the
menu option) it will only use values for these two commands, it will not
create the textual format.

