Re: Discussion: Formalizing the deprecation process in GDB

["Eli Zaretskii" <eliz at gnu dot org>]

> From: "Dave Korn" <dk@artimi.com>
> Cc: <cagney@gnu.org>,
> 	<gdb@sources.redhat.com>
> Date: Fri, 8 Oct 2004 13:40:31 +0100
> 
>   Eli, I was particularly thinking of you when I wrote
> 
> "  It's just occurred to me that this could be read as a specific complaint
> or accusation against gdb's documentation, rather than a comment on the
> generally sorry state of documentation as a whole in the software industry.
> No such inference was implied nor intended; sorry if anyone thought I was
> criticising gdb with that statement! "

I, for one, don't see your criticism as a Bad Thing; on the contrary.

>   However, since we mention it, sections 3.3-3.6, 4.3-4.4, 9.7-9.9,
> 10.3-10.6, 11.2-11.5, 12.3-12.4 and 12.7 of gdbint are missing.

Just so it is easier for me to find those places, could you please
tell the names of these sections, instead of just numbers?

>   Also, 9.5 and 9.6 are both prefixed with disclaimers; 9.5 says "This
> section is pretty much obsolete. The functionality described here has
> largely been replaced by pseudo-registers and the mechanisms described [...
> in 9.6 ...] " and refers the reader to 9.6, which says "The way GDB
> manipulates registers is undergoing significant change.  Many of the macros
> and functions refered to in this section are likely to be subject to further
> revision.".  The combined effect of these two sections is to leave the
> reader (well, this one, at any rate) with no idea how you're supposed to
> manipulate registers (or indeed, what a pseudo-register even is, since the
> term is not used nor defined anywhere else in the documentation).  And I
> didn't find that browsing the comments in regcache.h makes up for that.

I agree that such ``documentation'' is very unhelpful.  Would someone
please volunteer to write something more useful?