7.5.1.1 Usage and Version Info Display

These will affect the way usage is seen and whether or not version information gets displayed.

‘full-usage’

If this attribute is provided, it may specify the full length usage text, or a variable name assignable to a char const * pointer, or it may be empty. The meanings are determined by the length.

• If not provided, the text will be computed as normal.
• If the length is zero, then the usage text will be derived from the current settings and inserted as text into the generated .c file.
• If the length is 1 to 32 bytes, then it is presumed to be a variable name that either points to or is an array of const chars.
• If it is longer than that, it is presumed to be the help text itself. This text will be inserted into the generated .c file.

This string should be readily translatable. Provision will be made to translate it if this is provided, if the source code is compiled with ENABLE_NLS defined, and no-xlate has not been set to the value anything. The untranslated text will be handed to dgettext("libopts", txt) and then gettext(txt) for translation, one paragraph at a time.

To facilitate the creation and maintenance of this text, you can force the string to be ignored and recomputed by specifying

AUTOOPTS_USAGE=compute

in the environment and requesting help or usage information. See See section Developer and User Notes.

‘short-usage’

If this attribute is provided, it is used to specify an abbreviated version of the usage text. This text is constructed in the same way as the full-usage, described above.

‘gnu-usage’

AutoOpts normaly displays usage text in a format that provides more information than the standard GNU layout, but that also means it is not the standard GNU layout. This attribute changes the default to GNU layout, with the AUTOOPTS_USAGE environment variable used to request autoopts layout. See See section Developer and User Notes.

‘usage-opt’

I apologize for too many confusing usages of usage. This attribute specifies that ‘--usage’ and/or ‘-u’ be supported. The help (usage) text displayed will be abbreviated when compared to the default help text.

‘no-misuse-usage’

When there is a command line syntax error, by default AutoOpts will display the abbreviated usage text, rather than just a one line “you goofed it, ask for usage” message. You can change the default behavior for your program by supplying this attribute. The user may override this choice, again, with the AUTOOPTS_USAGE environment variable. See See section Developer and User Notes.

‘prog-group’

The version text in the ‘getopt.tpl’ template will include this text in parentheses after the program name, when this attribute is specified. For example:

mumble (stumble) 1.0

says that the ‘mumble’ program is version 1.0 and is part of the ‘stumble’ group of programs.

‘usage’

If your program has some cleanup work that must be done before exiting on usage mode issues, or if you have to customize the usage message in some way, specify this procedure and it will be called instead of the default optionUsage() function. For example, if a program is using the curses library and needs to invoke the usage display, then you must arrange to call endwin() before invoking the library function optionUsage(). This can be handled by specifying your own usage function, thus:

void my_usage(tOptions * opts, int ex) { if (curses_window_active) endwin(); optionUsage(opts, ex); }

‘version’

Specifies the program version and activates the VERSION option, See section Automatically Supported Options.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.