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

[Julien Fischer]

Hi Zoltan

On Thu, 17 Jul 2025 at 01:08, Zoltan Somogyi <zoltan.somogyi at runbox.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.

...

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

...

> 3 Grades
>
>     A new section, using the old help text for the --grade option
>     as a source of text to reuse, but crucially adding a description of
>     which grade modifiers are compatible (using grade_lib/grade_structure.m)
>
>     This section would NOT document any of the grade components that are
>     not ready for prime time (e.g. rbmm), are unmaintained (such as
>     threadscope) or which are effectively unusable (such as llds grades
>     without boehm).
>
>     XXX should we document mercury_file?

You mean the alternative file representation for the C grades?  Is it worth
keeping? It's been there for 25 years at this point and never enabled by
default.

Julien.