Re: A new strategy for internals documentation

[Stan Shebs <stanshebs at earthlink dot net>]

On 8/6/13 9:28 PM, Eli Zaretskii wrote:
>> Date: Tue, 06 Aug 2013 15:26:34 -0700
>> From: Stan Shebs <stanshebs@earthlink.net>
>>
>>
>> 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?

Isn't that going to be the end state of what I'm proposing? :-) I just
added a path to conserve any bits that seem useful.

People do want internals documentation, we hear grumbles about it on a
weekly basis.  But, having made a couple runs at updating the internals
manual myself, it's a daunting prospect, and always unclear what its
scope and detail level should be.  I'm not ready to give up on the
idea of internals documentation altogether, since we do have other
options we can try.

>> *** Migration of gdbint.texinfo to wiki
> 
> Wiki is a bad idea, because there's virtually no control on the
> quality of the information there.

That's true now, but I don't think I've heard of anybody being misled by
poor information on the GDB wiki.

>> * 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?

If nothing else, ensuring that "make info" doesn't break because
you forgot an @-sign. :-)

>> * 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.

I just meant that there are sections of the internals manual saying "go
here for GNU coding standards", "go here to post a bug report", that
sort ofthing.  We have multiple copies of all that verbiage elsewhere now.

>> 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.

True, if you're not mixing anything.  In the discussion that started
with http://www.sourceware.org/ml/gdb/2009-10/msg00208.html , there
seemed to be valid concerns about how things could be intermixed, and I
note that the libg++ documentation has a specific disclaimer that the
auto-generated parts of its docs are GPL and separate from the GFDL parts.

>> *** 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.

Hmm, I'm perhaps prejudiced since I haven't looked at any info file in
probably a decade.  Are many people using them still?

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

It's plausible, but idiosyncratic.  How much development does it get,
vs Doxygen?

> 
>> *** 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?...

I think it's time-consuming overkill for tutorials and howtos.  An
underlying implicit goal here is to encourage contribution, not think of
ways to chase people away.  Sure, for the official user manual, we need
to be careful about what it says, but a "hey, here's how I like to debug
signal handlers" shouldn't need anybody else to decide whether it's
allowed or not.

>> 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.

It might not; it would be an experiment.  Lots of hackers like it
though, so there's at least some empirical evidence in its favor.

>> 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.

Yes, in theory I could re-contribute my bits, but I really really don't
want to spend hours of debate on whether the licenses, or FSF ownership,
even allow for that, or if there if some obscure obstacle.
There are some bits of value in the old manual, but not enough to
justify sucking everybody into contemplation of arcane legal points.
I'd rather just leave it at "don't go there". :-)

Stan
stan@codesourcery.com