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

[Julien Fischer]

On Thu, 17 Jul 2025 at 01:49, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:
>
> On Thu, 17 Jul 2025 01:20:19 +1000, Julien Fischer <jfischer at opturion.com> wrote:

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

If you try to compile a multi-module program using mmc x.m you will get
an error about missing interface files, it never gets anywhere near the linker.

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

The argument for this is that beginner users are more likely to be
using single-module
compilation and not having the compiler spew generated files
all over the current working directory is probably less confusing than any
sudden manifestations of Mercury subdirs.   (I would imagine this class of
users are *not* using the -c option.)

> > >     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 have never used it. I did once ask the people who added it to benchmark
it against the standard file definition and then either enable or delete it, but
that never happened.

Julien.