From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7759 invoked by alias); 7 Aug 2013 04:28:34 -0000 Mailing-List: contact gdb-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-owner@sourceware.org Received: (qmail 7733 invoked by uid 89); 7 Aug 2013 04:28:34 -0000 X-Spam-SWARE-Status: No, score=-2.4 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_NO,RDNS_NONE,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from Unknown (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Wed, 07 Aug 2013 04:28:33 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0MR500E008BAFN00@a-mtaout20.012.net.il> for gdb@sourceware.org; Wed, 07 Aug 2013 07:28:24 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MR500E8V8FBEW20@a-mtaout20.012.net.il>; Wed, 07 Aug 2013 07:28:24 +0300 (IDT) Date: Wed, 07 Aug 2013 04:28:00 -0000 From: Eli Zaretskii Subject: Re: A new strategy for internals documentation In-reply-to: <5201781A.3000607@earthlink.net> To: Stan Shebs Cc: gdb@sourceware.org Reply-to: Eli Zaretskii Message-id: <83k3jyunt8.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> X-SW-Source: 2013-08/txt/msg00016.txt.bz2 > Date: Tue, 06 Aug 2013 15:26:34 -0700 > From: Stan Shebs > > 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.