Assist in the display of help text
showhelp.c
 
Prototype:   void showhelp(char *pgm, char *version_id, char *usage, char *HelpText[], int HelpData[])
Parameters: pgm program name
  version_id version information for program
  usage brief instructions on thow to use the calling program
  HelpText array of string pointers ending with NULL pointer
  HelpData numeric values associated with  HelpText
Return Value: none
 
 
Prototype:   void uhoh(char *pgm, char *usage)
Parameters: pgm program name
  usage brief instructions on thow to use the calling program
Return Value: none
 
 
I like to put usage and help text in all the filters I create. I wrote the two routines in showhelp.c to assist in this.
 
uhoh() is the simpler routine. It formats and displays a one-line usage message consisting of pgm followed by usage followed by a fixed string "(-h for more detail)".

 
See the purple text below for an example
.
The showhelp() routine does the following:
 
  • calls the uhoh() routine to display the usage line using the pgm and usage arguments.
  • formats and displays the strings it received in the HelpText array. There is a limited printf-like facility when these strings are displayed; each string is scanned looking for "%d". If one is found then the corresponding value (first, second ...) from the HelpData is used as the number replacing %d.
  • formats and displays some fixed text after the HelpText.
  • a brief description of the conventions used to invoke the calling program.
    See the red text below for an example.
  • a brief description of the format for options.
    It is up to the user to handle -h in the callback routine in addition to whatever options [s]he might specify.
    See the green text below for an example.
  • displays the version_id (which, in my case, is usually an RCS id string).
    See the orange text below for an example
Example
 
Usage: mll [-t#m#s#lb3h] [files...]
 
Measure length of lines in a file.
 
Options :
        -t#  treats tabstops as occurring every # characters (default=8)
        -m#  information only for files with longest line > # (default=80)
        -s#  indicates lines longer than # (default=80)
        -l   displays longest line and lines longer than -s#
        -b   treats BACKSPACE and DELETE as normal characters
             (otherwise they decrease the char count by one)
        -3   count trigraphs as 3 characters
             trigraph characters are #, [, ], {, }, \, ^,  and ~
        -h   display this message and terminate
 
The  "files"  argument  indicates the names of files to be converted. If no
files are specified or if the filename is a single '-', standard  input  is
converted.
 
Converted   output is  always  written to  single  standard  output  stream
(which may be redirected to a file).
 
On specifying options:
    Option  letters  are case-insensitive,  e.g.  -h and -H are equivalent.
 
    Options must  occur before  filename  arguments  and start  with a dash
    ('-')  immediately followed by an  option character.
 
    For options that take values  (example: -t#),  the value may optionally
    be separated from the option letter by white space.
 
                     (mll $Revision: 1.6 $ $Date: 2007-10-01 19:37:41-04 $)
 
Previous  |  Next ]     [ Up  |  First  |  Last ]     (Article 29 of 485)
 
Comments, flames, broken links?
Please send email to maintainer@intricate-simplicity.com