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

[Zoltan Somogyi]

On Sun, 25 May 2025 14:58:22 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> Another thought on this ...
> 
> On Fri, 23 May 2025 at 23:22, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
> 
> > diff --git a/compiler/options.m b/compiler/options.m
> > index 234b29dab..b1a64c67b 100644
> > --- a/compiler/options.m
> > +++ b/compiler/options.m
> 
> ...
> 
> > +:- type help
> > +    --->    gen_help(
> 
> 
> This type should contain a field that gives a link (e.g. a field gh_option) to
> the relevant member of the option/0 type. That way the usage message processor
> could look up details of the option, like its default value, using the usual
> predicates.

I don't think that lookup would be worthwhile. It would help with the trivial part
of writing the message (converting --long-name to --no-long-name), but not
with the harder part, which is writing the main description in the negative
instead of the positive form. In many cases, the difference will be just
"disable" vs "enable", but in other cases, the change would be different,
and I don't think it can be usefully automated.

> (Doing this will also make it more likely that the documentation
> is updated if the option is changed or deleted.)

Agreed. That link from the help structure to the option/0 value being documented
would be most useful if we could use it to guarantee that all options
are documented. That would mean using a complete switch on option/0,
effectively mapping each option to its help structure.

The simplest and most direct way to print help structures in such a map
is to convert the map (which you can get with solutions) into an assoc list
sorted on the option. That would require that the function symbols in the option type
be listed in the order in which we want their help texts to appear.
That is what we should move towards, but we are not there yet.

> (Doing this will also make it more likely that the documentation
> is updated if the option is changed or deleted.)

Yes. But if you want to increase that likelyhood to the maximum,
you need to move the help structure either next to, or *into*,
the optdef clause.

The former would require disabling the option that prevents clauses
of different predicates being interleaved. Ideally, it would be disabled
only for these two predicates. We don't currently have a way to do that.
though it wouldn't be too hard to add that capability. Possibly
a new option, --allow-interleaved-clauses="pred1,pred2,pred3,..."?

The latter has the problem that an option which has N names
has N optdef clauses, not one. We could partly solve that by making the
help structure for each alternate name be a value that says "there is no
help structure here; get it from the main name xyz". We could even
dispense with the alt names field, and instead get the same info from
the set of these "pointers". (Though this *would* require automating
the addition of "no-" prefixes on negatable option names, since
the opt_def clauses *never* have those prefixes.)

We could add an int field to the pointers themselves
indicating the order in which they should be listed in the help text,
since lexicographic order may not always be the one we want.

Overall, interleaved clauses seems simpler, and just as good.

I don't intend to implement any of these refinements initially.
Moving to use just the structure in the initial diff will tell us which of
these refinements are actually useful, and we can implement them
in lowest to highest hanging fruit order.

Zoltan.