From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 17971 invoked by alias); 10 Aug 2013 02:24:20 -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 17946 invoked by uid 89); 10 Aug 2013 02:24:19 -0000 X-Spam-SWARE-Status: No, score=1.2 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; Sat, 10 Aug 2013 02:24:18 +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 r7A2OA6a008579; Fri, 9 Aug 2013 19:24:10 -0700 Message-Id: <201308100224.r7A2OA6a008579@new.toad.com> To: Stan Shebs cc: gdb@sourceware.org Subject: Re: A new strategy for internals documentation In-reply-to: <52056DC4.4040109@earthlink.net> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <52031434.2080005@codesourcery.com> <83k3jwt7in.fsf@gnu.org> <201308090129.r791Tw6a016114@new.toad.com> <52056DC4.4040109@earthlink.net> Comments: In-reply-to Stan Shebs message dated "Fri, 09 Aug 2013 15:31:32 -0700." Date: Sat, 10 Aug 2013 02:24:00 -0000 From: John Gilmore X-SW-Source: 2013-08/txt/msg00061.txt.bz2 > 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. Or a README file in the source code. But the info in gdbint is too voluminous for that. Or for an email or a blog posting or a long comment block. Because it aggregates info from a lot of emails and blog postings and comment blocks. I mean, we could paste the info about symbol tables from gdbint into symtab.h, as a long multipage comment block. I doubt that that would encourage people to update it any more than they do now. Maybe more people would notice it because they would find it in grep results, since it'd be in the main source directory rather than in the doc directory. I was a long term volunteer for One Laptop Per Child. OLPC used a Wiki for its documentation. You can see that the older stuff got well documented, partly by staff and partly by volunteers like me. It fell rapidly out of date as soon as the staff shrunk and most volunteers went on to other things. You can see it today at http://wiki.laptop.org . It doesn't even mention the latest OLPC hardware or software (the XO Tablet on sale at Walmart)! And if you want the Wiki pages that match your OLPC hardware (they had four different vintages), operating system release (they've gone through about 13), etc, you are SOL -- you have to find them manually, possibly digging through the revision history of particular pages. And when wiki.laptop.org goes down, which it will one day, then only the Internet Archive will have a copy -- if we're lucky. At least the GDB documentation is in the source code, so if GDB survives, the doc also survives. > 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. That's a lovely concept. But I don't think even the amazing all-powerful C++ has managed to eliminate the requirement to add things to both header files and source files. And if you change the classic way from: * Add definitions for a new something to a struct or enum in category.h * Add code to use that new something in category.c * Add a new source module something.c that implements the something * Add something.c to the Makefile to: * Add something.c to the directory, the Makefile builds and links in every .c automatically, initializers build a dynamic data structure that enumerates all things of this category, etc... ... then you have scattered the info about "things of this category" into X number of files, rather than having a central place to ask, "How many things fall into this category? Which are they?" The classic problem with object-oriented code like this is that the information that would let you wrap your head around a concept (like a "target" or an "architecture" or a "symtab") is scattered among dozens of source files, and even merely instantiating one of them results in code running in a dozen files that inherit from each other in obscure ways. John