Re: A new strategy for internals documentation

Eli Zaretskii
2013-08-08T17:28:23Z

> Date: Wed, 07 Aug 2013 12:58:14 -0700
> From: Stan Shebs <stanshebs@earthlink.net>
> CC: gdb@sourceware.org
>
> > 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.

My way is faster and easier.

> People do want internals documentation, we hear grumbles about it on a
> weekly basis.

The grumbles come from people other than those who can provide the
documentation. And the latter don't think we have a problem in the
first place.

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

Again, if we don't care about the documentation, then of course we
shouldn't care about poor information. If we do care, then wiki is a
way to waste resources at best.

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

How is this different from a typo in the code?

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

Red herring. I asked RMS about this once, and the answer was there
was no problem.

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

I do, quite a lot. Besides, Info is the official format of GNU
documentation, you will have hard time convincing the FSF to demote an
existing manual.

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

Why do you need development for comments?

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

The net result will be that the documentation will be unreadable. Not
everybody who writes good code can write good documentation.

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

Another red herring, AFAIK. I can decide to distribute the text that
I wrote under any license I want, as long as I don't preclude the FSF
to distribute that text in the GNU manuals under GFDL. The fact that
I assigned the copyright to the FSF for the manual just means that the
FSF is free to distribute that text in that manual. But it doesn't in
any way preclude me to distribute the same text in other ways. IOW,
assignment of copyright doesn't mean the FSF now owns the text.