7.3.4.3 Special Option Handling

These option attributes do not fit well with other categories.

`no-preset'

If presetting this option is not allowed. (Thus, environment variables and values set in rc/ini files will be ignored.)

`settable'

If the option can be set outside of option processing. If this attribute is defined, special macros for setting this particular option will be inserted into the interface file. For example, TEMPL_DIRS is a settable option for AutoGen, so a macro named SET_OPT_TEMPL_DIRS(a) appears in the interface file. This attribute interacts with the documentation attribute.

`equivalence'

Generally, when several options are mutually exclusive and basically serve the purpose of selecting one of several processing modes, these options can be considered an equivalence class. Sometimes, it is just easier to deal with them as such.

For an option equivalence class, there is a single occurrence counter for all the members of the class. All members of the equivalence class must contain the same equivalenced-to option, including the equivalenced-to option itself. Thus, it must be a member.

As an example, cpio(1) has three options -o, -i, and -p that define the operational mode of the program (create, extract and pass-through, respectively). They form an equivalence class from which one and only one member must appear on the command line. If cpio were an AutoOpt-ed program, then each of these option definitions would contain:

equivalence = create;

and the program would be able to determine the operating mode with code that worked something like this:

switch (WHICH_IDX_CREATE) { case INDEX_OPT_CREATE: ... case INDEX_OPT_EXTRACT: ... case INDEX_OPT_PASS_THROUGH: ... default: /* cannot happen */ }

`documentation'

This attribute means the option exists for the purpose of separating option description text in the usage output. Libraries may choose to make it settable so that the library can determine which command line option is the first one that pertains to the library.

If present, this option disables all other attributes except settable, call_proc and flag_code. settable must be and is only specified if call_proc or flag_code has been specified. When present, the descrip attribute will be displayed only when the --help option has been specified. It will be displayed flush to the left hand margin and may consist of one or more lines of text. The name of the option will not be printed.

Documentation options are for clarifying the usage text and will not appear in generated man pages or in the generated invoking texinfo doc.