From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 31144 invoked by alias); 24 Jul 2004 17:16:18 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 31132 invoked from network); 24 Jul 2004 17:16:17 -0000 Received: from unknown (HELO aragorn.inter.net.il) (192.114.186.23) by sourceware.org with SMTP; 24 Jul 2004 17:16:17 -0000 Received: from zaretski ([80.230.148.60]) by aragorn.inter.net.il (MOS 3.4.6-GR) with ESMTP id DXC98257; Sat, 24 Jul 2004 20:15:59 +0300 (IDT) Date: Sat, 24 Jul 2004 17:16:00 -0000 From: "Eli Zaretskii" To: Joel Brobecker Message-Id: <1659-Sat24Jul2004201424+0300-eliz@gnu.org> CC: gdb-patches@sources.redhat.com In-reply-to: <20040724150104.GP20596@gnat.com> (message from Joel Brobecker on Sat, 24 Jul 2004 08:01:04 -0700) Subject: Re: [RFA] Enhance GDB to break inside DSO init code Reply-to: Eli Zaretskii References: <20040723202447.GM20596@gnat.com> <7494-Sat24Jul2004105517+0300-eliz@gnu.org> <20040724150104.GP20596@gnat.com> X-SW-Source: 2004-07/txt/msg00349.txt.bz2 > Date: Sat, 24 Jul 2004 08:01:04 -0700 > From: Joel Brobecker > > > Why, oh why do people go to such great lengths to explain this in a > > mail message and/or in the comments to the code, but not as a patch to > > gdbint.texinfo? Why not invest a small additional effort (Texinfo > > markup) to improve our documentation together with fixing a bug? > > To me, explainations about the code belong in the code. I didn't object to having them in the code as well. The one significant drawback with having these explanations _only_ in the code is that one cannot easily find them, unless one already knows where and what to look for. An Info manual, by contrast, has powerful search facilities. > If I had to make a suggestion, I would embed all the information from > gdbint inside the code, and make gdbint a document generated from the > code. I support this goal, but I don't have time to work on making this happen. AFAIK, there's no GNU standard for embedding documentation in code, and, apart of the chew thingy used by Binutils, I'm not aware of any tools that can produce Texinfo. Note that some background information doesn't belong to code comments, so there will be a need for pure Texinfo somewhere even if we adopt some self-documenting-code system.