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 20 Mar 2001, J.T. Conklin wrote:

> I've seen the puzzled expressions of folks when encountering the gcc
> manual for the first time.

I don't think the GCC manual is something we should consider as an
example: it is IMHO in such a bad shape that it cannot possibly serve
as a useful example of anything.  For starters, its indices, the
single most important means for finding information quickly, omit too
much; even the command-line options are not indexed!

> A further split into a users and a reference manual is also desirable.
> I can't recall a single manual where both introductory and reference
> information was presented well.

Please tell what would you like to see in a typical reference
manual, and why do you think a single manual cannot usefully serve
that purpose along with being an introduction.

The usual philosophy of a good manual written in Texinfo is that you
describe the various package facilities in a logical order, as
appropriate for someone who learns to use the package for the first
time, and leave it up to the indexing to provide the ability of using
the manual as a reference.

> But it is something to consider as we continue editing the manual, I
> think our current scheme leaves a lot to be desired.

If you have specific issues with the current scheme and/or suggestions
for improvement, please tell what they are.