From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.devel Subject: Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Date: Wed, 27 Apr 2011 20:40:17 +0100 Message-ID: <87vcxz5vq6.fsf@ossau.uklinux.net> References: <8CDD0063C9BEB29-FC8-5987@web-mmc-d08.sysops.aol.com> <8CDD0D662A18273-1820-10289@webmail-m029.sysops.aol.com> <8CDD19915ED74FC-D20-21138@webmail-d017.sysops.aol.com> <874o5k28e8.fsf@ossau.uklinux.net> <8CDD312F8902D56-2538-152DE@webmail-m127.sysops.aol.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: dough.gmane.org 1303933234 5761 80.91.229.12 (27 Apr 2011 19:40:34 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 27 Apr 2011 19:40:34 +0000 (UTC) Cc: wingo@pobox.com, guile-devel@gnu.org To: Mark Harig Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Wed Apr 27 21:40:30 2011 Return-path: Envelope-to: guile-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QFAb7-0007GQ-MX for guile-devel@m.gmane.org; Wed, 27 Apr 2011 21:40:29 +0200 Original-Received: from localhost ([::1]:47890 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QFAb6-0006NC-U3 for guile-devel@m.gmane.org; Wed, 27 Apr 2011 15:40:28 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:48191) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QFAb4-0006N4-Lj for guile-devel@gnu.org; Wed, 27 Apr 2011 15:40:27 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QFAb3-0000B8-Hg for guile-devel@gnu.org; Wed, 27 Apr 2011 15:40:26 -0400 Original-Received: from mail3.uklinux.net ([80.84.72.33]:48108) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QFAb3-0000Ah-A1 for guile-devel@gnu.org; Wed, 27 Apr 2011 15:40:25 -0400 Original-Received: from arudy (unknown [78.149.119.171]) by mail3.uklinux.net (Postfix) with ESMTP id 9FCB71F662B; Wed, 27 Apr 2011 20:40:18 +0100 (BST) Original-Received: from neil-laptop (unknown [192.168.11.9]) by arudy (Postfix) with ESMTP id 0C1EC3803B; Wed, 27 Apr 2011 20:40:18 +0100 (BST) In-Reply-To: <8CDD312F8902D56-2538-152DE@webmail-m127.sysops.aol.com> (Mark Harig's message of "Wed, 27 Apr 2011 12:54:56 -0400") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/23.2 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4-2.6 X-Received-From: 80.84.72.33 X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:12365 Archived-At: Mark Harig writes: >> > +The @var{function} is most often a simple symbol that names a function >> > +that is defined in the script. It can also be of the form @code{(@@ >> > +@var{module-name} @var{symbol})}, and in that case, the symbol is >> > +looked up in the module named @var{module-name}. >> >> You inserted a comma here before "@var{symbol})}, and in that case". I >> agree that a comma was needed, but would have put it as "@var{symbol})} >> and, in that case, the ...". What do you think? >> > > Is the sentence of the form 1) "A and B" or of the form 2) "A, and some > supplemental information about A"? I think it is 2). Then, you are > left with the choice of how many commas: > > 1) "A, and, in that case, B" > 2) "A, and in that case, B" > 3) "A and, in that case, B" > > Either choice 1) or 2) gets my vote. Choice 3) is, I think, an error. I'm not sure it's completely clearcut but yes, I see your point. In that case I might technically favour 1), but then that's a lot of commas. But, in any case, ... > Another perspective: Re-write the sentence, replacing "and in that > case" with "in which case." This should make it clearer that the > sentence consists of a main clause and a sub-clause (preceded by a > comma), not two main clauses. ... this is a much nicer idea than any of the above! >> > +@table @env >> > +@item GUILE_AUTO_COMPILE >> > +@vindex GUILE_AUTO_COMPILE >> > +This is a flag that can be used to tell Guile whether or not to compile >> > +Scheme source files automatically. Starting with Guile 2.0, Scheme >> > +source files will be compiled automatically, by default. >> >> Is it useful to say "Starting with Guile 2.0" in a post-2.0.0 version of >> the manual? I think that expression could be deleted now. >> > > That's a consequence of the fact that I looked up what information I > could find from the NEWS file, and then used that text as an initial > version. > > I agree that it's not the best solution to the problem, but the > problem is "how does the manual convey to long-time Guile users this > change in behavior?" I do not have a good solution to that in this > brief patch. For now, experienced users will and should rely on the > NEWS file to inform them about changes in behavior. Agreed. I think it makes sense overall for the manual to describe the status quo (plus the history section, for fun) and for NEWS to cover changes. (Notwithstanding that there are some occurrences in the manual source of `@vnew{...}', which I guess was/is an attempt to codify such things (when features changed, or were introduced) in the manual source. As far as I know this usage has never been sufficiently widespread to be reliable.) Regards, Neil