Merging manuals (was Re: How do you use GDB to debug GDB)

[Stan Shebs <shebs at apple dot com>]

Andrew Cagney wrote:
> 
> gdbint.texinfo is for internals - the things you see when you lift the
> bonnet (1) and start poking around with the engine.
> 
> gdb.texinfo is for the user - the external interfaces to GDB.  If anyone
> has ever wondered why the remote protocol is documented in gdb.texinfo
> and not gdbint.texinfo then this is it - it is an external interface to
> gdb.  To get carried away with the car metaphore, its a bit like the
> section of the manual which tries to explain how it is possible to
> change a flat using just the spare and tools all hidden somewhere in the
> boot (2).

A good analogy!

> As a complete asside, it has also been suggested that the two documents
> be merged.  From memory GCC did this.

GCC still works this way.  GDB has it as a separate document because
that's how John Gilmore set it up, and although I wasn't there, I bet
Roland Pesch, as the only professional tech writer at Cygnus at the time,
strongly objected to gluing the internals documentation into the user
manual.  (Probably the same way would have happened to GCC if he'd had
any input into GCC docs.)

I've thought about merging them from time to time.  The main argument
against merging should be obvious; the user manual is just that, and
should not include anything that might mislead or intimidate users.
The arguments for merging are that it slightly simplifies document
maintenance, and more importantly that it facilitates the transition
from being a user of the tool to being a developer of it.  (How often
have you looked at a GCC manual to find an option, then idly flipped
through the porting section and thought about trying your hand at it?
All the info you need is right there, right?....)

To me the arguments on each side seemed to have about equal weight, and
so I opted for the status quo.  But if people felt strongly that the GCC
approach was better, I'd be agreeable to merging the GDB manuals.

Stan