From mboxrd@z Thu Jan 1 00:00:00 1970 From: Stan Shebs To: Andrew Cagney Cc: gdb@sourceware.cygnus.com, ischis2@home.com Subject: Merging manuals (was Re: How do you use GDB to debug GDB) Date: Wed, 21 Mar 2001 15:59:00 -0000 Message-id: <3AB7B697.CBAF2099@apple.com> References: <3AB78AA3.A534B844@cygnus.com> X-SW-Source: 2001-03/msg00202.html 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