[m-rev.] for post-commit review: fill in much of the "compilation in detail" chapter

[Julien Fischer]

On Tue, 19 Aug 2025 at 02:38, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> On Sun, 17 Aug 2025 02:03:44 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > The rest looks fine.
>
> Thanks for the review. The attached diff addresses
> all your concerns, and goes further in describing trans_opt.


> diff --git a/doc/mercury_user_guide.texi b/doc/mercury_user_guide.texi
> index d94b414ce..0f8953138 100644
> --- a/doc/mercury_user_guide.texi
> +++ b/doc/mercury_user_guide.texi
> @@ -216,7 +216,7 @@ In the absence of the @code{--make} option,
>  whose description we will defer until @ref{Introduction to mmc --make},
>  all non-option arguments should be either
>  the name of a file, or the name of a module.
> - at c XXX what about e.g. "mmc --make prog.clean"?
> + at c XXX Should we talk about about e.g. "mmc --make prog.clean" here?

You can delete that XXX comment. To me, the sentence immediately before
is enough explanation of why we don't talk about --make prog.clean here.

>  The compiler assumes that
>  non-option arguments ending in @samp{.m} are file names,
>  while all other non-option arguments are module names.
> @@ -226,12 +226,13 @@ what code it should operate on.
>  @node Option arguments
>  @subsection Option arguments
>
> -The Mercury compiler follows the usual Unix conventions around options.
> +The Mercury compiler follows the usual GNU conventions around options,
> +which are themselves based on Unix conventions.
>  (Some of its options (e.g.@: @samp{-c}, @samp{-o}, and @samp{-I})
>  have a similar meaning to that in compilers for other languages,
>  though of course most are specific to Mercury.)
>
> -Like most other Unix programs, it supports both
> +Like most other GNU programs, it supports both

That gives the impression that Mercury is a GNU program. I would just
say "Like many programs". The existing reference to Unix was fine as well.

>  short (single-character) and long (multi-character) option names.
>
>  On command lines, an option argument that starts with @samp{--}
> @@ -1971,7 +1976,7 @@ for these target languages.)
>
>  If the source file contains nested modules,
>  then both the main module in the file,
> -and all the submodules nested inside it, directly or indirect,
> +and all the submodules nested inside it, directly or indirectly,
>  will all get compiled
>  first to separate @file{.c} (or @file{.java}, or @file{.cs} files,
>  and then to separate @file{.o} (or @file{.class}, or @file{.dll} files.

...

> @@ -2224,12 +2219,14 @@ whose results they contain.
>  One of these analyses is exception analysis,
>  which computes safe approximations to the set of exceptions
>  that each predicate or function can possibly throw.
> -If this approximations is the empty set,
> +These approximations do not refer to the identities of specific exceptions,
> +but they are nevertheless useful,
> +becayse if this approximation is the empty set,

s/becayse/because/

That looks fine otherwise.

Julien.