ARM Club 3/TheARMClub_PDCD3.iso/hensa/help/a285_1/!ReadMe

Text File | 1993-06-02 | 11KB | 217 lines

Application Help Program
Documentation for version 1.00

(C) Tony Patterson, 1993

THE HELP PROGRAM IS FREEWARE. IT CAN BE FREELY DISTRIBUTED AS LONG AS THE
!APPHELP DIRECTORY AND ALL THE FILES IN IT, AND NO OTHERS ARE INCLUDED.
FUTURE VERSIONS CAN BE DISTRIBUTED AS PART OF ANY VIRUS-FREE SOFTWARE
WHETHER IT IS FREEWARE, SHAREWARE OR COMMERCIAL SOFTWARE, AS LONG AS
!APPHELP IS LOCATED IN THE ROOT DIRECTORY OF THE DISK OR ARCHIVE THAT IS
BEING DISTRIBUTED. IT MUST NOT BE PRESENT INSIDE ANY OTHER DIRECTORY OR
APPLICATION DIRECTORY. FILES GENERATED BY MAKEHELP MAY BE INCLUDED WITH
SOFTWARE RELEASES, AS LONG AS !APPHELP IS ALSO DISTRIBUTED AS DETAILED
ABOVE. SUCH FILES MAY BE LOCATED IN SUBDIRECTORIES AND IN APPLICATION
DIRECTORIES. NO CHARGE MUST BE MADE FOR THE !APPHELP SOFTWARE OR THE MAKEHELP
COMPILER EXCEPT FOR REASONABLE DISTRIBUTION COSTS.

ANY QUERIES OR COMMENTS MAY BE ADDRESSED TO [e-mail]. BUG
REPORTS ARE WELCOME.

THIS VERSION IS NOT COMPLETE, BUT MAY BE DISTRIBUTED ACCORDING TO THE ABOVE
TERMS. PLEASE REPLACE ANY OLD COPIES OF APPHELP WITH THIS NEW VERSION AS IT
NOW HAS OFFICIAL FILE TYPE AND MESSAGE NUMBERS. YOU SHOULD SETTYPE ANY OLD
APPHELP FILES TO TYPE &3F6.

IF YOU WISH TO USE THE HELP APPLICATION IN A SOFTWARE RELEASE OF YOUR OWN,
PLEASE MAIL ME SO THAT I CAN LET YOU KNOW OF UPDATES TO THE SOFTWARE WHEN THEY
BECOME AVAILABLE SO THAT YOU CAN ALWAYS USE THE MOST UP TO DATE VERSION.
IF YOU CANNOT MAIL ME THEN WRITE TO ME AT

  57 LONGWAY AVE.
  CHARLTON KINGS,
  CHELTENHAM
  GL53 9JH

The Application Help program is designed to be the last word in Help
Applications. To try it out, double click on the !AppHelp icon. This will
load the Help on Help file. From there on the program should document
itself. The purpose of this document is to describe how to write help files
for your own applications. This is done with the MakeHelp program supplied.

makehelp [-e][-s][-v] <in_file> <out_file>

    -e export, include table of page and section names so they can be
       passed to the help displayer instead of section or page numbers
       THE -e OPTION IS NOT CURRENTLY SUPPORTED
    -s spelling, check spelling against file named in environmental
       variable Dictionary$File, and list words with questionable
       spelling on standard output
    -v verbose, print list of section and page names

MakeHelp is run from the command line, which allows it to be placed in
makefiles such as those used by amu. If you wanted to compile a help file
from the file HelpSource in the current directory, with spelling check, you
would use the commands:

Set Dictionary$File <Insert the filename of the dictionary here>
makehelp -s HelpSource !Help

The input file is a text file with certain special sequences. It is
recommended that you refer to the HelpSource file to help you understand the
following description. These are either escapes or commands. The most
important types of sequence are commands. Commands are sited on lines of
their own, there must be no other characters following a command unless it
has parameters, this means no trailing spaces. Commands all begin with a
full stop and are written in capital letters. The following commands are
used:

.END
.PAGE <page_name>
.SEARCH
.SECTION <section_name>

Escapes occur at any place in the text and are used to apply special effects
to the output text. They begin with a bar character (|), and are followed by
a single capital letter. Sometimes escapes have parameters, these occur
within a pair of curly brackets, and consist of a list of parameters
separated by commas. The space character should not occur anywhere within an
escape. The following escapes are provided.

 ||                          Print the bar character (|).
*|B                          Print a bullet character.
 |E{Effect}                  Text Effect (Used to change to the font).
*|G{section_name,page_name}  Link to glossary entry on given page.
 |J{section_name,page_name}  Jump to given page.
*|R                          Rule off (useful for tables).
 |S{sprite_name}             Plot named sprite.
 |T                          Tab character (Can accept real tabs too).
 |H                          Half tab.
 |F{filename}                File to run when button pressed
                             - must have full path.

The escapes marked by an asterisk are currently not implemented by both
MakeHelp and !AppHelp. Parameters to escapes and commands consist of at
least one, and not more than 29 alphanumeric characters and the underline
character, (A-Z, a-z, 0-9, _). Case is significant. The rest of the text is
just plain text, but it must fit into a structure given by commands:

<Title of Help File>
.SECTION <sect1>
.PAGE <page1>
<Text goes here>
.SEARCH
<Search window suggestions go here>
.END

The title of the file must go on the very first line, and should not run on
to the second. The .SECTION and the .PAGE must occupy the next two lines, it
is not possible to include text before the first section of a file, or
before the first page of a section. This also means that a .SECTION command
must always be immediately followed by a .PAGE. The text following this will
go on the very first page and it is recommended that this is a page of
contents. The file is split in to sections, which are like chapters, and are
themselves divided in to pages. A new page or section is begun with the
.PAGE or .SECTION command. It is important that all sections have unique
names, and that all pages within a section have unique names, it is also
important to use meaningful names, so they can be easily remembered. The
!AppHelp browse buttons are able to browse the pages in a section, but
cannot jump between pages. To do this, page to page links are required, like
those that are activated by clicking on a word when the hand-shaped pointer
is visible. These are made by including the J escape in the text. The
parameters it uses are the names that you give to the section and page that
you wish to jump to. A new page or section is begun with the .PAGE or
.SECTION command. If the phrase that is used by the J escape ends before the
end of the line another escape (E, F, J or G) must be used to mark the end
of the phrase. Sprites can be placed in the area affected by the J escape.
The G escape is similar to the J escape, but instead of jumping to another
page, it uses the text on the destination page as a glossary entry which is
displayed in a pop-up window. Glossary pages should not be accessible from
other pages. The F escape runs the named file when its corresponding button
is pressed. The filename given must have a full pathname, which can be
obtained from system variables if necessary. The named file can be an
application, a runnable file or even another help file. The E escape takes a
parameter which describes the sort of text that it produces:

NORMAL    The standard text used, use to switch off other effects
          caused by E, J or G escapes.
TITLE     Main title for the page.
BOLD      Used to highlight key words such as menu entries and
          button names.
SMALL     Used to make observations about the preceeding text.
ITALIC    Used to emphasise things.
SUBTITLE  Sub Heading.

The MakeHelp program provides reasonably helpful error messages which should
help you correct any errors reasonably quickly.

The location of the help file must be carefully considered because the Help
Application uses other files in the directory where it finds the help file.
These are:

HelpSpr    - Low resolution colour sprites
HelpSpr22  - High resolution colour sprites
HelpSpr23  - High resolution monochrome sprites
HelpExtra  - File containing details of bookmarks and annotations

It is obviously important to hide these files somewhere where they won't be
overwritten. Usually it is fine to put them in an application directory, but
sometimes it is necessary for a help file to appear alone, for instance to
document a command in the library, or to give help to novice users about
built in features of the machine. In these cases, it is usually best to make
a small application containing the help file and a !Run file of type Obey
with the following line in it:

<Obey$Dir>.!Help

and a sprite file with a sprite !<Application name> and possibly a small
version of the sprite too.

The dictionary file, <Dictionary$File> must contain alphabetically sorted
words, one to a line, and the output of MakeHelp should be saved either by a
redirection command, or with a task window, and run through a better spell
checker from a proprietary word processor, since the supplied dictionary
does not have many words.

When a task handle is given, the help window will be shut when the calling
task terminates. In the unlikely event that you want the window to stay
open, pass a task handle of 0.

Programs can call the help application up to display a particular page of
help using the following command:

*ShowHelp <HelpFile> <Section number> <Page number> <Task handle>

In future versions, message number &82601 (Message_AHSendHelp) will be a
possible alternative way to send help using a message block of the following
format:

   R1+20  Section number
   R1+24  Page number
   R1+28  Task handle
   R1+32  Help file, null terminated

This should be sent as a broadcast message of type 17 (Not recorded).

The 'Hot key' help function is supported by message &82600
(Message_AHRequestHelp). When your task receives this, it should endeavour
to send help to the AppHelp program either using the ShowHelp command or
Message_AHSendHelp. It must acknowledge the message (this will be done
automatically if you use Message_AHSendHelp provided you copy the my_ref
field of the original message into the your_ref field of the reply. If you
use ShowHelp to reply, you should explicitly acknowledge the message by
sending a message type 19, after copying my_ref into your_ref. If you can,
use the window and icon handles given to provide help specifically for those
objects. You should not acknowledge the message if you do not provide any
help, in which case the AppHelp support code will beep to indicate failure
to find any help. The format of Message_AHRequestHelp is:

   R1+20  Window handle
   R1+24  Icon handle

Thank-you to Dean Murphy of Acorn for discovering that
<AppHelp$Dir>.SendToHelp could be mistaken for the Icon virus by !VKiller,
(This software has been checked by !VKiller 1.400 and it found no viruses)
and for suggesting a configurable size type face. (Check the !Run file to
try out the experimental large text version).