Re: What's an annex? stratum?

[Jim Blandy <jimb at codesourcery dot com>]

Michael Eager <eager@eagercon.com> writes:
>> For what it's worth --- we don't invest enough time in
>> doc/gdbint.texinfo to keep it a clear, accurate reference to the
>> code.  (For me, at least, this is a deliberate decision.)  It's more a
>> collection of the clearer explanations that have appeared on the
>> mailing list over time.
>
> Unfortunately, much of it is obsolete.  Some sections, like 9.6,
> make this explicit.  Other sections say that the area is in flux,
> like section 9.7.  Other sections don't tell you that they are
> out of date (like the section about libgdb?).
>
> Some important parts are simply missing, like the sections titled
> Console Printing, TUI, Frame Interpretation, Inferior Call Setup, and
> others.
>
> I don't mean to harp on the documentation, but often the "clearer
> explanations" amount to commentary about how the old technique didn't
> work well and the new technique is better.  That may be true, but it
> doesn't reveal much about how to use the technique.
>
> If I get to the point where I think I really understand an area,
> I'll be happy to contribute to documentation improvements.  I'm
> not there at the moment.

Well, let me try again to say what I meant: if you're new to GDB, you
should not start by reading gdbint.texinfo.  Instead, start by reading
and grepping, and then experiment by debugging GDB with itself.  If
you ask a question, people may occasionally refer you to
gdbint.texinfo.  But it's not useful as a getting started guide for
GDB hackers, and I think the effort required to make it so is far more
than any of us have available.

I'm even a little skeptical about the value of internals documentation
at all.  It seems to me that explanations like that belong in the
code, where people are more likely to see them, keep them up to date,
and delete them when appropriate.