[m-rev.] for post-commit review: document the rest of the PROPOSED search options

[Zoltan Somogyi]

On Sat, 21 Dec 2024 16:17:13 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> > + at c @sp 1
> > + at c @item --c-include-dir-same-workspace @var{workspace_directory}
> > + at c @itemx --c-inc-dir-same-ws @var{workspace_directory}
> > + at c @sp 1
> > + at c @itemx --c-include-dir-independent-workspace @var{workspace_directory}
> > + at c @itemx --c-incl-dir-indep-ws @var{workspace_directory}
> > + at c @sp 1
> > + at c @itemx --c-include-dir-installed-library @var{install_directory}
> > + at c @itemx --c-incl-dir-installed-lib @var{install_directory}
> 
> For C header files specifically, there's an extra wrinkle. The existing
> --c-include-dir option is also (ab)used to get the Mercury compiler to
> tell the C compiler where to find header files for C libraries that are
> used by a Mercury program. I think we probably want to keep it around
> for that purpose, since:
> 
>    --c-include-dir /path/to/some/c/lib
> 
> is less cumbersome than:
> 
>    --c-flags "-I /path/to/some/c-lib"

OK. It would seem simplest to add, after the three options above,
a fourth, named --c-include-dir-X where X may be "external" or
"non-mercury" or something like that, to serve that purpose.
The directories named by that option would, or at least should,
contain only .h files, not .mh or .mih files, though we wouldn't want
to even try to enforce that.

Any preferences for what X should be?

> > + at c XXX Should we add something to specify that unlike the legacy options,
> > + at c the arguments of these options never require any directory name components
> > + at c that would be added by --use-subdirs/--use-grade-subdirs?
> 
> Would it suffice to say that if those options are used, then the
> directory specified
> by the option argument is the one containing the Mercury directory?

That's a good idea.

> The diff looks fine otherwise.

Thank you.

Zoltan.