rtsi.com/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/OSK/EFFO/pd1.lzh/SYS/HELP/help.hlp

Text File | 1990-02-03 | 16KB | 360 lines

@H
@T0
The advanced HELP utility offers structured access to all type of help
texts in OS-9/68k systems. The program replaces the standard utility
called "help".

Some quick hints how to use HELP:

  - Just type "help" at the shell prompt, and a list of available topics
    will appear, from which you may choose. Some topics will present
    a list of subtopics for more detailed help.

  - Type "?" at any prompt within HELP to get a list of available
    topics/subtopics.

  - Type Return at any subtopic prompt to step back towards the "root"
    of the topic tree. Typing Return at the root topic prompt will exit
    HELP.

  - Type "help <topic>" to see help on a specific topic.
@D1 W=25
Command_Line : 11
Interactive_Mode : 12
Help_Files : 3,31
Distribution_Rules : 4
@T11
SYNTAX  : help [<opts>] [<topic> {<subtopic>}] [<opts>]

USAGE   : help                     This will cause help to display a menu
                                   containing all topics for which help is
                                   available

          help <topic>             If help is available for <topic>, it
                                   will be displayed, else HELP tries to
                                   call <topic> as a program and passes "-?"
                                   as argument. If <topic> is a good OS-9
                                   program,it will display a short help text.

          help <topic> <subtopic>  Direct access to a subtopic. This is
                                   useful if you want to know some specific
                                   detail without reading all the general
                                   explanations. You may specify up to 8
                                   subtopics.

          help -r <topic>          This will search all help files and all
                                   subtopic levels recursively for a certain
                                   topic or subtopic. (see OPTIONS below)

OPTIONS : -? : show usage
          -r : recursive topic search. Only one topic may be specified
               in this mode.

NOTE    : Topic specifications may be abbreviated by typing only the
          first few characters. This allows fast access to topic with
          long and complicated name. Of course, topic specifications
          are case insensitive.
@T12
In the intercative mode, HELP displays a prompt whenever it is ready for
input. The prompt shows

   Topic ?

at the root level and

   this that Subtopic ?

at any subtopic level (while "this" and "that" represent the current
topic/subtopics). At these prompts, you may enter:

Return                   Returns to the overlying topic of the current
                         subtopic. If Return is typed at the top (root)
                         level, HELP terminates.

?                        Displays the list of available help topics.

<topic>                  Displays help for <topic> if available.

<topic> <subtopic> ...   Direct access to subtopics. You may specify
                         up to 8 subtopics separated by spaces.

NOTE : HELP performs automatic paging. After one screenfull of text,
       a prompt "[More...]" appears. Type Return to continue, "Q" to
       skip the rest of the help text and to advance to the next help menu
       or any subtopic of the current topic to get information on that
       subtopic immediately (listing of the current topic will be aborted).
@T3
All information that HELP can provide must be stored in one directory.
If the environment variable HELPDIR exists, it is assumed to be the
path of the help directory to be used. If HELPDIR is not defined in the
environment, HELP will use

  /dd/SYS/HELP

as default. This is the directory provided for help files by Microware
and I recommend not to use another directory without good reason.

HELP searches this directory for four different file types ("topic" stands
for the name of the command, program or other topic that is described in
the file):

  "topic"       Files with no extension are considered as simple text files
                describing a single topic. If help on "topic" is requested,
                HELP just lists that file. "topic" will also appear in the
                root help menu.

  "topic.man"   Files with extension ".man" are manual pages. Because under
                OS-9 they are often simple text files ("real" proff-formatted
                manual pages, if installed, will be kept in another directory
                anyway) they are treated like files without extension now.
                If a standard "man" establishes for OS-9 in the future,
                special handling for manual pages might be added to HELP.

  "topic.hlp"   Files with extension ".hlp" are text files with an internal
                structure. They contain multiple pages of text as well as
                lists of subtopics. A single ".hlp" file may contain a
                virtually unlimited number of subtopic levels. If help
                on "topic" is requested, HELP shows page number 0 as
                description of the topic and expects the first subtopic
                list on page number 1. "topic" will also appear in the
                root help menu. See subtopic "File_Structure" for
                details about ".hlp" file structure.

  "name.hlib"   This type of files is almost the same as ".hlp" files.
                The internal structure of ".hlp" and ".hlib" files is
                identical. The difference is the way how HELP uses ".hlib"
                files: It expects a list of topics (NOT subtopics) on
                page 1 of the ".hlib" file and will include those topics
                in the root help menu. "name" itself will NOT appear in
                the root menu.
                ".hlib" files are also called "Help libraries", because
                they contain not only a single topic but an entire
                library of (root) topics. Help libraries are useful to
                avoid thousands of help files. For example, help for all
                standard OS-9 commands could be included in a single
                ".hlib" file, but all commands would still be available
                in the root help menu.
                One caveat applies to help libraries: HELP will open all
                available ".hlib" files together to form the main menu.
                Therefore the number of help libraries is limited by the
                number of paths that can be open at once (32 minus 3
                standard paths minus 2 paths used internally = 27).
                However, it is recommended not to exploit this maximum
                because help access time increases with the number
                of help libraries (while it is independent of the number
                of ".hlp" files !!). In addition, many help libraries
                will lead to an overcrowded help root menu, which should
                be avoided for clarity, too.

  "name.ndx"    These are index files used by HELP to access ".hlp" and
                ".hlib" files. The ".ndx" files are NOT TEXTFILES. For each
                ".hlp" or ".hlib" file there must be a corresponding
                ".ndx" file. Index files can be easily created using the
                HELPINDEX utility. A new index file must be created
                whenever the associated help file has been changed.

Please read the following sections carefully before starting to write your own
help files. Aside from the techincal aspects described under "File_Structure"
the more general recommendations for writing help files discussed in
"Design_Hints" are important as well.
@D31
Design_Hints : 34
File_Structure : 32
Example : 33
@T32
A help file (".hlp" or ".hlib") is a normal text file. It can be edited
with any text editor. However, whenever a help file has been changed, the
index file must be remade using the HELPINDEX utility.

A valid help file must start with a header line:

   @H

The help file consists of directory pages and text pages. Each page must
have a unique number, but the numbering needs not to be contiguous or
in any particular order. The range for valid page numbers is 0..32767.

Text pages start with a page header line as follows:

   @T<page number>

All text between the page header line and the next line starting with an
"@" sign form one page.

Directory pages look as follows:

   @D<page number> [U] [W=<field width>]
   <topic> : <page # of description> [, <page # of subdirectory>]
   <topic>....
    etc.
   @...

The topics will be sorted alphabetically (case insensitive) by HELP for
displaying them in the menu. This sorting may be suppressed by an optional
"U" (meaning "Unsorted") following the directory page number. If the U is
found,the topics will appear in the same order as they are listed in the
directory page. A second option "W" can be used to specify the field
width used for the menu items (default is 15). Note that items exceeding
the field width will NOT be truncated but displayed over multiple fields.

The <topic> must not exceed 39 characters in length. The first page number
indicates where a description page of the topic can be found within the
file. The second page number (separated by a comma) is optional and
specifies another directory page containing further subtopics of the
<topic>.

If the separator between <topic> and the first page number is a semicolon
instead of a colon then the <topic> will not appear in the menu but will
be available for topic search. This can be used to implement shortcuts
to access important help pages.

Altough it is possible to implement all sorts of funny subtopic structures
including loops, nets etc. it is strongly recommended to use only strictly
hierachic tree structures to maintain clarity for the user of the help
file. Loops can even cause hangs if recursive search is used.

Notes: - Please remember also that HELP expects to find a basic description
         of the topic on (text) page number 0 and a subtopic list on
         (directory) page 1 of a ".hlp" file. For ".hlib" files, page 0 is
         not required, but page 1 must be a directory containing the topics
         of the library.
       - header lines other than @H, @T and @D are currently not used but
         are reserved for future extensions of HELP's functionality.
@T34
It is very important to maintain a certain uniformity in the entire help
system. Therefore this paragraph gives a few hints when and how to divide
a topic in what kind of subtopics. I strongly recommend to follow this
rules as far as it is possible in your context.

 1. Do not subdivide very simple topics. When a description of a topic
    is only one or two screen pages long, subtopics are just annoying for
    the user.

 2. If a medium sized topic needs subtopics, try to use one of the "standard"
    subtopics listed below:
     "About.."  for general information about the program that is not directly
                related to the functional description of the program (like
                name(s)/address(es) of the author(s) of a project, the
                basic ideas/philosophy behind a program etc.).
     "Hints.."  Hints for the beginner. Especially for programs with many
                features or subcommands, this section should explain
                what function applies to what situation (e.g "to do task xxx,
                you may use feature x,y or z").
     "Options"  For well behaved OS-9 utilities, this section should give a
                description of all command line options (in more detail than
                -?).
     "Examples" Include examples under this subtopic, if there are examples
                at all.
     "Copyright_Notes", "Edition_Notes", "Distribution_Rules" etc.

  3. Always think of the main purpose of on-line help: Short information
     for users that know the basics, but have forgotten some detail.
     Thus, if your help file contains lengthy introductionary information,
     separate it from the "quick-reference" part by putting it into a
     subtopic like "Introduction" or "Hints...".

  4. Do not use too many subtopic levels. Most "quick-reference" help
     should be available as a simple subtopic of a main topic. Level
     3 and above should be reserved for less frequently used (deep detail)
     information.

Of course, there are always exceptions to the rules presented above. But
even if these recommendations can't be applied strictly all the time, they
still should give an idea how to write help files in general.
@T33
This is a very small example help file:

--- beginning of example ---

   @H
   @T0
   This is an example help file
   You may now choose one of the following subtopics
   @D1
   Help_Package : 3,4
   Fox : 2
   @T2
   The Quick Brown Fox Jumps Over The Lazy Dog.
   @T3
   This are the files the HELP package consists of
   @D4 U
   help : 5
   helpindex : 6
   help.hlp : 7
   @D5
   "help"  : The help utility itself.
   @D6
   "helpindex"   : Utility used to create index files for help files
   @D7
   "help.hlp"    : A help file describing the help utility itself

--- end of example ---

Assuming the file was called "example.hlp", the following help structure
would result:

root menu
 |
 |-- a_topic       |---- Fox
 |                 |
 |-- example ------|                      |--- help
 |                 |                      |
 |-- x_topic       |---- Help_Package ----|--- helpindex
                                          |
                                          |--- help.hlp

If the file was called "example.hlib", the help structure for the same
example file would look like this:

root menu
 |
 |-- a_topic
 |
 |-- Fox              |--- help
 |                    |
 |-- Help_Package ----|--- helpindex
 |                    |
 |-- x_topic          |--- help.hlp

Note also that the subtopics "help","help.hlp" and "helpindex" will not
appear in alphabetical order (which would list "help.hlp" before "helpindex")
because the "U" option is present in the header line of directory page #4.
@T4
*****************************************************************
*  HELP and HELPINDEX (c) 1989 by Lukas Zeller, CH-Maennedorf   *
*    email:   [e-mail], [e-mail]           *
*             ..!mcvax!cernvax!chx400!ethz!zeller               *
*    DECNet:  PSI%4991108411::STRATI::ZELLER                    *
*    OS9-BBS: LZELLER                                           *
*****************************************************************

This HELP utility is public domain and may be used and distributed freely
as long as the following conditions are met:

 1. This Program may only be used for peaceful applications. I do NOT
    ALLOW using this program for anything that has to do with development,
    testing or manufacturing of weapons of any type.

 2. This text as well as all copyright messages (in this file as well
    as in the source texts and the code files) must be retained.

 3. When distributing this program, source code may or may not be
    included, but the file "help.hlp" as well as the index
    creator utility "helpindex" HAVE TO be included.

 4. Modified or enhanced versions of the program may only be distributed
    if they are compatible with the original help file format described
    in this file. Extensions to the help file format must be clearly
    documented in this file.

Because the usefulness of this HELP utility increases with the
availability of help files, this program may be included even in
commercial packages supplying documentation in HELP format, as long as
the purpose of the package does not conflict with condition #1 above.

Please note that information in help files/libraries might be copyrighted
by third parties and therefore distribution might be restricted.

For bug reports, comments and suggestions, please contact the author (see
email paths above). Thank you !