From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 8881 invoked by alias); 30 Jan 2008 18:06:47 -0000 Received: (qmail 8871 invoked by uid 22791); 30 Jan 2008 18:06:46 -0000 X-Spam-Check-By: sourceware.org Received: from py-out-1112.google.com (HELO py-out-1112.google.com) (64.233.166.183) by sourceware.org (qpsmtpd/0.31) with ESMTP; Wed, 30 Jan 2008 18:06:29 +0000 Received: by py-out-1112.google.com with SMTP id v53so387045pyh.33 for ; Wed, 30 Jan 2008 10:06:26 -0800 (PST) Received: by 10.35.91.1 with SMTP id t1mr1177251pyl.5.1201716386653; Wed, 30 Jan 2008 10:06:26 -0800 (PST) Received: by 10.35.36.15 with HTTP; Wed, 30 Jan 2008 10:06:26 -0800 (PST) Message-ID: <8f2776cb0801301006w531c0694je39b2068979be3ef@mail.gmail.com> Date: Wed, 30 Jan 2008 18:14:00 -0000 From: "Jim Blandy" To: "Rob Quill" Subject: Re: New scope checking patch Cc: gdb-patches@sourceware.org In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Content-Disposition: inline References: X-Google-Sender-Auth: 88c2fd5f761d9baa 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: 2008-01/txt/msg00808.txt.bz2 On Jan 30, 2008 4:05 AM, Rob Quill wrote: > I have attached the docs patch below. I wasn't sure how much to put in > the docs, so I just put a small paragraph in the place which seemed > most appropriate. Any feedback is much appreciated. I think you can be more expansive than that --- don't be shy! :) There are two points of view to consider when you write documentation: 1) Think of someone who is writing scripts and needs your feature. Where would they look for it in the manual? What terms would they look up in the index? 2) Think of someone who is aware of the feature, but wants full details on how it works. The GDB manual is also the reference manual --- how should a reference manual describe this feature? What does a script author need to know to decide whether the feature does what they want, and whether they've used it correctly? If the feature should be mentioned in more than one place, then there should be one complete description, and the others should reference it.