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

[Zoltan Somogyi]

On Sun, 25 May 2025 14:50:29 +1000, Julien Fischer <jfischer at opturion.com> wrote:

> > +%---------------------------------------------------------------------------%
> > +%
> > +% 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?

No, it doesn't. Those two are alternatives, and I don't know whether
reflow is required.

> > +% - 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 is the order of output. I added that comment.
 
> 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.

Done, though "help" is the only option with more than one short name.
(The set of chars available as short names is limited, after all.)

> > +
> > +                % 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.)

Yes, we could. I will modify the print code to take a flag controlling whether
we print private options.

> > +
> > +                % 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).

Agreed, but I am pretty sure that it would be overkill for the vast majority
of options. And for the ones for which it would not be overkill, it will take
conversion to *this* form to discover what extra structure *would* be useful.

> That's fine otherwise.

Thanks. I followed your other suggestions.

Zoltan.