[m-dev.] for review: improve debugger documentation

[Zoltan Somogyi]

> +To use the debugger, you must
> +first compile your program with debugging enabled.
> +You can do this by using the @samp{--debug} option to @samp{mdb},
> +or by including @samp{GRADEFLAGS = --debug} in your @file{Mmakefile}.

mdb does not have a --debug option; you want mmc, not mdb.

> +The debugger will print a start-up message
> +and will then show you the first trace event,
> +namely the call to @code{main/2}:
> +
> + at example
> +       1:      1  1 CALL pred hello:main/2-0 (det)
> +                         hello.m:13
> +mdb>
> + at end example

This is the format that you would get if "context nextline" were the default,
but it isn't; at the moment it is "context after". Given that this often causes
lines to wrap around, maybe we should change the default.

> +information.  The three numbers at the start of the display are the
> +event number, the sequence number, and the call depth. 

You probably want to say "the *call* sequence number", or just "the call
number".

> +After that comes the module name (@samp{io}),
> +procedure name (@samp{write_string}), arity (@samp{3}),
> +mode number (@samp{0}), and determinism (@samp{det}).

Instead of this, say "after that comes the identification of the procedure
in which the event occurs, consisting of the name of the predicate or function
to which the procedure belongs, prefixed by the name of its containing module
and postfixed by its arity, mode number and determinism".

> +replacing "/usr/local/mercury-1.0" with the directory
> +that your Mercury implementation was installed in.

You probably want to replace 1.0 with 0.9 throughout.

> +Emacs will then create several "buffers": one for the debugger prompt,
> +one for the output of the program being executed, and one or more for
> +the source files.

You should specify into which window the user should type input that is
intended for the program, not the debugger.

There must be restrictions on which of the five context options the emacs
interface can perform source linking with. It does not have enough information
if "context none" is selected; can it parse context information from all
four of the other context formats? This must be documented.

Zoltan.
--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------