[m-rev.] for review: combine ml and c2init options

[Fergus Henderson]

On 30-Nov-2001, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:
> 
> Combine the options for ml and c2init. Once mmake has been
> altered to pass MLFLAGS to c2init users will be able to
> mostly ignore the existence of c2init.
> 
> diff -N scripts/parse_ml_options.sh-subr.in
...
> +Diagnostics options:
> +	-v, --verbose
> +		Echo the gcc command line before executing it.

It might be a good idea to change that to

		Print each command before executing it.

and modifying c2init to support this option
(i.e. printing the `mkinit' command).

> +	-i, --include-initialization-code
> +		Always include code that calls the initialization functions
> +		of the various modules. With this option, the debugger can use
> +		information from any modules that were compiled with execution
> +		tracing to print (partial) stack traces, and to print the
> +		values of variables in ancestors of the current call, even
> +		in grades in which this not normally possible.

IMHO this one should go in the "Debugging options" section,
rather than the "Initialization options" section,
since the fact that it happens to work via the initialization
function is an implementation detail, from the user's perspective
the more important factor is the option's effect on debugging.

In fact this option is rarely useful, and might not be worth documenting.
If it is worth documenting, then IMHO the documentation ought to explain
why one might want to use this option rather than `--trace'.
Personally I never use this option and I'd vote for not documenting it.

> +
> +	Environment variables:
> +		MERCURY_MOD_LIB_DIR, MERCURY_MOD_LIB_MODS,
> +		MERCURY_TRACE_LIB_DIR, MERCURY_TRACE_LIB_MODS,
> +		MERCURY_MKINIT.
> +
> +Threads options:
> +	--use-thread-libs
> +		Link with the POSIX thread libraries. This option is useful
> +		if a C library being linked with uses threads, but the
> +		Mercury code being linked doesn't.

The environment variables should be listed after all the options
(and "Environment variables:" should not be indented).


I also have a couple of suggestions about things that were
just moved around, not modified, in this change:

> +Initialization options:
> +	-a, --aditi
> +		Generate a function to upload Aditi-RL data to a database.

That description is a bit cryptic.  I suggest appending the following:

		This option is needed when interfacing with the Aditi
		deductive database system.

> +	-c <n>, --max-calls <n>
> +		Break up the initialization into groups of at most <n> function
> +		calls.  (Default value of <n> is 40.)

This one is probably not useful enough to be worth officially documenting.
I suggest commenting out the documentation for this option.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------