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

[Zoltan Somogyi]

On Fri, 14 Jan 2022 23:34:14 +1100 (AEDT), Julien Fischer <jfischer at opturion.com> wrote:
> > Agreed about what happens in the presence of user-supplied --libgrade=...
> > and --no-libgrade options. Question is: are there any use cases in which
> > non-developers would ever need, or even want, to use those options?
> > I don't know of any, and would therefore be happy if the --libgrade option
> > was deleted (see below), though we may need a replacement for
> > --no-libgrade.
> 
> Please don't do anything to either of those options;

Since you asked, I won't, though that is just one option, not two :-)

I will fix the doc of --output-libgrade.

> I just had a grep
> through the G12 source code which is using them all over the place.

Using them for what purpose, if I may ask?

> > That relationship tells me that those two pieces of code definitely belong
> > in the same module; at the very least, in the absence of user-provided
> > --libgrade options, we could avoid having detect_libgrades compute a set,
> > and then having check_libgrades run the *same algorithm as detect_libgrades*
> > before testing if they get the same output.
> 
> I imagine there is a fair amount of overlap between the two;

> obviously
> check_libgrades it not restricted to just the standard library, it also
> checks that any user-specified libraries are present in the required
> grades.

I wasn't talking about that part.

> The rationale for this was to support (or at least simplify) finer
> grained packaging of Mercury (e.g. one .deb or .rpm for the base system,
> another for the debug grades, another for the profiling grades etc) and
> also to allow installation of additional library grade from source after
> the initial installation has been completed.  (I think there were some
> additional changes to the configure script to support that last use case,
> that never made it in for one reason or another.)

While the above is a useful goal, I would point out that it is also sort-of
dangerous, unless accompanied by *some* mechanism for ensuring
that the newly installed library files are compatible with the existing ones.
If e.g. the old one has module_a.p/3, but the new one has module_a.p/4,
and neither has the one in the other, then recompiling a user program
after switching grade may yield an unexpected error.

Zoltan.