Re: [RFA][patch 1/9] Yet another respin of the patch with initial Python support

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 4 Aug 2008 22:07:54 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: bauerman@br.ibm.com, tromey@redhat.com, gdb-patches@sources.redhat.com
> 
> On Mon, Aug 04, 2008 at 10:48:46PM +0300, Eli Zaretskii wrote:
> >    When executing the @code{python} command, Python exceptions
> >    uncaught within the Python code are translated to calls to
> >    @value{GDBN} error-reporting mechanism.  If the command that called
> >    @code{python} does not handle the error, @value{GDBN} will
> >    terminate it and print an error message containing the Python
> >    exception name, the associated value, and the Python call stack
> >    backtrace at the point where the exception was raised.  Example:
> 
> I think we've almost got it.  The only problem I see with the above
> text is that it's focused on user commands, both "python" and others.
> This fits with the "Canned Sequences of Commands" usage which is what
> the first patch implements, but if we can say it more generally it may
> continue to be true as more patches go in.  Here's some other
> scenarios I heard mentioned in conversation today:
> 
> - Tab completion.  Python code might be invoked when the user hits Tab
> in the middle of an expression.
> 
> - "gdb --python", which Tom has implemented on the branch - no CLI
> interpreter involved, GDB just executes a Python script.
> 
> - If Python code is used to discover some information about a stack
> frame, it might be invoked every time the program stops.
> 
> So that gives me a paragraph like this, which I think is accurate.
> Does this look OK to you?
> 
>   When executing Python code, uncaught Python exceptions are translated
>   to calls to the @value{GDBN} error-reporting mechanism.  If
>   @value{GDBN} does not handle the error, it will terminate the current
>   command and print an error message containing the Python exception
>   name, the associated value, and the Python call stack backtrace at the
>   point where the exception was raised.  Example:

I'm not sure this change is for the best: you've eliminated only one
of the two uses of "command" in this text, which just obfuscates the
text a little (what is it exactly in GDB that does not handle the
error, and if it isn't a command that invoked "python", why do we
terminate a command?).

I think trying to say the truth, all the truth, and nothing but the
truth is not the right attitude when writing software documentation.
So, on balance, I like my text better.