A Programmers Manual for the I-Manual System
--------------------------------------------
This document is intended for programmers to read who
are interested in how I-Manual works, and how they can
include I-Manual's into their own programs.

Any programmer is welcome to use I-Manual in their own
software if they so desire - however, if you are going
to use it in a commercial program we would appreciate
you contacting us so that we can make sure you have the
latest version.

How it works
------------
The principle behind how an I-Manual works is very
simple:  clicking on any word or phrase on a manual
page makes the I-Manual go away and look for a new
related page.

Constructing your own I-Manual is relatively easy: an
I-Manual is made up of page files and a few
accompanying database files.

The 'Dirs' file
---------------
I-Manual knows where to look for manual pages through
the use of a file called 'Dirs', which is hidden inside
I-Manual.  This is a plain text file containing
information as to where I-Manual should look for manual
pages, and usually contains the following lines:

   <I-Manual$Dir>.Pages
   <I-Manual$Dir>.I-Man-Docs

I-Manual searches for manual pages down that list -
therefore the first place it will look is inside
'Pages', and then inside 'I-Man-Docs'.

Words and Phrases
-----------------
As mentioned before, I-Manual links together manual
pages by way of certain words and phrases.  The pages
themselves are all seperate files hidden inside one of
the directories pointed to by the 'Dirs' file.

When a user clicks on an I-Manual page, the controlling
manual program then looks for a new page.  Firstly, it
consults a list it has compiled to see if the user has
clicked on a phrase it knows.  I-Manual learns which
phrases to look for through reading all files called
'--Aliases' it can find inside manual page directories.

An '--Aliases' file is of the following format:

   Phrase text  >  FileName
   ...etc.

The file-name in question should not include the path. 
The phrase can also be of any length - from a single
word (useful to cater for long words) to a whole
sentence.

If I-Manual finds that you haven't clicked inside a
phrase it knows about, it will instead go and look for
a page for the word you've clicked on.

If a page is found, then I-Manual will display it for
you, and it's title will contain either the word or the
phrase you clicked on as a reference.

Running I-Manual
----------------
I-Manual supports three different command-line options:

  -file  <filename>   runs up I-Manual and loads the
                      file <filename>
  -page  <pagename>   runs up I-Manual which then looks
                      for page <pagename>
  -title <titlename>  runs up I-Manual which then uses
                      <titlename> each page's titlebar

Any of the above options can be ommitted - in fact the
-file option probably would be very rarely used.  If
options are not passed then I-Manual reverts to default
values which are like so:

    <filename>  becomes a name worked out from...
    <pagename>  reverts to 'I-Manual'.  Finally,
   <titlename>  becomes 'On-line'.

For example, it is suggested that you should have a
!Help file (of the Obey file type) that reads something
like:

  Run <Obey$Dir>.!I-Manual -page "Index" -title "App"

This would of run up an I-Manual hidden inside that
applications directory which would load in the page
"Index". It's title bar would read 'App Manual: Index'.

Things to remember
------------------
I-Manual page names are restricted to 10 characters in
length (as this is a filing system restriction). 
Therefore I-Manual truncates words you may have clicked
on to become 10 characters long.

If you need more manual pages that a directory will
allow you to have then edit the 'Dirs' file.

The 'Dirs' file doesn't have to point inside the manual
application.  You can point to directories anywhere
from that file - if the directories are not found they
will simply be ignored.

While constructing --Aliases files, beware!
Take this example where you have two different aliases:

Locked Entries > Locked
Unlocked Entries > Unlock

If you were to click on the phrase 'Unlocked Entries'
in such a manual, I-Manual may well go away and display
the page for 'Locked Entries' instead, as this would be
the first matching alias it finds...  Therefore, if an
alias is a sub-string of another alias, make sure the
smaller entry is positioned last.

This manual itself is an example of I-Manual - don't
be affraid to look at how it's constructed.  Please
note that your pages don't have to be as long as this! 
This is intentionally long so that the aliases used by
I-Manual shouldn't clash with any you may wish to use.

If you use I-Manual, remember to keep I-Manual's own
documentation intact (ie. don't delete anything from
the 'I-Man-Docs' directory).

I-Manual ignores all of the following characters when
it goes away to look for a new manual page:
 $:%.,:;'`()<>[]*#^{}/\!?+-="
Therefore, the use of these characters should be
avoided inside file-names for manual pages.  Obviously,
some of these characters are not allowed in file-names
anyway, so that shouldn't be too much hassle, and the
rest above are included so that I-Manual will ignore
punctuation when looking for a manual page.  Otherwise,
for example, clicking on a word at the end of a
sentence wouldn't work.  However, the inclusion of
these characters inside aliases is permitted.

Further Info
------------
I-Manual was developed by DreamSoft in association with
Data Store Software.  If you should have any further
queries about this or any other Data Store program,
then please feel free to write to us at:

   The Data Store, 6 Chatterton Road, Bromley, Kent

      DreamSoft and Data Store Software 1991
