[m-rev.] for post-commit review: improve documentation of query options

[Julien Fischer]

Hi Zoltan,

On Sat, 15 Jan 2022, Zoltan Somogyi wrote:

> On Sat, 15 Jan 2022 16:56:09 +1100 (AEDT), Julien Fischer <jfischer at opturion.com> wrote:
>> Is egrep broken on your system? ;-)  It told me exactly what
>> code is doing that:
>>
>> make.program_target.m: globals.lookup_accumulating_option(Globals, libgrades, LibGrades0),
>
> OK. I missed that, because I was looking for things that are in control
> of what grades *the Mercury standard library* is installed in, which
> make.program_target.m does *not* do.

The grades in which the standard library is installed are controlled
exclusively by Mercury's configuration system and mmake. That whole
setup is something of an outlier as far as normal users of Mercury
are (or indeed should be) concerned.

> With those answers, I think I have a good enough understanding
> of this use case, but let me check whether I have the right overall
> picture. At the moment, I see these possible use cases of --libgrades.
>
> 1A: a --no-libgrades option followed by several --libgrade=<grade> options,
> to control in what grades make.program_target will install a specified user library.
> This is the use case of g12.

Correct.

> 2A: the same as 1A, except without an initial --no-libgrades, which means that
> the grades added by user-specified --libgrade=... options get added to the
> set of grades in which the Mercury standard library is installed.

Yes, although that not a very useful thing to do.

> 3A: the same as 2A, except without any user-specified --libgrade=... options.
> Any library installed by make.program_target.m will be installed in the
> same set of grades in which the Mercury standard library is installed.

Yes.

> With all of 1A, 2A and 3A, the --output-libgrades option will tell you
> the set of grades in which make.program_target.m will install a library.
> (This is what the original documentation of that option was trying to say.)

Yes.  Bear in mind there are more options that affect the set of grades
in which make.program_target.m will install a library, e.g.
--libgrade-exclude-component. One reasonn that --output-libgrades exists
is to answer the question: given a Mercury installation and a set of
command line options, what grades will this library be installed in?

...

> --output-libgrades should do what it does now, and have (some variant of)
> its old documentation. Its output will be controlled by --libgrade=...
> and --no-libgrade options, exactly as now, including the initial set
> specified by detect_libgrades.
>
> --output-stdlib-grades, or some variant of that name, should print
> the set of installed stdlib grades. Its output should be controlled
> *only* by the grades returned by detect_libgrades; it should not be
> affected by user-given --libgrade options.
>
> I think in one of your earlier emails you proposed something very similar.
> Did I understand you correctly?

Yes, the above was what I was proposing.

Julien.