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

[Fergus Henderson]

On 10-Dec-1999, Zoltan Somogyi <zs at cs.mu.OZ.AU> wrote:
> 
> > + 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".

Yes, I changed it so that it would fit in the printed manual.

> Given that this often causes
> lines to wrap around, maybe we should change the default.

I think the current default is OK.

I don't think it matters if the line wraps in the debugger
documentation don't reflect exactly what the debugger outputs.

BTW, I experimented with the `context' command a little,
and I found that IMHO the `context before' and `context prevline'
outputs look awful.  I'd be happy to delete those options.
(But not for this release ;-)

> > +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"

Shall do.

> > +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".

How about "after that comes the identification of the procedure
in which the event occurred, consisting of the module-qualified name
of the predicate or function to which the procedure belongs,
followed 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.

Changing that every release would be a maintenance problem.
I could use a VERSION macro, but that would require pre-processing
the .texi file; it didn't seem worth the effort.

"1.0" is just a canonical version number for the example,
not necessarily related to the actual version installed.

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

OK, s/for the output/for the input and output/

> 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?

No.

> This must be documented.

Shall do.

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
WWW: <http://www.cs.mu.oz.au/~fjh>  |  of excellence is a lethal habit"
PGP: finger fjh at 128.250.37.3        |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------