DEFINITION MODULE Help;
(*******************************************************************
Module Help (Version 1.0)
Copyright (c) 1991-2006 by Andreas Fischlin, Harald Bugmann and
ETH Zurich.
Purpose Implementation of a small help system that looks
like a HyperCard stack.
Remarks Supports only one single help window at a time.
Programming
o Design
Andreas Fischlin 23/07/1991
o Implementation
Andreas Fischlin 23/07/1991
Harald Bugmann 23/07/1991
ETH Zurich
Systems Ecology
CHN E 35.1
Universitaetstrasse 16
8092 Zurich
SWITZERLAND
URLs:
<mailto:RAMSES@env.ethz.ch>
<http://www.sysecol.ethz.ch>
<http://www.sysecol.ethz.ch/SimSoftware/RAMSES>
Last revision of definition: 24/01/1992 AF
*******************************************************************)
PROCEDURE ShowHelpWindow;
(* generate the help window and display the help text. The latter is
to be read from a help file, which is an ordinary text file.
The help file must be present and be written in the syntax
specified below. IMPORTANT NOTE: The name of the help file
must be set by means of procedure SetHelpFileName; otherwise
an error message will be displayed. *)
(*
The help file must be written using a word processor such as Microsoft
Word and stored in the Rich Text Format (RTF).
The help utility uses the module RTFScanner to read the help file.
For a description of RTF commands supported, see the file RTFScanner.DEF.
All text in the help window is written in font Geneva with size 9 points.
All items are placed in character cells. It is therefore sometimes not possible
to place items exactly as they were in Microsoft Word if margins or space before
have not been set properly; however, this most often does not matter.
The following formatting procedures are supported by the help mechanism:
************************************************************************
- Italic, Bold and Underline Style (in any combination)
- Space before paragraphs
- Left and right margins (but not first indents)
- Adjustment of paragraphs (left, right, centered)
- Side-by-side paragraphs
- forced return (Shift-Return in Word) within a paragraph
- optional hyphens
- all special characters are supported except for "{", "}", and "\"
- pictures may be pasted into the Microsoft Word help file
- HiddenText is used to read data from a resource file, i.e.
"s1003" plays the sound with ID 1003, and
"p7002" displays the picture with ID 7002 from the resource file
(the latter may be much faster for large pictures than if pictures are pasted
directly into the help file; this is especially important on slow machines)
- Page Break Before is used to start a new help topic; this must be specified
explicitly because automatic page breaks are not recorded in the RTF file!
- other RTF commands are ignored by RMS Help
Recommended formatting:
***********************
- Define Normal Style as: Geneva 9 point, Flush left, Line spacing -12 pt
- Format the document size as A4 paper with the following margins:
top 2.998 cm, bottom 17.707 cm, left 2.011 cm, right 2.081 cm.
This page size corresponds to one help page
- The topic list must be in two paragraphs formatted as side-by-side, and the
items must be separated by forced returns (Shift-Return)
Notes on the interpretation of some RTF symbols:
************************************************
HiddenTextSym:
--------------
Help assumes that all hidden text can be interpreted as a character describing
the resource type ("s" for sound and "p" for picture), followed by the resource ID.
The ID is used to load the resource from a resource file. Do not specifiy anything
as hidden text unless it describes a resource ID!
To play a sound several times, each "sXXXX" statement must be separated from the
other(s) by some non-hidden text, e.g. a blank.
PageBreakSym:
-------------
A new help topic in the Word Processor must be preceeded by a forced page break
(use the "Paragraph" command and choose "page break before" for Microsoft Word).
Any page break in the RTF file is interpreted as the beginning of a new help topic.
The \pagebb command must be followed by a number and - on the same line - by
the topic title. The number is used to determine which line of the "Topics" list
corresponds to the topic, and the title is used as title for the the help window.
The line must end with an end-of-paragraph symbol (\par in RTF), NOT with a
forced line break (\line in RTF, Shift-Return in Microsoft Word)
PictSym:
--------
Implementation restriction: The current implementation of the Help module does
not support pictures drawn by means of the Graph Editor that is part of the
Microsoft Word software (procedure DMPTFiles.LoadPicture crashes due to the format
of Microsoft Graph pictures).
Equations produced with the Equation Editor of Microsoft Word can be used if the
following restrictions are taken into account: The equation must be pasted e.g.
into a MacDraw II document, copied from there and only then pasted into the
Word document
SideBySideSym:
--------------
Implementation restriction: Each column of a side-by-side section may contain
ONLY ONE PARAGRAPH.
SpaceBeforeSym:
---------------
Since all items are placed in character cells, it is not possible to specifiy
Space Before at a higher resolution; the RTF contains Space Before with a
resolution of 1/20 points (!); the measures are rounded to one character cell.
*)
PROCEDURE SetHelpFileName (fn: ARRAY OF CHAR);
(* In case the help window is currently open and the new name is
different from the old, the help window is first closed and
then reopened using the new file name. A file name may contain
a path. *)
PROCEDURE SetResourceFileName( fn: ARRAY OF CHAR );
(* Set the file name of the resource file which contains picture
or sound resources to be displayed within the help file. *)
PROCEDURE SetInstallationErrHandler( errMsg: PROC );
(* In case that ShowHelpWindow encounters an error when attempting to
open and read the help file, a basic error message is
displayed. By default it shows the address of the authors of
the RAMSES software. If you wish to change this text,
overwrite it by installing the procedure errMsg. Its purpose
is to write some information on where or how to get help, if
the user can't get the help mechanism properly working. This
is likely to ocurr, if the help file becomes damaged, or is
not properly installed etc. You may find out how far the
initial error message has come, by calling at the begin
of errMsg DMWindIO.GetPos, and position your text relative
to this character cell. Note also that Help tries to
play back a sound with ID 1003 (in RAMSES this is "whoops"), to
notify the user about the error condition. *)
PROCEDURE SetDebugMode( debugOn: BOOLEAN );
(* Switches the internal debugging mode on or off. This mode may be
useful while writing help files. If the debug mode is on,
the user gets a more detailed information on the type of error
encountered. However, turn this mode off, once the help file
has been finalized, since interpreting these detailed error
messages requires some knowledge about the internal structure
of a help file. Normally the latter is rather confusing for an
ordinary user, hence the currently installed error handler
(see SetInstallationErrHandler) is shown if the debug mode
is turned off. By default debugOn = FALSE. *)
PROCEDURE ResetHelp;
(* Resets this modules to its initial default condition. *)
END Help.
RAMSES
Modules:
A-Z
Function
Layer
QuickRefs:
DM
AuxLib
AuxLibE
SciLib
EasyMW
MW
ISIS
RMSLib