[m-rev.] for review: structured representation of option documentation

[Julien Fischer]

On Fri, 23 May 2025 at 23:22, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> I am proposing that we switch from our current stringly-typed
> representation of option help text to a strongly-typed representation :-)
> The attached diff shows the general form of I am proposing for that
> representation. If people agree that this is a good idea, then I will
> convert the documentation of all the other options as well.

> Prototype a better way to store option documentation.
>
> compiler/options.m:
>     Implement a more structured representation of option documentation,
>     and use it one case.

... use it *in* one case.

I don't have any objections to this change, since it is an improvement on the
status quo. Ideally, we would have a mechanism for doing this as part of
getopt.m, but coming up with a sufficiently generic design for that kind of
thing is tough.

> diff --git a/compiler/options.m b/compiler/options.m
> index 234b29dab..b1a64c67b 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m
> @@ -4450,8 +4450,9 @@ handle_quoted_flag(Option, Flag, !OptionTable) :-
>  %---------------------------------------------------------------------------%
>
>  options_help(Stream, !IO) :-
> -    io.write_string(Stream, "\t-?, -h, --help\n", !IO),
> -    io.write_string(Stream, "\t\tPrint this usage message.\n", !IO),
> +    OptHelpHelp = gen_help("help", [], ['?', 'h'], no_arg, help_public,
> +        ["Print this usage message."]),
> +    output_help_messages(Stream, [OptHelpHelp], !IO),
>      options_help_warning(Stream, !IO),
>      options_help_verbosity(Stream, !IO),
>      options_help_output(Stream, !IO),
> @@ -7252,6 +7253,129 @@ options_help_misc(Stream, !IO) :-
>          "\tonly be processed for implicit parallelism."
>      ], !IO).
>
> +%---------------------------------------------------------------------------%
> +%
> +% XXX The code from here to the end of the file should be in another file,
> +% since options.m is big enough already :-(.
> +%
> +% This structured representation improves on our traditional approach
> +% of storing just lists of lines in the following ways.
> +%
> +% - It does not force us to start every line documenting an option
> +%   with "\tactual help text".
> +%
> +% - It does not require global changes to change indentation levels.
> +%
> +% - It allows an optional check, probably inside a trace scope, that tests
> +%   each first and each later line whether they fit on a standard
> +%   80 column line, and adds an easily greppable marker if any
> +%   exceeds that limit.

Does that matter if we are reflowing the lines wrt to a line width parameter
anyway, as per the next point?

> +% - It allows taking a line width parameter, and reflowing the later lines
> +%   to respect that limit.
> +%
> +% - It allows adding a version of output_help_messages that outputs
> +%   the help message not to be read by a compiler user, but with
> +%   texinfo markup, intended to be copy-and-pasted into doc/user_guide.texi.
> +%
> +
> +:- type help
> +    --->    gen_help(
> +                % The name of the option.
> +                gh_long_name            :: string,
> +
> +                % Any alternate names of the option.
> +                % We have many options that have both British and American
> +                % spelling of the option name, and some have both
> +                % short and long versions.
> +                gh_alt_long_names       :: list(string),

Is the order of this list significant? Is the order intended to be reflected
in the order of the output. If so, I suggest adding a comment saying so.

It may be useful to capture whether the option is negated by default here or
not. That way the addition of the "--no-" prefix can be handled automatically.

> +
> +                % Every character in this field is a short name of the option.
> +                gh_short_names          :: list(char),

Ditto about order here.

> +
> +                % If the option takes an argument, then this should contain
> +                % the name of the placeholder for that argument.
> +                gh_maybe_arg            :: maybe_opt_arg,
> +
> +                % Is the option's documentation printed for users, or not?
> +                gh_public_or_private    :: help_public_or_private,

Presumably, we could support something like --developer-help, which will
include the undocumented options in the usage message. (That would be useful as
I often find myself having to go and consult options.m for details about them.)

> +
> +                % The lines describing the effect of the option.
> +                gh_description          :: list(string)

In the longer term, we should consider moving to a more structure markup of the
description (something like what error_util does for error/warning messages).

That's fine otherwise.

Julien.