[m-rev.] for post-commit review: explain grades more deeply

[Zoltan Somogyi]

2020-05-04 13:43 GMT+10:00 Julien Fischer<jfischer at opturion.com>:
> Do you want me to commit these changes?

I thought you already had.

Some parts I agree with, some parts I don't.

>> I agree, the description of the grade system should be in its own
>> section.  Given the level of confusion that they seem to cause, maybe
>> it should be its own chapter instead?

For a chapter, I think we would need a complete description
of which grade modifiers are compatible with which base grades
and *other* modifiers. For that, I would prefer to wait until
we switch to using the grade library, since its structured grade
representation is I think the only way we can *enforce* whatever
rules the documentation says.

>> diff --git a/doc/user_guide.texi b/doc/user_guide.texi
>> index 288fabd..ea19b4a 100644
>> --- a/doc/user_guide.texi
>> +++ b/doc/user_guide.texi
>> @@  -7933,9 +7933,9 @@ and each following element (if any) is a @samp{grade > @@  modifier}.
>>
>>  The base grade specifies
>>  what target language to compile the Mercury program to,
>> -and if that the compiler can do this in several different ways,
>> +and if the compiler can do this in several different ways,
>> selects one of those ways.

That's fine.

>> -The available base grades are the following.
>> +The available base grades are:

I think your wording, which is also the old wording, works *only*
if what follows are part of the same sentence. I added "the following"
because each point is now a complete sentence.

>> @ item @samp{hlc}
>> This base grade calls for generating idiomatic C,
>> -which we call high level C.
>> +which we call high-level C.

As is clear by my use of high level C, I prefer not to use the dashed version.

>> @ samp{none} calls for generating standard C without using any GNU C > @ extensions.
>> @ samp{reg} and @samp{asm_fast} both call for
>>  the use of GNU C's extension for storing global variables in registers,
>> @@  -7966,7 +7966,7 @@ while @samp{asm_fast} also calls for the use of two > @@  GNU C extensions
>>  that together allow direct gotos to labels in other functions,
>>  even in other modules.
>>  In general, the more GNU C extensions are used,
>> -the faster the programmer will be,
>> +the faster the program will be,
>>  but some platforms, compilers or compiler versions
>>  do not support specific extensions.

s/programmer/program/ is clearly an improvement.

>> @ item garbage collection
>>  The default is no garbage collection beyond what the target language
>>  provides.
>>  C#, Java and Erlang have their own builtin garbage collectors, but C does
>>  not.
>> -Since gc is essential for all programs
>> +Since garbage collection is essential for all programs
>>  other than those with @emph{very} short runtimes,

Since we are inside an item named "garbage collection", anyone who
doesn't know what "gc" is can figure it out from context. But spelling it out
doesn't hurt.

>> +By default when targeting C, the Mercury @samp{float} type is implemented as > an
>> +IEEE 754 double-precision floating point number, which occupies 64 bits of
>> +space.

Two things wrong here. First it restricts the following discussion to C, but then
says nothing about the other target languages. Second, we have no control over
whether Mercury floats are IEEE 754 or not. They will be, on most kinds of platforms,
but there are still machines out there with non-754 float architectures.

>> @ item stack size
>> -When generating assembly-like C code,
>> +When generating low-level C,

Each of these are ok.

>> @@  -8076,37 +8072,37 @@ small memory segments chained together in a list.
>>  When there is no room in the current segment for a new stack frame,
>>  we simply allocate a new segment and add it to the list.
>>  This approach has higher overhead,
>> -since calls to and returns from procedures we must execute more code,
>> +since calls to, and returns from, procedures must execute more code,

In this case, I would prefer a third wording, such as

we must execute more code both at calls to procedures,
and at returns from them.


>> -The price of this is that @samp{.decldebug} will result
>> +The price of this is that @samp{.decldebug} results
>>  in significantly larger executable files.

Both are ok.

>> -The default is whatever thread support is given by the target language.
>> +The default is whatever thread support is provided by the target language.

That's an improvement.

>> -thread support can be enabled by specifying the grade modifier @samp{.par}.
>> -When targeting low level C,
>> +thread support must be enabled by specifying the grade modifier @samp{.par}.
>> +When targeting low-level C,

Your wording implies that non-par grades are not allowed, which is wrong.

Zoltan.