Re: A new strategy for internals documentation

[John Gilmore <gnu at toad dot com>]

The real issue is not about where the information is stored.  The real
issue is that people are evolving the code base without evolving the
matching documentation.  This is accepted to be a sin with regard to
the "Debugging with GDB" manual, which IS required to be complete,
definitive, tutorial, and readable.  Could I gently suggest that
contributors who make patches that evolve e.g. the symbol table handling,
but who don't document their improvements in Gdbint, be gently reminded
to improve and resubmit their patch by including a patch to gdbint as well?  

I started the GDB Internals manual.  Why?  Because we had no place to
record textual explanations about why and how GDB is internally
structured.  For example, there was no obvious place to put a list of
"how to add a new target type to GDB".  You had to edit half a dozen
files, in sync, and none of those files was the right place to put the
overview information.  For another example, we had nothing that
described an overview of how symbol table processing works -- how it
gets read in from files, how it gets searched, what jobs the various kinds
of symbol tables in GDB are designed to do (and designed specifically NOT
to do).  I had to maintain that code but had no idea how psymtabs versus
symtabs were supposed to work.  (I could figure out what the code did,
but was that what it was supposed to be doing?)

So as I gradually learned (or created) these things, I put whatever
documentation I had, into the GDB Internals manual.  Frequently a
contribution was the sort that might be sent as an email to the
maintainers list, like "I just added a new host type -- here are all
the places I had to touch."

Gdbint was never intended to be definitive -- because there has seldom
been enough time, or writing ability, to make it definitive.  And it
was never intended to be complete.  It was designed as a net to catch
useful short bits of prose so that future maintainers would be able to
find them.  But it was far better than having nothing.  And it is part
of the source code, so it can evolve along with the source code, and
the version that ships in, and matches, each source release of GDB can
be easily found.

It seems to me that the main arguments for change are:

  *  It's fragmented and inconsistent.

Any replacement for gdbint will also be fragmented and inconsistent, 
unless the team decides it's worth spending the resources to write
a complete and consistent internals manual, which seems unlikely.
Therefore this is not an argument for change.

  *  It's too hard to edit texifo.

Texinfo markup is not significantly easier or harder than Wiki markup.
They do the same basic things.  And anyone who maintains GDB will need
to understand how to edit texinfo anyway, since anyone who adds or removes
a feature has to fix its documentation in the GDB Manual.  So this is
not an argument for change either.

  *  Wikis have a more "dynamic style"

Gdbint is just as dynamic as the GDB source code.  It's stored in a
widely distributed, branch oriented source code control system.  Anyone
who can usefully edit a GDB source file can usefully edit gdbint.texinfo.
On the contrary, to edit the Wiki requires a separate login and permission.

  *  Changes to Gdbint should not go through approval

If the team agrees with this, it's easy enough for any GDB maintainer
to merely approve gdbint changes that are submitted as patches.
(Presumably if they come in along with a substantive code change,
you'd only insert the gdbint change when the code change is also
approved.  Having half the change in the source code and half in a
wiki would complicate that process.)

My suggestion is that if somebody (Stan?) actually wants to put many
hours into improving the situation with respect to GDB internal
documentation, spend your time making the text better, strategically,
rather than wasting time moving info from one format (texinfo) to
another (Wiki markup).  As a senior maintainer, you know what parts
of it are obsolete and why -- insert a FIXME paragraph explaining
that that part is obsolete and why, and encouraging anyone who has
the time and information to update it to match the code.

My experience with Doxygen comments has been that they quickly become
formulaic.  This provides sometimes-useful material about the
arguments of individual functions -- which is best read directly in
the source code rather than in a separate manual -- but seldom
provides an overview of what's actually going on.  It produces an
endless forest of detailed information, when what the reader wants is a few
paragraphs of overview to know where to focus their attention to handle
the job in front of them.

That's what the GDB Internals manual was originally created to do.
If it isn't doing that job, don't just change its format; change the
process of updating the information, so that the information becomes
relevant again.

	John