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

[Zoltan Somogyi]

On Fri, 20 Dec 2024 08:56:29 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> On Fri, 20 Dec 2024 at 01:41, Zoltan Somogyi <zoltan.somogyi at runbox.com>
> wrote:
> > > + 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>)"?
> >
> 
> The synonyms should be listed above anyway, so I don't think you need
> to repeat them inline.

My reason for proposing that addition was not to introduce the synonyms,
but to clarify that the appearance of those options above *are* synonyms,
as opposed to semantically separate options. I am not sure about whether
just putting a blank line between the groups-of-synonyms would be sufficient
to get that point across. Or I could just add a remark of the form
"(and its abbreviated synonym)" after text that includes the full form
of the option name.

Thanks for the review. I will follow your other suggestions.

Zoltan.