Museum

10.0;hlpver (help_version), revision 1.0, 88/01/21
hlpver (help_version) -- Provide HELP support for shell scripts.
usage: hlpver script_name version ^1



DESCRIPTION
     hlpver provides access to the Domain/OS 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 cpf
     (copy_file) command.

     10.0;wd (working_directory), revision 1.0, 88/06/06
     cpf (copy_file) - copy a file
     usage:  cpf source_pathname [target_ pathname]
                 [-c|-r] [-chn] [-f] [-lf] [-ldl]
                 [-du] [-dacl|-sacl] [-subs|-nsubs]
                 [-pdt] [-cwl] {CL}

     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 you are using hlpver inside the script mary.
     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 (that is, /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 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 you type

     $ test_script -help

     hlpver returns the contents of /sys/help/test_script.hlp to the
     transcript pad.  Likewise, when you type:

     $ test_script -version

     hlpver returns the first line of the help file containing the version
     number.