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

Tom Tromey
2008-07-26T18:00:50Z

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> I don't really want to merge them. I don't think it provides much
>> benefit to the reader of the manual.

Eli> The benefit is more structure. Both Python support and the old way of
Eli> defining user-defined commands is about the same thing: extending GDB.

That is one way to look at it. But really they don't have that much
in common.

The "define" command creates new user-defined commands, which are
sequences of gdb commands.

The python command accesses the python interpreter. It is not really
useful unless you already know python and want to use gdb's python
api. So, it has a much narrower audience.

>> It might make sense to document the "python" command alongside
>> "define" or what have you -- but I think only barely, since the
>> "python" command is kinda pointless without the rest of the API.

Eli> I don't see why this invalidates the merge. Please explain.

Well, there are two cases.

In one case, we put the python command and all the python API
documentation together in the "Commands" section. This means that if
you read the manual straight through, you will get a lot of
information about the CLI, then a very long diversion into the details
of the Python API, and then more information about the CLI.

In the other case, we can document the python command in one place,
but then the API elsewhere. However, this will also be a pain to
read. The python command is not useful unless you can also read about
the API. So, readers will have to flip between two parts of the
manual.

Eli> Having too many chapters is not a good sign.

This does not seem like a strong argument given that there are already
27 chapters.

Tom