[m-rev.] for post-commit review: start documenting PROPOSED search options

[Julien Fischer]

On Tue, 17 Dec 2024 at 14:33, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Start documenting PROPOSED file search options.
>
> doc/user_guide.texi:
>     Add a (commented-out for now) description of one set of three options
>     for directing searches for interface files.
>
>     Fix the documentation of --search-directory and --intermod-directory,
>     and add a comment.
>
> compiler/options.m:
>     Fix the documentation of --search-directory and --intermod-directory
>     the same way.
>
> diff --git a/compiler/options.m b/compiler/options.m
> index 384a08e78..e26ca1ab5 100644
> --- a/compiler/options.m
> +++ b/compiler/options.m
> @@ -7067,11 +7067,11 @@ options_help_build_system(Stream, !IO) :-
>          "\t`--no-mercury-stdlib-dir' is passed to mmc.",
>          "\tThe configuration file is just an options file.",
>          "-I <dir>, --search-directory <dir>",
> -        "\tAppend <dir> to the list of directories to be searched for",
> -        "\timported modules.",
> +        "\tAppend <dir> to the list of directories to be searched",
> +        "\tfor `.int*' and `.module_dep' files.",
>          "--intermod-directory <dir>",
> -        "\tAdd <dir> to the list of directories to be",
> -        "\tsearched for `.opt' files.",
> +        "\tAdd <dir> to the list of directories to be searched",
> +        "\tfor `.opt' and `.trans_opt' files.",
>          "--no-use-search-directories-for-intermod",
>          "\tDo not add the arguments of `--search-directory' options to",
>          "\tthe list of directories to search for `.opt' files; use only the",
> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
> index b088cb082..ed6f8b5f5 100644
> --- a/doc/user_guide.texi
> +++ b/doc/user_guide.texi
> @@ -10619,16 +10619,56 @@ Search @var{dir} for Mercury system's configuration files.
>  @findex --search-directory
>  @cindex Directories
>  @cindex Search path
> -Append @var{dir} to the list of directories
> -to be searched for imported modules.
> +Append @var{dir} to the list of directories to be searched
> +for @samp{.int*} and @samp{.module_dep} files.
> + at c XXX Should we list .int0, .int, .int2 and .int3 separately?

I don't think that is necessary.

> + at c @c XXX The "normal" part of the names of these options
> + at c @c was just a placeholder, since one was needed to differentiate
> + at c @c these options from their intermod, c-include-file and .a/.so versions.
> + at c @c Its use does not lead to good option names, but it is difficult
> + at c @c to come up with better option names. Any ideas?

  --module-dirs-same
  --module-dirs-indep
  ...

or

  --interface-dirs-same (--int-dirs-same, for short)
  --interface-dirs-indep
  ... etc.

(Ok, .module_dep files are not interface files, but it if you squint hard
enough I think it works.)

> + at c @c
> + at c @c XXX Once there is agreement on the structure of this entry, it will be
> + at c @c duplicated, mutatis mutandis, for the other three groups of PROPOSED
> + at c @c search dir options.
> + at c @sp 1
> + at c @item --normal-dirs-same @var{workspacedir}
> + at c @itemx --normal-dirs-indep @var{workspacedir}

I think these two should include "workspace" in their names.
Yes, it's longer but it is also clearer.

> + at c @itemx --normal-dirs-installed-lib @var{installdir}
> + at c @findex --normal-dirs-same
> + at c @findex --normal-dirs-indep
> + at c @findex --normal-dirs-installed-lib

I think it should be "dir" (singular). The argument of the option is the named
workspace or named library install directory and there is only one of them.

Also, while abbreviating components of the names is fine, can we please provide
non-abbreviated versions (however long they may be). Trying to guess what
abbreviations might be used in an option name is annoying.

> + at c @cindex Directories
> + at c @cindex Search path
> + at c Append either the named workspace directory,
> + at c or the named library install directory,
> + at c to one of three separate lists of directories to be searched
> + at c for @samp{.int*} and @samp{.module_dep} files.
> + at c Any workspace directory
> + at c named in a @var{--normal-dirs-same} option
> + at c should set the same values
> + at c for the @samp{--use-subdir} and @samp{--use-grade-subdir}
> + at c as the current workspace directory;
> + at c this restriction does not apply to workspace directories
> + at c named in a @var{--normal-dirs-indep} options.
> + at c The compiler will first search the workspace directories
> + at c named in @var{--normal-dirs-same} options,
> + at c second it will search the workspace directories
> + at c named in @var{--normal-dirs-indep} options,
> + at c and third it will search the library install directories
> + at c named in @var{--normal-dirs-installed-lib} options.

That looks fine otherwise.

Julien.