Museum

9.0;hlpver (help_version), revision 9.0, 85/03/26
HLPVER (HELP_VERSION) -- Provide HELP support for Shell scripts.
usage:  HLPVER script_name version ^1


FORMAT

  HLPVER script_name version ^1


  HLPVER  provides  access  to the DOMAIN HELP system utilities that support the
  standard command options -HELP, -VERSION, and -USAGE for Shell commands.    By
  placing  the  HLPVER command inside a Shell script, you can allow users of the
  script to specify these three standard command options and receive  meaningful
  output.

  HLPVER  looks for help information in a file called /SYS/HELP/script_name.HLP.
  HELP files have special information  at  the  top  that  HLPVER  uses.    This
  information  must  follow  a standard format.  The following example shows the
  header of the HELP file for the WD (WORKING_DIRECTORY) command.

      1.1;wd (working_directory), revision 1.1, 81/06/27
      WD (WORKING_DIRECTORY) -- Set or display the current working directory.
      usage:  WD [pathname]

  All HLPVER output goes to standard output (normally directed  to  the  process
  transcript  pad).   HLPVER returns the first line of the HELP file in response
  to -VERSION.  It returns the second line through the first blank line  in  the
  file in response to -USAGE.  It returns the entire file in response to -HELP.

  Any  user file placed in the /SYS/HELP directory is also available to the HELP
  command  for  display  in  a  standard   HELP   window.      Thus   the   file
  /SYS/HELP/MARY.HLP can be viewed with $ HELP MARY regardless of whether or not
  you are using HLPVER inside the MARY script.  HLPVER is solely for the purpose
  of enabling the three standard command options mentioned above.


ARGUMENTS

  script_name
  (required)          Specify  the  name  of  the script for which HELP is to be
                     provided.  The name is the right-most leaf in the pathname,
                     not  the  entire  pathname of the script.  HLPVER uses this
                     name to construct the pathname for  the  HELP  file  to  be
                     returned (i.e., /SYS/HELP/script_name.HLP).

  version
  (required)          Specify  the  version  number of the Shell script.  HLPVER
                     compares this number to the version number in the HELP file
                     (the   first  characters  in  the  file  up  to  the  first
                     semicolon) and returns an error if they do not match.  This
                     allows  you  to  coordinate  versions of the script and the
                     HELP file.

  ^1
  (required)         Pass in the desired option from the  command  line.    "^1"
                     must   appear  literally  so  that  HLPVER  can  tell  what
                     information to return (-HELP, -VERSION, or  -USAGE).    See
                     the example below.


EXAMPLES

  Assume that the following lines appear in a file called "test_script":

      #
      # Example script showing HLPVER usage.
      #
      hlpver test_script 1.0 ^1
      args "Please enter ..."
         .
         .
         .
      # End of script

  When the user types:

      $ test_script -help

  HLPVER  returns  the  contents  of /SYS/HELP/TEST_SCRIPT.HLP to the transcript
  pad.  Likewise, when the user types:

      $ test_script -version

  HLPVER returns the first line of the HELP file containing the version number.