From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 14879 invoked by alias); 9 Aug 2013 09:26:46 -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 14852 invoked by uid 89); 9 Aug 2013 09:26:45 -0000 X-Spam-SWARE-Status: No, score=-3.6 required=5.0 tests=AWL,BAYES_00,KHOP_THREADED,RCVD_IN_DNSWL_NONE,RCVD_IN_HOSTKARMA_YE,RDNS_NONE,SPF_SOFTFAIL autolearn=no version=3.3.1 Received: from Unknown (HELO mtaout23.012.net.il) (80.179.55.175) by sourceware.org (qpsmtpd/0.84/v0.84-167-ge50287c) with ESMTP; Fri, 09 Aug 2013 09:26:44 +0000 Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0MR900K00BBSNU00@a-mtaout23.012.net.il> for gdb@sourceware.org; Fri, 09 Aug 2013 12:26:21 +0300 (IDT) Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0MR900KQSBJUMP20@a-mtaout23.012.net.il>; Fri, 09 Aug 2013 12:26:18 +0300 (IDT) Date: Fri, 09 Aug 2013 09:26:00 -0000 From: Eli Zaretskii Subject: Re: A new strategy for internals documentation In-reply-to: <201308090129.r791Tw6a016114@new.toad.com> To: John Gilmore Cc: yao@codesourcery.com, stanshebs@earthlink.net, gdb@sourceware.org Reply-to: Eli Zaretskii Message-id: <83txizrz91.fsf@gnu.org> References: <5201781A.3000607@earthlink.net> <83k3jyunt8.fsf@gnu.org> <52031434.2080005@codesourcery.com> <83k3jwt7in.fsf@gnu.org> <201308090129.r791Tw6a016114@new.toad.com> X-SW-Source: 2013-08/txt/msg00040.txt.bz2 > cc: Yao Qi , stanshebs@earthlink.net, gdb@sourceware.org > Comments: In-reply-to Eli Zaretskii > message dated "Thu, 08 Aug 2013 20:30:24 +0300." > Date: Thu, 08 Aug 2013 18:29:58 -0700 > From: John Gilmore > > 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. Maybe it was so back when you started with this manual. It is no longer the case. The real issue with this manual now is that it is profoundly incomplete, so much so that some of the most important parts of the GDB internals are not described at all, or their description is just a listing of APIs without any glue. By contrast, what _is_ there is being updated as GDB is developed, as part of the development, and changes in GDB that invalidate what's in the manual are accompanied by suitable changes to the manual. > * 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. The approval part is a non-issue: I usually review patches to documentation within hours of the RFA. Note that people who mentioned this issue didn't talk about approval, they talked about the writing process itself. > If [the internals manual] 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. People want _zero_ process on its behalf. I tried to convince them otherwise, offering help in many ways, including those you mentioned, but you cannot convince someone to invest any effort when they want to invest none. So I gave up. After all, a project in general, and its documentation in particular, cannot be better than what the project's community wants it to be. Once again, the main problem (and some will say it's not a problem at all) is that the majority of GDB developers don't see any need in this manual's existence, or in any documentation of the internals besides what's in the comments. None whatsoever. Until this changes, there's no hope in improving the internals' documentation, and no need to invest any additional effort in any replacements.