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

Eli Zaretskii
2008-08-05T03:32:05Z

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