Re: A new strategy for internals documentation

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Tue, 06 Aug 2013 15:26:34 -0700
> From: Stan Shebs <stanshebs@earthlink.net>
> 
> Although GDB has had an internals manual for many years, nobody has
> been especially happy with it.  It is perennially out of date,
> sometimes majorly so, and it is quite incomplete.  With the passage of
> time, the whole idea of an internals manual has come to seem like a
> throwback to the old days, when the prospective GDB hacker's
> information had to come from either printed books, or tape archives
> downloaded from an FTP site.
> 
> Various ideas for how to fix have been floating around, generally with
> the goal of improving the manual somehow, but nothing has developed
> into action.
> 
> I propose a two-pronged strategy, first migrating the internals manual
> to the wiki, and then introducing Doxygen for source code
> documentation.

It is customary to save the important issues to the end, but I'd like
to break that custom and ask this now: do we even want to document the
internals?  This is a serious question: over the years, I've had my
share of trying to convince the main contributors to improve the
internals manual, and the result was always the same: people are
generally happy with the commentary in the code and don't feel any
need to go any further.

So how just declaring gdbint.texinfo dead and deleting it altogether?
Why should we waste any breath arguing about a creature that is not
loved by anyone?

Having said that (and I do suggest to discuss this main issue first),
here are some comments about specific points of the proposal.

> *** Migration of gdbint.texinfo to wiki

Wiki is a bad idea, because there's virtually no control on the
quality of the information there.

> * Procedures and standards, such as for releases and end of year
> 
> These evolve as the release manager and other owners see fit, and the
> wiki's dynamic style is a better fit for keeping them up to date.

That is a strange opinion, given the ease of use of today's VCSs.
What exactly makes it hard to keep this part up to date now?

> * Cross-references to more info
> 
> Much of this is redundant with information already on the GDB website
> or in the wiki.

If you renounce cross-references, you in effect are saying that
hyperlinks, which IMO are one of the most important inventions in
on-line docs, are useless and should not be considered important at
all.  That is a strange opinion, indeed.

> proposals to auto-generate any of [internal API docs] from the (GPLed)
> sources run afoul of the incompatible GFDL that governs the wiki and
> the manuals.

That's not correct.  Generation of a Texinfo manual from program
sources is well established, and used in libiberty, binutils, and
elsewhere.  The licensing issue is AFAIU a red herring.

> *** Doxygen
> 
> As a second step, we should adopt Doxygen for the sources, and use it
> to generate material for a new area of the website, which will be the
> detailed documentation of GDB internals.

AFAIK, Doxygen cannot generate an Info manual, only HTML.  If so, this
would be a serious downside that you don't mention.

If we want to keep the documentation in the sources, why not use the
same system as libiberty?

> *** Upsides
> 
> Having the narrative and descriptive material as a pile of wiki page
> will make it easier to tinker with incrementally.  Changes won't go
> through a formal patch review process, which is OK because the pages
> are more informal and tutorial rather than authoritative.

Not having a review process for documentation is an "upside"
because?...

> (Knowledgeable GDBers should still monitor edits and fix any serious
> errors that creep in.)

Why should "Knowledgeable GDBers" do the job of whoever submits the
patch?  Do we have a lot of free time on our hands to do that?  Patch
review is a well established process in GDB maintenance and
development, and AFAICS it works reasonably well, certainly in the
area of the documentation.  Why would we consider getting rid of it?

> Conversely, Doxygen in the sources will bring additional rigor and
> detail to a chronically weak aspect of GDB's code, namely, how the
> different parts are supposed to work with each other.

This is precisely the problem with documenting in comments, but (see
above) people seem to be happy with it.  So I don't see how Doxygen
will change any of that.

> As a texinfo document, it has always been possible to produce printed
> versions, info files, PDF files, etc, and we will lose that
> capability.  However, while this is important for the main GDB manual,
> there is no evidence that any GDB hacker uses the internals manual in
> these formats as guidance when working on GDB, nor do I know of
> anybody selling a printed internals manual.

That's tautology: since the manual is terribly outdated, why would
someone use it?

> The licensing requires us to be careful about migrating pieces of
> text; material from gdbint.texinfo can be copied to the wiki, but not
> into the sources.  This is not purely hypothetical, as for instance
> the gdbint.texinfo description of i386_insert_watchpoint is more
> detailed than the comments currently in the source code.

Because the author for some strange reason believed that the
documentation should be in the manual rather than in the sources.  But
that author is still among us, so you could ask him politely whether
he would like to consider relicensing the stuff.

> In such a case, it is allowable to refer to the gdbint description
> when expanding on the comments in the source code, but not to copy
> verbatim.  However, I believe the amount of material that would need
> to be rewritten in this way is small, perhaps a dozen pages or so,
> requiring only a few hours of work.

Most of the authors are still available, you can ask them about
relicensing.

> The existence of two places to record information may become a dilemma
> for contributors.

No one will want to update two places.  Heck, even with one we have
difficulties.