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

[Julien Fischer]

On Sat, 30 Aug 2025 at 22:27, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

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

....

> > > > > +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.
>
> OK, I will delete even the comment. But if you know what redesign
> would be needed for this, it would be nice if you described it in the
> module comment of closure_analysis.m. The two kinds of comments
> I have always wished for, when missing, were
>
> - comments that describe an approach that looks like it would work
>   and improve things, but cannot be adopted due to an Achilles heel
>   (which would have been nice to know about before I designed and
>   implemented that approached, and THEN discovered that heel), and
>
> - comments that describe a design that would improve on the current
>   approach (so I would have to reinvent it from scratch).
>
> These are the comments that take a few minutes to write when the
> details are fresh in your mind, but save hours or days, either for
> someone else, or your future self.

I'll see if I can add something.  Having just refreshed my memory about
the details of closure analysis, the issue of tracking higher-order
values across
module boundaries is quite a different problem.

> > > > 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".
>
> "Determines" implies "controls", which in this case is a false
> implication. That's why I am pretty sure it is not appropriate
> in these cases.

"identifies"?

Julien.