From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 20421 invoked by alias); 9 Aug 2013 01:30:16 -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 20405 invoked by uid 89); 9 Aug 2013 01:30:15 -0000 X-Spam-SWARE-Status: No, score=1.1 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RCVD_IN_BRBL_LASTEXT,RCVD_IN_HOSTKARMA_YE,RDNS_NONE autolearn=no version=3.3.1 Received: from Unknown (HELO new.toad.com) (209.237.225.253) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 09 Aug 2013 01:30:14 +0000 Received: from new.toad.com (localhost.localdomain [127.0.0.1]) by new.toad.com (8.12.9/8.12.9) with ESMTP id r791Tw6a016114; Thu, 8 Aug 2013 18:29:58 -0700 Message-Id: <201308090129.r791Tw6a016114@new.toad.com> To: Eli Zaretskii cc: Yao Qi , stanshebs@earthlink.net, gdb@sourceware.org Subject: Re: A new strategy for internals documentation In-reply-to: <83k3jwt7in.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <52031434.2080005@codesourcery.com> <83k3jwt7in.fsf@gnu.org> Comments: In-reply-to Eli Zaretskii message dated "Thu, 08 Aug 2013 20:30:24 +0300." Date: Fri, 09 Aug 2013 01:30:00 -0000 From: John Gilmore X-SW-Source: 2013-08/txt/msg00036.txt.bz2 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