This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
Re: [rfa/doc] correct info about best C++ compilers/debug formats
- From: Eli Zaretskii <eliz at is dot elta dot co dot il>
- To: Michael Elizabeth Chastain <mec at shout dot net>
- Cc: carlton at math dot stanford dot edu, drow at mvista dot com, gdb-patches at sources dot redhat dot com
- Date: Tue, 4 Feb 2003 10:07:35 +0200 (IST)
- Subject: Re: [rfa/doc] correct info about best C++ compilers/debug formats
On Tue, 4 Feb 2003, Michael Elizabeth Chastain wrote:
> The only testing I did was to build gdb (hey, it takes only 10 minutes)
> and then look at the 'makeinfo' output in the log file. I didn't even
> read the generated info files, let alone chase references.
Let me explain myself: I'm grateful that you did _any_ testing at all; it
should have been my job, except that I don't have time to do anything
these days except read the patches and approve them.
So a big thanks is in order!
> This falls in my self-claimed charter of "gdb quality assurance".
>
> I've added this to my todo list.
Thanks in advance!
> Can you give me a brain dump of how to QA the manuals: what software
> I need to have, what procedures to follow, how to check the output,
> things that often go wrong.
What I do (when I have time) is this:
- do a "make info" and make sure makeinfo doesn't print any warnings
- do a "make dvi" and make sure there are no overfull hbox warnings
from TeX that cite large (more than 10) margin overflow
- if you can afford that, view the results of "make dvi" with a DVI
previewer (or say "make pdf" and use Acrobat or its workalike), where
the manual(s) were changed, and make sure the results look pleasantly
- use any Info reader you fancy (preferably either Emacs or the
stand-alone reader from Texinfo) to display every node where changes
were made; press TAB to move to each menu item and cross-reference
that has been changed/added, and press RET to go to the target of
each of those menu items/cross-references, make sure RET places you
at the right place and doesn't barf
- while in the Info reader, type "i FOO RET" for each new/modified index
entry FOO, and see that it places you where you think it should
- also while in the reader, find the new/modified index entries in the
Index sections and make sure there aren't multiple index entries for
the same topic. These look like this:
* foo:: About foo.
* foo<1>:: Something else about foo.
If you find such entries, it is usually best to disambiguate these
multiple entries like so:
@cindex foo, the basics
@cindex foo, and its relation to bar
(you get the idea).
Again, thanks for doing any part of this.