From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Robert J. Chassell" Newsgroups: gmane.emacs.devel Subject: Re: Texinfo doc for GDB-UI Date: Thu, 26 Dec 2002 14:26:30 +0000 (UTC) Sender: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Message-ID: References: <15882.19771.90811.285810@nick.uklinux.net> Reply-To: bob@rattlesnake.com NNTP-Posting-Host: main.gmane.org X-Trace: main.gmane.org 1040912896 11241 80.91.224.249 (26 Dec 2002 14:28:16 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 26 Dec 2002 14:28:16 +0000 (UTC) Cc: emacs-devel@gnu.org Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 18RYze-0002vA-00 for ; Thu, 26 Dec 2002 15:28:14 +0100 Original-Received: from monty-python.gnu.org ([199.232.76.173]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 18RZ4C-0004ie-00 for ; Thu, 26 Dec 2002 15:32:57 +0100 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18RYyx-0004xM-0C for emacs-devel@quimby.gnus.org; Thu, 26 Dec 2002 09:27:31 -0500 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 18RYyT-0004aB-00 for emacs-devel@gnu.org; Thu, 26 Dec 2002 09:27:01 -0500 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 18RYy3-0003yb-00 for emacs-devel@gnu.org; Thu, 26 Dec 2002 09:26:40 -0500 Original-Received: from syr-24-161-120-95.twcny.rr.com ([24.161.120.95] helo=localhost) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 18RYxz-0003m6-00 for emacs-devel@gnu.org; Thu, 26 Dec 2002 09:26:31 -0500 Original-Received: by rattlesnake.com via sendmail from stdin id (Debian Smail3.2.0.114) Thu, 26 Dec 2002 14:26:30 +0000 (UTC) Original-To: nick@nick.uklinux.net In-reply-to: <15882.19771.90811.285810@nick.uklinux.net> (message from Nick Roberts on Thu, 26 Dec 2002 00:28:43 +0000) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Emacs development discussions. List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: emacs-devel-bounces+emacs-devel=quimby.gnus.org@gnu.org Xref: main.gmane.org gmane.emacs.devel:10352 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:10352 + Continue execution up to the current line. ^^ This language sounds reversed to me. It is potentially confusing, since I think of execution as continuing through a text, line by line. For me, the point of current execution goes *down* the screen. Thus, if I set a break point for in aline that is is not as yet executed, I expect to go *down* the display of the source code to find that line, not up the screen to it. Please simply write + Continue execution to the current line. and not use the words `up' or `down'. In my experience, readers for whom English is a second or third language have an easier time when the language is formal. They were taught such a language in school. And, in general, formal English is easier to understand since related concepts are closer to each other, or linked in well established ways. Here is a sentence that is easily understood by a fluent English speaker: .... The program will run until + it hits a breakpoint, terminates, gets a signal that the debugger is + checking for or reaches the line that the cursor is on You might change those lines to: + it hits a breakpoint, terminates, receives a signal that the + debugger seeks, or reaches the line on which the cursor currently + sits. You might change from + GDB-UI is invoked with the command @code{gdba}. As well as having the + usual features of GUD, it does the following : ^^^^^^^^^^ ^^^^^^^^^^^ | - extraneous space to + GDB-UI is invoked with the command @code{gdba}. In addition to + the usual features of GUD, it has the following: ^^^^^^^^^^ The imperative verb in a sentences such as the following is often read in an isolated context: from: + @item + Finds the source file where execution begins and displays it in a buffer. ^^^^^ to + Find the source file where execution begins and displays it in a buffer. ^^^^ from + Displays a bullet point icon in the margin on the line at which a ^^^^^^^^ ^^^^^^^^^^^^^^^^^ to + Display a bullet in the margin on the line at which a ^^^^^^^ ^^^^^^ The following is weird: + breakpoint is placed. This is red when the breakpoint is enabled and + grey when it is disabled. ^^^ ^^^^ What color is the breakpoint when the user changes the color, as I do, or when the user can display only a single color, or when the user listens to the buffer, rather than looks at it? The sentence reads as if you are planning only for non-blind people to run GDB locally in a fully working, expensive system with a working graphical interface. Please re-write the sentence to explain the user interface to someone listening to the buffer (using eflite, which does not offer different voices as yet), and to someone viewing the buffer while working remotely over a slow line. + The extra buffers may either be displayed in the same frame or a Are the buffers `extra', meaning `superfluous' or are they `additional'? If the latter, please use the word `additional', since that word is more immediately comprehensible in this context to someone for whom understanding is difficult. + @code{gdb-frame-*-buffer} respectively where * needs to replaced ^ ^ The `@var' command in Texinfo provides a way to display and discuss metasyntactic variables; please use it. Please select a meaningful word for the metasyntactic variable (unfortunately, I cannot think of one). I hope this helps. I lack the time to make more comments, but this should give you some ideas. -- Robert J. Chassell Rattlesnake Enterprises http://www.rattlesnake.com GnuPG Key ID: 004B4AC8 http://www.teak.cc bob@rattlesnake.com