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

[Zoltan Somogyi]

I would like your feedback on the following proposed new structure
for the initial chapters of the user guide.

Zoltan.

------------------------------------------

1 Introduction

    Keep this unchanged.

2 Introduction to compiling Mercury programs

    2.1 single module programs

        discusses just "mmc x.m", and storing module A in A.m.

    2.2: multi-module programs

        describe mmc -f here

        2.2.1: mmc --make *.m

        2.2.2: mmake mainmodule.depend; mmake mainmodule

    2.3: running Mercury programs

    The current contents of section 4, plus the info about .exe and .bat
    files, and runtime flags such as --java-runtime-flags and 
    --java-classpath, from the current section 3.

    This section would STOP here, leaving out the last two-thirds or so
    of the current section 3. This material would be moved later, to the
    new section 4.

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?

4 The compilation pocess in detail

    The last two-thirds of the old section 3:
    explaining each step of the compilation process,
    including building .int* files, .*opt files, .init files,
    and using mgnuc/ml

    keep the warning from the old section 3 about this stuff being skippable

5 File naming conventions

    The current section 2, but add description of
    more kinds of files, including .err

6 Using mmc --make

    A short new section, explaining "mmc x.ext" for each extension
    in the file naming convention section

7 Using mmake

    From here to the end, I am proposing no changes.