home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / EFFO / pd1.lzh / SYS / HELP / help.hlp < prev    next >
Text File  |  1990-02-03  |  16KB  |  360 lines

  1. @H
  2. @T0
  3. The advanced HELP utility offers structured access to all type of help
  4. texts in OS-9/68k systems. The program replaces the standard utility
  5. called "help".
  6.  
  7. Some quick hints how to use HELP:
  8.  
  9.   - Just type "help" at the shell prompt, and a list of available topics
  10.     will appear, from which you may choose. Some topics will present
  11.     a list of subtopics for more detailed help.
  12.  
  13.   - Type "?" at any prompt within HELP to get a list of available
  14.     topics/subtopics.
  15.  
  16.   - Type Return at any subtopic prompt to step back towards the "root"
  17.     of the topic tree. Typing Return at the root topic prompt will exit
  18.     HELP.
  19.  
  20.   - Type "help <topic>" to see help on a specific topic.
  21. @D1 W=25
  22. Command_Line : 11
  23. Interactive_Mode : 12
  24. Help_Files : 3,31
  25. Distribution_Rules : 4
  26. @T11
  27. SYNTAX  : help [<opts>] [<topic> {<subtopic>}] [<opts>]
  28.  
  29. USAGE   : help                     This will cause help to display a menu
  30.                                    containing all topics for which help is
  31.                                    available
  32.  
  33.           help <topic>             If help is available for <topic>, it
  34.                                    will be displayed, else HELP tries to
  35.                                    call <topic> as a program and passes "-?"
  36.                                    as argument. If <topic> is a good OS-9
  37.                                    program,it will display a short help text.
  38.  
  39.           help <topic> <subtopic>  Direct access to a subtopic. This is
  40.                                    useful if you want to know some specific
  41.                                    detail without reading all the general
  42.                                    explanations. You may specify up to 8
  43.                                    subtopics.
  44.  
  45.           help -r <topic>          This will search all help files and all
  46.                                    subtopic levels recursively for a certain
  47.                                    topic or subtopic. (see OPTIONS below)
  48.  
  49. OPTIONS : -? : show usage
  50.           -r : recursive topic search. Only one topic may be specified
  51.                in this mode.
  52.  
  53. NOTE    : Topic specifications may be abbreviated by typing only the
  54.           first few characters. This allows fast access to topic with
  55.           long and complicated name. Of course, topic specifications
  56.           are case insensitive.
  57. @T12
  58. In the intercative mode, HELP displays a prompt whenever it is ready for
  59. input. The prompt shows
  60.  
  61.    Topic ?
  62.  
  63. at the root level and
  64.  
  65.    this that Subtopic ?
  66.  
  67. at any subtopic level (while "this" and "that" represent the current
  68. topic/subtopics). At these prompts, you may enter:
  69.  
  70. Return                   Returns to the overlying topic of the current
  71.                          subtopic. If Return is typed at the top (root)
  72.                          level, HELP terminates.
  73.  
  74. ?                        Displays the list of available help topics.
  75.  
  76. <topic>                  Displays help for <topic> if available.
  77.  
  78. <topic> <subtopic> ...   Direct access to subtopics. You may specify
  79.                          up to 8 subtopics separated by spaces.
  80.  
  81. NOTE : HELP performs automatic paging. After one screenfull of text,
  82.        a prompt "[More...]" appears. Type Return to continue, "Q" to
  83.        skip the rest of the help text and to advance to the next help menu
  84.        or any subtopic of the current topic to get information on that
  85.        subtopic immediately (listing of the current topic will be aborted).
  86. @T3
  87. All information that HELP can provide must be stored in one directory.
  88. If the environment variable HELPDIR exists, it is assumed to be the
  89. path of the help directory to be used. If HELPDIR is not defined in the
  90. environment, HELP will use
  91.  
  92.   /dd/SYS/HELP
  93.  
  94. as default. This is the directory provided for help files by Microware
  95. and I recommend not to use another directory without good reason.
  96.  
  97. HELP searches this directory for four different file types ("topic" stands
  98. for the name of the command, program or other topic that is described in
  99. the file):
  100.  
  101.   "topic"       Files with no extension are considered as simple text files
  102.                 describing a single topic. If help on "topic" is requested,
  103.                 HELP just lists that file. "topic" will also appear in the
  104.                 root help menu.
  105.  
  106.   "topic.man"   Files with extension ".man" are manual pages. Because under
  107.                 OS-9 they are often simple text files ("real" proff-formatted
  108.                 manual pages, if installed, will be kept in another directory
  109.                 anyway) they are treated like files without extension now.
  110.                 If a standard "man" establishes for OS-9 in the future,
  111.                 special handling for manual pages might be added to HELP.
  112.  
  113.   "topic.hlp"   Files with extension ".hlp" are text files with an internal
  114.                 structure. They contain multiple pages of text as well as
  115.                 lists of subtopics. A single ".hlp" file may contain a
  116.                 virtually unlimited number of subtopic levels. If help
  117.                 on "topic" is requested, HELP shows page number 0 as
  118.                 description of the topic and expects the first subtopic
  119.                 list on page number 1. "topic" will also appear in the
  120.                 root help menu. See subtopic "File_Structure" for
  121.                 details about ".hlp" file structure.
  122.  
  123.   "name.hlib"   This type of files is almost the same as ".hlp" files.
  124.                 The internal structure of ".hlp" and ".hlib" files is
  125.                 identical. The difference is the way how HELP uses ".hlib"
  126.                 files: It expects a list of topics (NOT subtopics) on
  127.                 page 1 of the ".hlib" file and will include those topics
  128.                 in the root help menu. "name" itself will NOT appear in
  129.                 the root menu.
  130.                 ".hlib" files are also called "Help libraries", because
  131.                 they contain not only a single topic but an entire
  132.                 library of (root) topics. Help libraries are useful to
  133.                 avoid thousands of help files. For example, help for all
  134.                 standard OS-9 commands could be included in a single
  135.                 ".hlib" file, but all commands would still be available
  136.                 in the root help menu.
  137.                 One caveat applies to help libraries: HELP will open all
  138.                 available ".hlib" files together to form the main menu.
  139.                 Therefore the number of help libraries is limited by the
  140.                 number of paths that can be open at once (32 minus 3
  141.                 standard paths minus 2 paths used internally = 27).
  142.                 However, it is recommended not to exploit this maximum
  143.                 because help access time increases with the number
  144.                 of help libraries (while it is independent of the number
  145.                 of ".hlp" files !!). In addition, many help libraries
  146.                 will lead to an overcrowded help root menu, which should
  147.                 be avoided for clarity, too.
  148.  
  149.   "name.ndx"    These are index files used by HELP to access ".hlp" and
  150.                 ".hlib" files. The ".ndx" files are NOT TEXTFILES. For each
  151.                 ".hlp" or ".hlib" file there must be a corresponding
  152.                 ".ndx" file. Index files can be easily created using the
  153.                 HELPINDEX utility. A new index file must be created
  154.                 whenever the associated help file has been changed.
  155.  
  156. Please read the following sections carefully before starting to write your own
  157. help files. Aside from the techincal aspects described under "File_Structure"
  158. the more general recommendations for writing help files discussed in
  159. "Design_Hints" are important as well.
  160. @D31
  161. Design_Hints : 34
  162. File_Structure : 32
  163. Example : 33
  164. @T32
  165. A help file (".hlp" or ".hlib") is a normal text file. It can be edited
  166. with any text editor. However, whenever a help file has been changed, the
  167. index file must be remade using the HELPINDEX utility.
  168.  
  169. A valid help file must start with a header line:
  170.  
  171.    @H
  172.  
  173. The help file consists of directory pages and text pages. Each page must
  174. have a unique number, but the numbering needs not to be contiguous or
  175. in any particular order. The range for valid page numbers is 0..32767.
  176.  
  177. Text pages start with a page header line as follows:
  178.  
  179.    @T<page number>
  180.  
  181. All text between the page header line and the next line starting with an
  182. "@" sign form one page.
  183.  
  184. Directory pages look as follows:
  185.  
  186.    @D<page number> [U] [W=<field width>]
  187.    <topic> : <page # of description> [, <page # of subdirectory>]
  188.    <topic>....
  189.     etc.
  190.    @...
  191.  
  192. The topics will be sorted alphabetically (case insensitive) by HELP for
  193. displaying them in the menu. This sorting may be suppressed by an optional
  194. "U" (meaning "Unsorted") following the directory page number. If the U is
  195. found,the topics will appear in the same order as they are listed in the
  196. directory page. A second option "W" can be used to specify the field
  197. width used for the menu items (default is 15). Note that items exceeding
  198. the field width will NOT be truncated but displayed over multiple fields.
  199.  
  200. The <topic> must not exceed 39 characters in length. The first page number
  201. indicates where a description page of the topic can be found within the
  202. file. The second page number (separated by a comma) is optional and
  203. specifies another directory page containing further subtopics of the
  204. <topic>.
  205.  
  206. If the separator between <topic> and the first page number is a semicolon
  207. instead of a colon then the <topic> will not appear in the menu but will
  208. be available for topic search. This can be used to implement shortcuts
  209. to access important help pages.
  210.  
  211. Altough it is possible to implement all sorts of funny subtopic structures
  212. including loops, nets etc. it is strongly recommended to use only strictly
  213. hierachic tree structures to maintain clarity for the user of the help
  214. file. Loops can even cause hangs if recursive search is used.
  215.  
  216. Notes: - Please remember also that HELP expects to find a basic description
  217.          of the topic on (text) page number 0 and a subtopic list on
  218.          (directory) page 1 of a ".hlp" file. For ".hlib" files, page 0 is
  219.          not required, but page 1 must be a directory containing the topics
  220.          of the library.
  221.        - header lines other than @H, @T and @D are currently not used but
  222.          are reserved for future extensions of HELP's functionality.
  223. @T34
  224. It is very important to maintain a certain uniformity in the entire help
  225. system. Therefore this paragraph gives a few hints when and how to divide
  226. a topic in what kind of subtopics. I strongly recommend to follow this
  227. rules as far as it is possible in your context.
  228.  
  229.  1. Do not subdivide very simple topics. When a description of a topic
  230.     is only one or two screen pages long, subtopics are just annoying for
  231.     the user.
  232.  
  233.  2. If a medium sized topic needs subtopics, try to use one of the "standard"
  234.     subtopics listed below:
  235.      "About.."  for general information about the program that is not directly
  236.                 related to the functional description of the program (like
  237.                 name(s)/address(es) of the author(s) of a project, the
  238.                 basic ideas/philosophy behind a program etc.).
  239.      "Hints.."  Hints for the beginner. Especially for programs with many
  240.                 features or subcommands, this section should explain
  241.                 what function applies to what situation (e.g "to do task xxx,
  242.                 you may use feature x,y or z").
  243.      "Options"  For well behaved OS-9 utilities, this section should give a
  244.                 description of all command line options (in more detail than
  245.                 -?).
  246.      "Examples" Include examples under this subtopic, if there are examples
  247.                 at all.
  248.      "Copyright_Notes", "Edition_Notes", "Distribution_Rules" etc.
  249.  
  250.   3. Always think of the main purpose of on-line help: Short information
  251.      for users that know the basics, but have forgotten some detail.
  252.      Thus, if your help file contains lengthy introductionary information,
  253.      separate it from the "quick-reference" part by putting it into a
  254.      subtopic like "Introduction" or "Hints...".
  255.  
  256.   4. Do not use too many subtopic levels. Most "quick-reference" help
  257.      should be available as a simple subtopic of a main topic. Level
  258.      3 and above should be reserved for less frequently used (deep detail)
  259.      information.
  260.  
  261. Of course, there are always exceptions to the rules presented above. But
  262. even if these recommendations can't be applied strictly all the time, they
  263. still should give an idea how to write help files in general.
  264. @T33
  265. This is a very small example help file:
  266.  
  267. --- beginning of example ---
  268.  
  269.    @H
  270.    @T0
  271.    This is an example help file
  272.    You may now choose one of the following subtopics
  273.    @D1
  274.    Help_Package : 3,4
  275.    Fox : 2
  276.    @T2
  277.    The Quick Brown Fox Jumps Over The Lazy Dog.
  278.    @T3
  279.    This are the files the HELP package consists of
  280.    @D4 U
  281.    help : 5
  282.    helpindex : 6
  283.    help.hlp : 7
  284.    @D5
  285.    "help"  : The help utility itself.
  286.    @D6
  287.    "helpindex"   : Utility used to create index files for help files
  288.    @D7
  289.    "help.hlp"    : A help file describing the help utility itself
  290.  
  291. --- end of example ---
  292.  
  293. Assuming the file was called "example.hlp", the following help structure
  294. would result:
  295.  
  296. root menu
  297.  |
  298.  |-- a_topic       |---- Fox
  299.  |                 |
  300.  |-- example ------|                      |--- help
  301.  |                 |                      |
  302.  |-- x_topic       |---- Help_Package ----|--- helpindex
  303.                                           |
  304.                                           |--- help.hlp
  305.  
  306. If the file was called "example.hlib", the help structure for the same
  307. example file would look like this:
  308.  
  309. root menu
  310.  |
  311.  |-- a_topic
  312.  |
  313.  |-- Fox              |--- help
  314.  |                    |
  315.  |-- Help_Package ----|--- helpindex
  316.  |                    |
  317.  |-- x_topic          |--- help.hlp
  318.  
  319. Note also that the subtopics "help","help.hlp" and "helpindex" will not
  320. appear in alphabetical order (which would list "help.hlp" before "helpindex")
  321. because the "U" option is present in the header line of directory page #4.
  322. @T4
  323. *****************************************************************
  324. *  HELP and HELPINDEX (c) 1989 by Lukas Zeller, CH-Maennedorf   *
  325. *    email:   zeller@strati.ethz.ch, zeller@ethz.uucp           *
  326. *             ..!mcvax!cernvax!chx400!ethz!zeller               *
  327. *    DECNet:  PSI%4991108411::STRATI::ZELLER                    *
  328. *    OS9-BBS: LZELLER                                           *
  329. *****************************************************************
  330.  
  331. This HELP utility is public domain and may be used and distributed freely
  332. as long as the following conditions are met:
  333.  
  334.  1. This Program may only be used for peaceful applications. I do NOT
  335.     ALLOW using this program for anything that has to do with development,
  336.     testing or manufacturing of weapons of any type.
  337.  
  338.  2. This text as well as all copyright messages (in this file as well
  339.     as in the source texts and the code files) must be retained.
  340.  
  341.  3. When distributing this program, source code may or may not be
  342.     included, but the file "help.hlp" as well as the index
  343.     creator utility "helpindex" HAVE TO be included.
  344.  
  345.  4. Modified or enhanced versions of the program may only be distributed
  346.     if they are compatible with the original help file format described
  347.     in this file. Extensions to the help file format must be clearly
  348.     documented in this file.
  349.  
  350. Because the usefulness of this HELP utility increases with the
  351. availability of help files, this program may be included even in
  352. commercial packages supplying documentation in HELP format, as long as
  353. the purpose of the package does not conflict with condition #1 above.
  354.  
  355. Please note that information in help files/libraries might be copyrighted
  356. by third parties and therefore distribution might be restricted.
  357.  
  358. For bug reports, comments and suggestions, please contact the author (see
  359. email paths above). Thank you !
  360.