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

[Fergus Henderson]

On 09-Dec-1999, Erwan Jahier <Erwan.Jahier at irisa.fr> wrote:
> | I've changed that to the following:
> | 
> |  | Then start up Emacs, e.g. using the command @samp{emacs},
> |  | and type @kbd{M-x mdb @key{RET}}. Emacs will prompt you for
> |  | the mdb command to invoke
> |  | 
> |  | @example
> |  | Run mdb (like this): mdb
> |  | @end example
> |  | 
> |  | @noindent
> |  | and you should type in the name of the program that you want to debug
> |  | and any arguments that you want to pass to it:
> |  | 
> |  | @example
> |  | Run mdb (like this): mdb ./hello arg1 arg2 ...
> |  | @end example
> | 
> | Hopefully that is clearer?
> 
> Well, I'm not sure: 
...
> It is ok if you already know emacs, but it might(?) be disturbing otherwise 
> IMHO.
> 
> What about:
> 
> |  | Then start up Emacs, e.g. using the command @samp{emacs},
> |  | and type @kbd{M-x mdb @key{RET}}. Emacs will prompt you for
> |  | the mdb command to invoke and you should type in the name of 
> |  | the program that you want to debug and any arguments that 
> |  | you want to pass to it:
> |  | 
> |  | @example
> |  | Run mdb (like this): [M-x] 
> |  |                         mdb [RET]
> |  |                         mdb ./hello arg1 arg2 ... [RET]
> |  | @end example
> 
> ?

I don't think that is an improvement.

For one thing, that suggests to the user that they should wait until
they get a "Run mdb (like this): " prompt before typing M-x, which
is not the case.  Also this suggests that the user needs to type in
"mdb" twice, which is also not the case.

I think the current documentation is adequate; probably it is
a bit unclear if read in isolation, but as soon as the user
actually runs Emacs and follows the instructions, I think it
should become clear.  So for now I will leave it as is.

Of course, if you have any further suggestions for improvement,
I'd still appreciate hearing them.

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