Assist in the display of help text

Assist in the display of help text

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)