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

[Eli Zaretskii <eliz at is dot elta dot co dot il>]

On Tue, 20 Mar 2001, Stan Shebs wrote:

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

There's another important consideration: the ease of finding
information when you use the manual as a reference (as opposed to a
textbook which is read in its entirety).

The most efficient means of using a manual as a reference is the `i'
command of the Info browser.  (For those who don't know: that command
looks up a string you type in the manual's indices, and in a
well-indexed manual, will usually land you on the right spot in a
matter of seconds.)

If that fails, the next best alternative is `s' which searches the
manual's text for a string or a regexp.

By contrast, the facilities presented by today's Info browsers for
searching multiple documents are abysmally inadequate.  In the
stand-alone Info reader, we have the --apropos option (which I'm quite
sure some of the people here have never heard about); and we have
nothing similar in Emacs.

Also, please note that the chapters which describe annotations and
GDB/MI are already very technical in nature and come very close to
documenting the internals.

So I think, on balance, merging the two documents would be a good
thing.