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

[Julien Fischer]

On Sat, 30 Aug 2025 at 20:47, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
>
> 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?

I think it would be fine to omit the reason.

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

I don't think we will be doing that without a fairly major redesign and rewrite
of closure analysis.

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

"report" gives the impression that it prints out a message
telling the user about what a predicate does with the trail.

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

I prefer the word I used, "determine".

Julien.