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

[Zoltan Somogyi]

On Thu, 19 Dec 2024 23:47:27 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> On Tue, 17 Dec 2024 at 14:33, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
> > @@ -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.

I didn't think so either.

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

I will go with interface, since that is the dominant use case.

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

Ok, I will provide at least these spellings of that last option:

--interface-dir-indep-ws
--interface-dir-independent-workspace

which abbreviate both components or spell out both components in full.

Should I also add the mixed abbrev/full versions below?

--interface-dir-indep-workspace
--interface-dir-independent-ws

My vote would be "no".

Should the order of the last two components be indep/ws or ws/indep?
I prefer the former, though only slightly.

And, given that each option now has at least two forms, is it still ok
to list all forms of each of the three options one after the other without
any separation, or should we put e.g. a blank line between the groups?
I lean towards the latter.

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

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

Will do.

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

Should this fully-spelt-out name of the option be followed here by
"(synonyms: <list them here>)"?

> > + 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;

> That looks fine otherwise.

Thank you.

Zoltan.