From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Mark Harig Newsgroups: gmane.lisp.guile.bugs Subject: Re: Typos in the manual Date: Tue, 15 Feb 2011 17:32:26 -0500 Message-ID: <8CD9B775B2E1E50-714-23E5@webmail-d099.sysops.aol.com> References: <20110208202529.GD16805@gmx.de><874o88kbbs.fsf@ossau.uklinux.net><8CD9B68D2F170D1-714-CAC@webmail-d099.sysops.aol.com> <20110215211443.GG24361@gmx.de> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; format=flowed Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1297809178 3407 80.91.229.12 (15 Feb 2011 22:32:58 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 15 Feb 2011 22:32:58 +0000 (UTC) Cc: bug-guile@gnu.org, neil@ossau.uklinux.net To: Ralf.Wildenhues@gmx.de Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Tue Feb 15 23:32:52 2011 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PpTRz-00022E-N2 for guile-bugs@m.gmane.org; Tue, 15 Feb 2011 23:32:52 +0100 Original-Received: from localhost ([127.0.0.1]:54974 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PpTRz-0005dJ-6a for guile-bugs@m.gmane.org; Tue, 15 Feb 2011 17:32:51 -0500 Original-Received: from [140.186.70.92] (port=51501 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PpTRt-0005d4-QZ for bug-guile@gnu.org; Tue, 15 Feb 2011 17:32:46 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1PpTRs-0003la-GS for bug-guile@gnu.org; Tue, 15 Feb 2011 17:32:45 -0500 Original-Received: from imr-mb02.mx.aol.com ([64.12.207.163]:58452) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1PpTRs-0003lW-E7 for bug-guile@gnu.org; Tue, 15 Feb 2011 17:32:44 -0500 Original-Received: from imo-ma04.mx.aol.com (imo-ma04.mx.aol.com [64.12.78.139]) by imr-mb02.mx.aol.com (8.14.1/8.14.1) with ESMTP id p1FMWZN5003566; Tue, 15 Feb 2011 17:32:35 -0500 Original-Received: from idirectscm@aim.com by imo-ma04.mx.aol.com (mail_out_v42.9.) id i.ffd.7e0e449 (43913); Tue, 15 Feb 2011 17:32:31 -0500 (EST) Original-Received: from smtprly-md03.mx.aol.com (smtprly-md03.mx.aol.com [64.12.143.156]) by cia-dc08.mx.aol.com (v129.7) with ESMTP id MAILCIADC082-d4324d5afefa3cd; Tue, 15 Feb 2011 17:32:31 -0500 Original-Received: from webmail-d099 (webmail-d099.sim.aol.com [205.188.255.20]) by smtprly-md03.mx.aol.com (v129.8) with ESMTP id MAILSMTPRLYMD031-d4324d5afefa3cd; Tue, 15 Feb 2011 17:32:26 -0500 X-MB-Message-Type: User Original-Received: from 98.185.24.91 by webmail-d099.sysops.aol.com (205.188.255.20) with HTTP (WebMailUI); Tue, 15 Feb 2011 17:32:26 -0500 X-AOL-IP: 98.185.24.91 X-MB-Message-Source: WebUI X-Mailer: AIM WebMail 33222-STANDARD In-Reply-To: <20110215211443.GG24361@gmx.de> X-AOL-SENDER: idirectscm@aim.com X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 64.12.207.163 X-BeenThere: bug-guile@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.bugs:5142 Archived-At: > > > Both "i.e." and "e.g." should always be followed by a comma. > > Well. Let me tell you. I've written those kinds of patches before, > adding a comma unconditionally and all. After a few maintainers of > some packages rejected them, I've become less enthused. > Something that's long been a mystery to me is why it is that computer programmers, who spend their days learning and following the rules and idioms of various programming languages, do not want to learn and follow the rules and idioms of natural languages. Reference manuals should strive to follow grammar and usage rules as much as possible in a jargon-filled context. There is enough room already for confusion and lack of precision. > Also, while the Chicago Manual of Style recommends it, some other=20 online > grammar sites mention that it is American English style, but British > English would not add a comma afterwards. Yet others do not require=20 it > even in American style. > Let's follow the guides that do require it. To propose that the comma sometimes be included and sometimes be omitted after "i.e." and "e.g." should be considered the same as proposing that the comma following the words "that is" and "for example" are optional. The comma should not be optional because it changes the meaning of the sentence, often making it ungrammatical. Examples from the Guile reference manual: Example 1: By "simple" we mean data types that are not primarily used as containers to hold other data -- i.e. pairs, lists, vectors and so on. Substituting the words "that is" for "i.e." in two alternatives, which is correct? A) By "simple" we mean data types that are not primarily used as containers to hold other data -- that is pairs, lists, vectors and so on. B) By "simple," we mean data types that are not primarily used as containers to hold other data, that is, pairs, lists, vectors, and so on. Without the comma between "that is" and "pairs," the reader has a noun-verb phrase that he needs to disambiguate to figure out the true meaning. ("that is pairs?" "that is pairs" *what*? What is "pairs" doing? Oh, you mean, "that is, pairs, lists, ...") (Note the added comma before 'and so on' in keeping with the rule that "etc." should always be preceded by a comma, and "etc." is an (Latin) abbreviation for "and so on.") Example 2: An external representation (i.e. one which can written with `write' and read with `read') of a random state object can be obtained via `random-state->datum'. Which is correct? A) An external representation (that is one which can written with `write' and read with `read') of a random state object can be obtained via `random-state->datum'. B) An external representation (that is, one which can written with `write' and read with `read') of a random state object can be obtained via `random-state->datum'. Again, without the comma after "that is," the parenthetical phrase has a different meaning than it does with the comma. With the comma, the phrase is a supplemental description of what is meant by the term "external representation." Without the comma, the phrase is selecting from the supposedly many types of "external representations." > Cheers, > Ralf (whose first style book is shipping this way right now ... :-) GNU Guile is lucky to have someone as knowledgeable as yourself reviewing its manual. --