for review: getopt.m documentation rot

[Andrew Bromage]

G'day all.

Would someone care to review this?  Thanks.

Cheers,
Andrew Bromage


Estimated hours taken: 1

Fix of documentation rot.

library/getopt.m:
	Describe the different kinds of options that we support.


Index: getopt.m
===================================================================
RCS file: /home/staff/zs/imp/mercury/library/getopt.m,v
retrieving revision 1.20
diff -u -t -u -r1.20 getopt.m
--- getopt.m	1998/01/23 12:33:17	1.20
+++ getopt.m	1998/09/16 00:51:39
@@ -24,17 +24,50 @@
 % (An option can have as many names as you like, long or short.)
 % You must provide a predicate `option_default(Option, OptionData)'
 % which specifies both the type and the default value for every option.
-% We support five different option types: bool, int, string, maybe_string
-% (which have either a value of `no' or `yes(string)'), and
-% "accumulating" (which accumulates a list of strings).
-% For the first four option types, if there are multiple occurrences
+% You may optionally provide a predicate `special_handler(Option,
+% SpecialData, OptionTable, MaybeOptionTable)' for handling special
+% option types.  (See below.)
+%
+% We support the following "simple" option types:
+%
+%       - bool
+%       - int
+%       - maybe_int (which have a value of `no' or `yes(int)')
+%       - string
+%       - maybe_string (which have a value of `no' or `yes(string)')
+%
+% We also support one "accumulating" option type:
+%
+%       - accumulating (which accumulates a list of strings)
+%
+% And the following "special" option types:
+%
+%       - special
+%       - bool_special
+%       - int_special
+%       - string_special
+%
+% For the "simple" option types, if there are multiple occurrences
 % of the same option on the command-line, then the last (right-most)
 % occurrence will take precedence.  For "accumulating" options,
 % multiple occurrences will be appended together into a list.
-% Single-character boolean or maybe-string options can be negated by
-% following them with another `-', e.g. `-x-' will negate the `-x' option.
-% Long boolean or maybe-string options can be negated by preceding them with
-% `--no-', e.g. `--no-foo' will negate the `--foo' option.
+%
+% The "special" option types are handled by a special option handler
+% (see `special_handler' below), which may perform arbitrary
+% modifications to the option_table.  For example, an option which
+% is not yet implemented could be handled by a special handler which
+% produces an error report, or an option which is a synonym for a
+% set of more "primitive" options could be handled by a special
+% handler which sets those "primitive" options.
+%
+% It is an error to use a "special" option for which there is no
+% handler, or for which the handler fails.
+%
+% Single-character boolean (i.e. bool or bool_special) or maybe_*
+% options can be negated by following them with another `-', e.g. `-x-'
+% will negate the `-x' option.  Long boolean or maybe_* options can be
+% negated by preceding them with `--no-', e.g. `--no-foo' will negate
+% the `--foo' option.
 
 :- module getopt.
 :- interface.