From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 4996 invoked by alias); 3 Jan 2012 08:17:06 -0000 Received: (qmail 4986 invoked by uid 22791); 3 Jan 2012 08:17:04 -0000 X-SWARE-Spam-Status: No, hits=-3.1 required=5.0 tests=AWL,BAYES_00,RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from fencepost.gnu.org (HELO fencepost.gnu.org) (140.186.70.10) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Tue, 03 Jan 2012 08:16:51 +0000 Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1RhzY6-0007lK-So; Tue, 03 Jan 2012 03:16:46 -0500 Date: Tue, 03 Jan 2012 08:17:00 -0000 Message-Id: From: Eli Zaretskii To: Tom Tromey CC: stanshebs@earthlink.net, gdb-patches@sourceware.org In-reply-to: (message from Tom Tromey on Mon, 02 Jan 2012 15:07:51 -0700) Subject: Re: FYI: minsyms documentation Reply-to: Eli Zaretskii References: <4EF38DAD.3040106@earthlink.net> <8362h8z60x.fsf@gnu.org> <4EF39E85.3050207@earthlink.net> <83vcp7xqxx.fsf@gnu.org> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2012-01/txt/msg00083.txt.bz2 > From: Tom Tromey > Cc: Stan Shebs , gdb-patches@sourceware.org > Date: Mon, 02 Jan 2012 15:07:51 -0700 > > >>>>> "Eli" == Eli Zaretskii writes: > > Stan> Are newbies learning by reading the manual, or reading the code? > > Eli> What newbies? The people who hack at the core features of GDB can be > Eli> counted on fingers of a single hand, and they didn't change in years. > > There have been multiple new contributors since I started seriously > working on GDB 3 years ago. I was not talking about contributors. I was talking about people who dare hacking at the core features and making structural changes that cross boundaries of APIs. > Eli> Again, the current content of that manual can only do a mis-service, > Eli> so redistributing it is wasted effort. > > This is not entirely true. Some of gdbint.texinfo is badly out of date, > but some of it is still relevant. Without a clear markings which are which, and with large parts of it badly outdated, it is still a reader-unfriendly document, reading which runs a very high risk of learning misleading or downright incorrect information. Emacs development has a habit that a release requires careful review of the documentation for inaccuracies, stale or incorrect information, etc. We don't have such process; perhaps we should introduce it. > For example, it is still the only documentation for ui-out and for > cleanups I'm willing to bet that even these parts are no longer entirely accurate or complete, even though at the time they were written, they were exemplary stuff. > due to licensing, I think that text cannot be moved into comments in > the code without special dispensation from the FSF. This problem can be easily solved: read the text in the manual, close it, then write the docs in the source files without looking at the manual, but just at the code. The result will be different enough from the original to side-step the copyright issue. If needed, another person (e.g., me) can edit the comments to remove any semblance to the original that sneak in.