7.3 Developer and User Notes

The formatting of the usage message can be controlled with the use of the AUTOOPTS_USAGE environment variable. If it contains any of five possible comma separated values, it will affect ‘libopts’ behavior. Any extraneous or conflicting data will cause its value to be ignored.

If the program attributes long-usage and short-usage have been specified (see section Usage and Version Info Display), these strings are used for displaying full usage and abbreviated usage. “Full usage” is used when usage is requested, “abbreviated usage” when a usage error is detected. If these strings are not provided, the usage text is computed.

The AUTOOPTS_USAGE environment variable may be set to the comma and/or white space separated list of the following strings:

‘compute’

Ignore the provision of long-usage and short-usage attributes, and compute the usage strings. This is useful, for example, if you wish to regenerate the basic form of these strings and either tweak them or translate them. The methods used to compute the usage text are not suitable for translation.

‘gnu’

The format of the usage text will be displayed in GNU-normal form. The default display for ‘--version’ will be to include a note on licensing terms.

‘autoopts’

The format of the extended usage will be in AutoOpts’ native layout. The default version display will be one line of text with the last token the version. gnu and autoopts conflict and may not be used together.

‘no-misuse-usage’

When an option error is made on the command line, the abbreviated usage text will be suppressed. An error message and the method for getting full usage information will be displayed.

‘misuse-usage’

When an option error is made on the command line, the abbreviated usage text will be shown. misuse-usage and no-misuse-usage conflict and may not be used together.

misuse-usage and autoopts are the defaults. These defaults may be flipped to no-misuse-usage and gnu by specifying gnu-usage and no-misuse-usage program attributes, respectively, in the option definition file.

Note for developers:

The templates used to implement AutoOpts depend heavily upon token pasting. That mens that if you name an option, debug, for example, the generated header will expect to be able to emit #define macros such as this:

#define DESC(n) (autogenOptions.pOptDesc[INDEX_OPT_## n])

and expect DESC(DEBUG) to expand correctly into (autogenOptions.pOptDesc[INDEX_OPT_DEBUG]). If DEBUG is #defined to something else, then that something else will be in the above expansion.

If you discover you are having strange problems like this, you may wish to use some variation of the guard-option-names See section Program Description Attributes.

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