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

[Zoltan Somogyi]

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.

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.

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.

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.

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

1B, 2B and 3B are the same as the corresponding A variants,
except you never install any libraries; you only look at the set of grades
with --output-libgrades. Of these, only 3B makes sense: it reports
the set of grades the Mercury standard library is installed in.
(This is what my rewritten documentation, to which you objected, says.)
1B and 2B don't really make sense, because the only difference between
their output and the output of 3B is simply and directly determined
by options the user specifies him/herself, but those options
(in the B use cases) have no other uses.

At the moment, --output-libgrades has two separate semantics,
in in the 1A/2A/3A use case, and one in the 3B use case.
The obvious solution to me is to have two separate options,
one for each use case.

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

Zoltan.