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

[Zoltan Somogyi]

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

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

Ok, I will delete it.

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

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

Zoltan.