RE: Discussion: Formalizing the deprecation process in GDB

["Dave Korn" <dk at artimi dot com>]

> -----Original Message-----
> From: halo1 On Behalf Of Eli Zaretskii
> Sent: 08 October 2004 11:11

> > From: "Dave Korn" 
> > Cc: "'Andrew Cagney'" ,
> > 	<gdb>
> > Date: Thu, 7 Oct 2004 13:42:24 +0100
> > 
> > I look for the internals docs!  And complain bitterly when I can't
> > find them
> 
> Please don't hesitate to complain here whenever you find missing or
> outdated docs in GDB.  Thanks!

  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! "

  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.  I imagine
you knew that already though!

  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.

> >   Since opinions are being invited, I'll just mention that 
> I'm currently
> > working on an internal version of gdb for which I'm having 
> to up-port a
> > 5.x-compatible backend to 6.x series.  I sometimes find it 
> *ever* so hard
> > when faced with yet another deprecated__ this or obsoleted_ 
> that to know
> > what the new and approved replacement is
> 
> Andrew, should we have a section in gdbint.texinfo that lists obsolete
> techniques and their modern replacements, with short examples of both
> the old and new code, like we did for ui_* stuff?

  I think such a section would be a great resource for people working on
ports, and I would hope that it wouldn't impose too great a maintenance
burden.

    cheers, 
      DaveK
-- 
Can't think of a witty .sigline today....