[m-dev.] proposal for a new structure for the inital chapters of the user guide

[Zoltan Somogyi]

On Thu, 17 Jul 2025 01:20:19 +1000, Julien Fischer <jfischer at opturion.com> wrote:
> > I would like your feedback on the following proposed new structure
> > for the initial chapters of the user guide.
> 
> The proposed structure seems fine to me.

Thanks.

> > 2 Introduction to compiling Mercury programs
> >
> >     2.1 single module programs
> >
> >         discusses just "mmc x.m", and storing module A in A.m.
> 
> Unrelated: should we enable --use-subdirs by default for compilation
> of single module
> programs?  (This occurred to me when I was reviewing one of you previous changes
> and this just reminded me.)

Can we actually do so in a non-confusing manner? The reason I ask is that
when given "mmc x.m", we don't know in advance whether this is

- the compilation of a single-module program, or
- the compilation of one module of a multi-module program that is missing a -c,
  or the specification of some libraries to link against, or something similar.

We don't know which is the case until the linker exits, by which time
we have already put the .c and .o files (when targeting C) *somewhere*.

We *could* assume that a single source file arg means a single-module program,
and enable --use-subdirs on that basis, but having a missing -c lead to 
the sudden appearance of a Mercury subdir would be confusing, I think.

> >     XXX should we document mercury_file?
> 
> You mean the alternative file representation for the C grades? 

Yes.

> Is it worth
> keeping? It's been there for 25 years at this point and never enabled by
> default.

That question is precisely what I am seeking feedback on.
I have looked at it long ago, but never used it in anger, so to speak,
so I have no first-hand knowledge of its general usefulness.
I'll mark you down as a "no" on that score.

Anyway, I intend to initially document only what I know is useful;
we can always document more grade components later.

Zoltan.