*********************************************************************
*
*                    MINIHELP VERSION 1.1b3
*                            11/7/96
*                         Charlie Kempson
*                    charlie@siren.demon.co.uk
*                       kempsonc@logica.com
*
*    HOME PAGE:  http://public.logica.com/~kempsonc/mh_index.htm
*
*********************************************************************

INTRODUCTION
------------

This is release 1.1 b3 of the integrated Help environment for
all tcl/Tk platforms.  It should run unmodified on all platforms.

This release of MiniHelp is SGML compliant.  That is to say, if
you create a help file and run it through one of the many public
domain packages for parsing and checking SGML, it will pass
through correctly.  Why, you say?  What's the need for SGML 
compliance?

(1) It gives you a means to verify your help text, for example
    to ensure that there are no dangling hyperlinks or 
    unbalanced tags.
(2) It makes it much simpler to write conversion tools, to 
    convert MiniHelp files into, for example Latex or HTML.
(3) It's a standard, so you are not relying on a proprietary
    language definition.  The MiniHelp DTD fully defines the
    language and the allowable constructs.  This will not
    change (at least not in a way which is not backwards
    compatible).

PACKAGING
---------

The MiniHelp package comprises a number of files.  The basic runtime
elements are:

global.tcl - Contains useful globals
dialog.tcl - Contains convenience dialog functions
utils.tcl - Contains convenience routines
help.tcl - Contains hooks for developers
parser.tcl - The minihelp parser
minihelp_filter.tcl - The MiniHelp language filter

In addition the editing facilities are based around MiniHelp.tcl:

MiniHelp.tcl - The editor
html_filter.tcl - Not yet complete
minihelp.dtd - The MiniHelp Document Type Definition

Also included are two example help files:

test1.mhp - Another shorter help file
test2.mhp - The TkNet help

These may be viewed and edited using both the editor and
the standalone run-time viewer, Viewer.tcl.

INSTALLING MINIHELP
-------------------

It doesn't really matter where you place the minihelp
files.  However all the scripts will need to live in the
same directory.

RUNNING MINIHELP
----------------

(a) The Viewer -
    
To run the viewer, simply type Viewer.tcl (ensure the file
is executable).  A file selection dialog will be popped up 
and you can select the help file to display (try test1.help
or test2.help).  Alternatively provide the help filename
on the command line: 'Viewer.tcl test1.help'.

(b) The Editor -

Run up as MiniHelp.tcl (again ensure thatthe file is
executable).  Select a file or cancel the file selection
dialog, then start creating pages.  Start simple until
you get the hang of how pages hang togather within the
document structure.  Then save it to a file, and view the
resultant file using an editor to get an idea of the 
structure.

You can edit multiple files at the same time, and copy
between them.  You can import from the clipboard, from file
or from an HTML file (only basic tags are supported - 
consider this incomplete).

INVOKING MINIHELP FROM YOUR APPLICATION
---------------------------------------

Use Viewer.tcl as a template.  Source the necessary files:

source $dir/global.tcl
source $dir/dialog.tcl
source $dir/utils.tcl
source $dir/help.tcl
source $dir/parser.tcl
source $dir/minihelp_filter.tcl

Then create a dummy text widget (needed for the parsing) - you
don't need to pack it.  Load the help file into memory using
the routine MH_ReadSGMLFile.  Once this has been done you can
safely destroy that text widget.

Now whenever you wish to invoke help, place a call to MH_MiniHelp
in your code, providing the page name (not title!) as an argument.
Voila!

CLOSING COMMENTS
----------------

Minihelp is beta software.  There are currently many bugs and
unimplemented features.  The software should however be usable, 
and the run-time code is pretty stable.

If you find bugs or features that need changes, please feel
free to modify the sources and to provide patches to improve 
MiniHelp.  

---
Charlie Kempson
charlie@siren.demon.co.uk
