From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <gdb-patches-return-65892-listarch-gdb-patches=sources.redhat.com@sourceware.org>
Received: (qmail 3547 invoked by alias); 6 Aug 2009 18:11:49 -0000
Received: (qmail 3538 invoked by uid 22791); 6 Aug 2009 18:11:48 -0000
X-SWARE-Spam-Status: No, hits=-1.0 required=5.0 	tests=AWL,BAYES_00,SPF_SOFTFAIL
X-Spam-Check-By: sourceware.org
Received: from mtaout7.012.net.il (HELO mtaout7.012.net.il) (84.95.2.19)     by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Thu, 06 Aug 2009 18:11:42 +0000
Received: from conversion-daemon.i-mtaout7.012.net.il by i-mtaout7.012.net.il (HyperSendmail v2007.08) id <0KNY00L00VKBHK00@i-mtaout7.012.net.il> for gdb-patches@sourceware.org; Thu, 06 Aug 2009 21:11:39 +0300 (IDT)
Received: from HOME-C4E4A596F7 ([77.126.151.173]) by i-mtaout7.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0KNY00KHHVVDIE50@i-mtaout7.012.net.il>; Thu, 06 Aug 2009 21:11:38 +0300 (IDT)
Date: Thu, 06 Aug 2009 18:42:00 -0000
From: Eli Zaretskii <eliz@gnu.org>
Subject: Re: [rfc] Infrastructure to disable breakpoints during inferior startup
In-reply-to: <m3ab2dgcht.fsf@fleche.redhat.com>
To: Tom Tromey <tromey@redhat.com>
Cc: uweigand@de.ibm.com, thiago.bauermann@gmail.com, gdb-patches@sourceware.org, pedro@codesourcery.com, jkratoch@redhat.com
Reply-to: Eli Zaretskii <eliz@gnu.org>
Message-id: <833a84olra.fsf@gnu.org>
References: <200908051814.n75IED4s005139@d12av02.megacenter.de.ibm.com> <m3ab2dgcht.fsf@fleche.redhat.com>
X-IsSubscribed: yes
Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm
Precedence: bulk
List-Id: <gdb-patches.sourceware.org>
List-Subscribe: <mailto:gdb-patches-subscribe@sourceware.org>
List-Archive: <http://sourceware.org/ml/gdb-patches/>
List-Post: <mailto:gdb-patches@sourceware.org>
List-Help: <mailto:gdb-patches-help@sourceware.org>, <http://sourceware.org/ml/#faqs>
Sender: gdb-patches-owner@sourceware.org
X-SW-Source: 2009-08/txt/msg00091.txt.bz2

> Cc: eliz@gnu.org, thiago.bauermann@gmail.com (Thiago Jung Bauermann),
>         gdb-patches@sourceware.org, pedro@codesourcery.com,
>         jkratoch@redhat.com
> From: Tom Tromey <tromey@redhat.com>
> Date: Thu, 06 Aug 2009 09:58:54 -0600
> 
> I think there is still a need for an internals document, because there
> are things worth documenting that don't have a natural location in a
> source file.  I'm thinking of things like coding conventions, HIG
> guidelines for new commands, etc -- things that affect future decisions
> but that are not inherent in the code.

That's one reason for the internals manual.  The other -- which IMO is
a more important one (but I'm in minority here) -- is that Texinfo
allows you to organize the documentation for easy reading in ways code
comments never will.  You cannot have index entries in comments, and
you cannot have cross-references which are easy to be followed, two
features without which reading about a complicated topic described in
several places is a PITA.

So ideally, we should have both code comments and corresponding manual
docs, IMO.