From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eli Zaretskii To: "J.T. Conklin" Cc: Stan Shebs , gdb@sourceware.cygnus.com Subject: Re: Merging manuals (was Re: How do you use GDB to debug GDB) Date: Wed, 21 Mar 2001 15:59:00 -0000 Message-id: References: <5melvs7ywm.fsf@jtc.redback.com> X-SW-Source: 2001-03/msg00224.html 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.