From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21668 invoked by alias); 9 Aug 2013 22:31:42 -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 21643 invoked by uid 89); 9 Aug 2013 22:31:41 -0000 X-Spam-SWARE-Status: No, score=-1.4 required=5.0 tests=AWL,BAYES_50,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_YE,RDNS_NONE autolearn=no version=3.3.1 Received: from Unknown (HELO elasmtp-dupuy.atl.sa.earthlink.net) (209.86.89.62) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 09 Aug 2013 22:31:41 +0000 Received: from [68.96.200.16] (helo=macbook2.local) by elasmtp-dupuy.atl.sa.earthlink.net with esmtpa (Exim 4.67) (envelope-from ) id 1V7vDZ-0005g2-K3 for gdb@sourceware.org; Fri, 09 Aug 2013 18:31:33 -0400 Message-ID: <52056DC4.4040109@earthlink.net> Date: Fri, 09 Aug 2013 22:31:00 -0000 From: Stan Shebs User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.7; rv:17.0) Gecko/20130801 Thunderbird/17.0.8 MIME-Version: 1.0 To: gdb@sourceware.org Subject: Re: A new strategy for internals documentation References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <52031434.2080005@codesourcery.com> <83k3jwt7in.fsf@gnu.org> <201308090129.r791Tw6a016114@new.toad.com> In-Reply-To: <201308090129.r791Tw6a016114@new.toad.com> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit X-ELNK-Trace: ae6f8838ff913eba0cc1426638a40ef67e972de0d01da940e2d70ecd95f75eb69ff4854c2d2b8a81350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c X-SW-Source: 2013-08/txt/msg00056.txt.bz2 On 8/8/13 6:29 PM, John Gilmore wrote: > 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? In theory that's always been the case, but once the manual fell out of sync, it was easy to reply with "my change refers to material not in the manual" or "I don't have the time nor understanding to get the internals manual back up to date". We also have never had consensus among the maintainers whether this was something to enforce, and it only take one maintainer approving patches (or committing their own) that change the internals, and the manual immediately stop reflecting reality. > I started the GDB Internals manual. Why? Because we had no place to > record textual explanations about why and how GDB is internally > structured. The ironic thing is that no one working on a new free software project today would react to that situation by saying "we need an internals manual". The project would add a wiki page, send an email, or maybe a blog posting, or a long comment block in the source code. If there were a half-dozen files to edit in sync, these days there is more likely to be intense pressure to refactor that code and bring it back down to one place to edit, which would then be the place for the documentation about it. While your detailed points are logically valid, we have twenty years of empirical experience that says reality is not conforming to what we originally imagined. So I've suggested a Plan B where we try a couple alternatives that are known to have a good track record in other projects; they do not entail massive commitments or even very much change initially. If neither work out, then we shrug, drop them, and think of a Plan C to try instead. Stan stan@codesourcery.com