home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 December / simtel1292_SIMTEL_1292_Walnut_Creek.iso / msdos / c / help.arc / HELP.MAN < prev    next >
Text File  |  1988-03-10  |  6KB  |  179 lines
  1. HELP              Michael Shiels' DOSIX Programmer's Manual                HELP
  2.  
  3.  
  4.  
  5. NAME
  6.      help - user-friendly documentation reader
  7.  
  8.  
  9. SYNOPSIS
  10.      help [ -c<#>d<str>h<#>vw<#> ] [ topic-path ]
  11.  
  12.  
  13. DESCRIPTION
  14.      Help is a documentation reader based closely on the VMS(tm)
  15.      help facility.  Documentation texts are arranged in a tree,
  16.      and the users reads them with the built in interface or with
  17.      another file viewer. Help allows documentation to be treated
  18.      as an n-tree, the structure of the help tree is the structure
  19.      of the directory tree in which the help files reside.
  20.  
  21.      The help program is invoked from the shell like
  22.  
  23.           help [ options ] topic sub-topic sub-sub-topic ...
  24.  
  25.      Topic may be any top-level help file name.  A topic-path is
  26.      a path of topics and their subtopics, down into the tree.
  27.      Topic and subtopic names may be abbreviated, but no wild-
  28.      cards are recognized.
  29.  
  30.      The options are:
  31.  
  32.      c<#>   The number will be used as the number of columns for the
  33.             Topic/Subtopic listings.
  34.  
  35.      d<str> Next argument is the help root directory.  Default is
  36.             what ever $HELPDIR is set to or /usr/help.
  37.  
  38.      h<#>   The number will be used as the maximum number of help
  39.             topics/subtopics which will ever occur at any level.
  40.             This is usually set up in the HELP.RC file.
  41.  
  42.      v      This triggers vertical instead of horizontal printing
  43.             of the help topics/subtopics.
  44.  
  45.      w<#>   The number will be used as the maximum number of help
  46.             topics/subtopics which will be requested during an
  47.             ambiguous helprequest.
  48.             This is usually set up in the HELP.RC file.
  49.  
  50.      
  51.      The help interactive mode asks the user what help he would
  52.      like next.  The prompt looks like this:
  53.  
  54.      Topic?
  55.  
  56.      or like this:
  57.  
  58.       vi commands deletion Subtopic?
  59.  
  60.      Where "vi commands deletion" is the help tree path. This
  61.      path is printed for each prompt, and as a header for each
  62.      help text.
  63.  
  64.      The following commands are meaningful in to the "topic?"
  65.      prompt:
  66.  
  67.      ?  Print current introduction and subtopic-list again.
  68.  
  69.      #  Print current introduction again.
  70.  
  71.      $  Print current subtopic-list again.
  72.  
  73.      !<CR>
  74.         To shell to the current setting of $COMSPEC.
  75.  
  76.      !command
  77.         To run the 'command' under $COMSPEC.
  78.  
  79.      Return <CR>
  80.         Exit this level of help.  If at top level, goes back to
  81.         calling program.
  82.  
  83.      <subtopic-name>
  84.         Read the documentation for this subtopic, or all subto-
  85.         pics for which this is a legal abbreviation.  Wildcards
  86.         are not permitted, but a short abbreviation matches
  87.         everything longer.
  88.  
  89.      ^Z Exit the help program.
  90.  
  91.  
  92. HELP FILES
  93.  
  94.      Help files are the text and directories of the help documen-
  95.      tation tree.  There are four kinds of help files: topic directory,
  96.      introduction file, and subtopic file.
  97.  
  98.      The usual way of calling help is to just type
  99.  
  100.      % help
  101.  
  102.      in the shell.  This brings up help in interactive mode at the
  103.      top level of topics.  The user can always abort with ctrl/Z.
  104.  
  105.  
  106. GENERAL ENVIRONMENT VARIABLES
  107.      SWITCHAR - is used to detect which character you wish to use for
  108.                 the command line option trigger.  Usually it is '/' but
  109.                 if you are a UNIXer you can set it to '-'.
  110.  
  111.      GETSOPTS - is used to locate the HELP.RC file which can be used
  112.                 to change some of the defaults for the command line
  113.                 switches.  Usually it is used to increase the number
  114.                 of help topics/subtopics which can be available at
  115.                 any one level.
  116.  
  117.      COMSPEC - this is used to locate the COMMAND shell.
  118.  
  119.  
  120. ENVIRONMENT VARIABLES
  121.      HELPOPTS - is used to override the HELP.RC file and set up personal
  122.                 command line preferences.
  123.  
  124.      HELPDIR - is the root of the help system.
  125.  
  126.      HELPDISPLAY1 - can be set to a program (such as more) which will be
  127.                     used to display the introductory text file if there
  128.                     is one.
  129.  
  130.      HELPDISPLAY2 - can be set to a program (such as more) which will be
  131.                     used to display the help files.
  132.  
  133.  
  134. EXAMPLE
  135.      HELPDIR = J:/HELP
  136.      Thie disk structure would look like this
  137.  
  138.      J:\HELP\INTRO.TXT              Introduction which will be display when
  139.                                     the topics at this level are displayed
  140.      J:\HELP\AUTOEXEC.HLP           Help Text
  141.      J:\HELP\GNUPLOT.HLD            Subtopic Directory
  142.      J:\HELP\GNUPLOT.HLD\PLOT.HLP   Subtopic Help Text
  143.      J:\HELP\GNUPLOT.HLD\EXPR.HLD   SubSubtopic Directory
  144.      ...
  145.  
  146.  
  147. AUTHOR
  148.      Michael A. Shiels ( mshiels@electrical.watstar.waterloo.EDU )
  149.      604 Bridle Wood
  150.      Burlington, Ontario
  151.      CANADA, L7L 4C7
  152.  
  153.  
  154. FILES
  155.      $GETSOPTS/HELP.RC
  156.      $HELPDIR/...
  157.      NANSI.SYS
  158.  
  159.  
  160. NOTES
  161.      This program will use the 'RAW' mode of the NANSI.SYS driver if it
  162.      is loaded, but it can still be run with ANSI.SYS.
  163.  
  164.      All user prompting is read using 'cgets' so CED will work at the
  165.      help prompts.
  166.  
  167.  
  168. SEE ALSO
  169.      more, pc-more, smore, list, nansi, ced.
  170.  
  171.  
  172. DIAGNOSTICS
  173.      Error messages are printed whenever a request is made to get
  174.      documentation that does not exists, or is not accessible.
  175.  
  176.  
  177. BUGS
  178.      The file naming conventions are very strict.
  179.