[m-rev.] for post-commit review: finish the intermodule opt section in the user guide

[Zoltan Somogyi]

On Sat, 30 Aug 2025 14:55:28 +1000, Julien Fischer <jfischer at opturion.com> wrote:

> On Sat, 30 Aug 2025 at 03:27, Zoltan Somogyi <zoltan.somogyi at runbox.com>
> wrote:
> 
> > diff --git a/doc/mercury_user_guide.texi b/doc/mercury_user_guide.texi
> > index 79d268e94..0b7f1d8a8 100644
> > --- a/doc/mercury_user_guide.texi
> > +++ b/doc/mercury_user_guide.texi
> > @@ -2330,20 +2334,96 @@ Mercury's first step
> >  towards avoiding circular dependencies between @file{.trans_opt} files
> >  is to impose an order on the modules of the program
> >  when the @command{mmc --generate-dependencies} command is executed for
> it.
> > -This order is recorded in the @file{.dv}
> > -The second step is to ensure that
> > -a @file{.trans_opt} file can only ever depend on
> > - at file{.trans_opt} files that @emph{follow} it in the order,
> > -never ones that @emph{precede} it.
> > +(One reason, though not the only one,
> > +why @command{mmc --make} does not support @file{.trans_opt} files is that
> > +it neither has nor needs a @command{mmc --generate-dependencies} step.)
> 
> That doesn't seem a very strong reason, presuambly *if* mmc --make were
> modified to support transitive intermodule-optimization, we would modify
> its internal dependency mechanism to account for that?

No, it is not a strong reason, but we do not have a strong reason available.
Our only choices we have are (a) give readers a weak reason, or (b) give readers
no reason at all. Which would you prefer?


> > +Beside @option{--analyse-exceptions},
> > +the following options also record their results in @file{.trans_opt}
> files.
> > + at itemize @option
> > + at c @item @option{--analyse-closures}, and
> 
> The analysis carried out by --analyse-closures is within a module only.
> Its results are not placed in .opt or .trans_opt files.

I added a note about --analyse-closures being probably modified
to put its results in .trans_opt files, when we start using it.

> > + at item --enable-termination
> > +This option turns on Mercury's first termination analyser,
> > +which uses linear inequalities.
> > + at item --enable-termination2
> > +This option turns on Mercury's second termination analyser,
> > +which uses convex constraints.
> > + at item --analyse-trail-usage and
> > +This option turns on an analysis
> > +that reports which predicates and functions
> 
> What do you mean by "reports"? The analysis determines which
> predicates and functions do not touch the trail, but it doesn't
> report them, except to the rest of the compiler.

"report to the rest of the compiler" is exactly what I meant.
I though this would be clear from the rest of the sentence,
which is:

> > +definitely do not touch the trail,
> > +enabling the compiler to reduce the overhead of trailing.

What other word would be clearer to you?

I don't think "records" works in this case, since "recording"
does not sound like it enables anything.

"Finds out" may work, but does not sound right to me.

"Computes" may work, but then everything the compiler does
is computation ...

Which, if any, of these alternatives do you prefer?

> > +(That performance problem @emph{may} be non-termination,
> > +but the analyser's inability to prove termination
> > +may also be caused by less drastic performance problems.)
> 
> I suggest: s/caused by/indicative of/

I went with "may indicate".

I followed the rest of your suggestions.

Zoltan.