Re: [rfa/doc] correct info about best C++ compilers/debug formats

[Eli Zaretskii <eliz@is.elta.co.il>]

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.