Re: Discussion: Formalizing the deprecation process in GDB

[Joel Brobecker <brobecker@gnat.com>]

> Unfortunately, it doesn't help in making a progress in this
> discussion, since all it does is reiterate your opinions that were
> clear (at least to me) during the XM_FILE debate, or else explaining
> principles and generalities that don't need to be explained.

The reason why I sent my message was that I felt that both parties
had exposed their views and that both had their merits. So I felt
that it was necessary to bring more people in the discussion and
decide one way or the other. I suggested that the discussion group
be the global maintainers for instance.

> I'm not sure what is it that you are saying here.  Should we abandon
> gdbint.texinfo and instead rely on the code to explain itself, because
> ``we are programmers and thus code is the only thing we read''?  Maybe
> I should stop trying so hard to review each documentation patch in a
> matter of days, because the code already says all there is to tell?

Just my two cents on this specific topic:

I do agree with Andrew that the place were developers search
for documentation is the code. I would love to see a lot of the
documentation contained in gdbint.texinfo be moved as comments
into the code. Having the documentation embedded inside the code
is very convenient, and also where I have been trained to look
first.

This does not mean that I am suggesting that we get rid of gdbint
entirely. I see chapters and sections that can only be placed in
a separate documentation, such as how to add support for a new
host for instance. But the documentation about partial symbol
tables, for instance, would be much more useful directly in
symtab.h or symtab.c.

I don't know about others, but I have read the gdbint manual once
from cover to cover almost 4 years ago, and never refered to it
anymore.

-- 
Joel