From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Mark Harig Newsgroups: gmane.lisp.guile.devel Subject: Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme" Date: Wed, 27 Apr 2011 12:54:56 -0400 Message-ID: <8CDD312F8902D56-2538-152DE@webmail-m127.sysops.aol.com> 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> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="--------MB_8CDD312F8A599BF_2538_2480B_webmail-m127.sysops.aol.com" X-Trace: dough.gmane.org 1303923379 8633 80.91.229.12 (27 Apr 2011 16:56:19 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Wed, 27 Apr 2011 16:56:19 +0000 (UTC) Cc: wingo@pobox.com, guile-devel@gnu.org To: neil@ossau.uklinux.net Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Wed Apr 27 18:56:15 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 1QF82A-00054M-4o for guile-devel@m.gmane.org; Wed, 27 Apr 2011 18:56:14 +0200 Original-Received: from localhost ([::1]:35069 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QF829-0003Tf-Ny for guile-devel@m.gmane.org; Wed, 27 Apr 2011 12:56:13 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:40338) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QF822-0003TN-Nl for guile-devel@gnu.org; Wed, 27 Apr 2011 12:56:12 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QF820-0007l5-Tr for guile-devel@gnu.org; Wed, 27 Apr 2011 12:56:06 -0400 Original-Received: from imr-db03.mx.aol.com ([205.188.91.97]:53720) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QF820-0007i5-Pk for guile-devel@gnu.org; Wed, 27 Apr 2011 12:56:04 -0400 Original-Received: from imo-ma02.mx.aol.com (imo-ma02.mx.aol.com [64.12.78.137]) by imr-db03.mx.aol.com (8.14.1/8.14.1) with ESMTP id p3RGt5A0019611; Wed, 27 Apr 2011 12:55:05 -0400 Original-Received: from idirectscm@aim.com by imo-ma02.mx.aol.com (mail_out_v42.9.) id 8.eac.13645288 (45324); Wed, 27 Apr 2011 12:55:01 -0400 (EDT) Original-Received: from smtprly-dc01.mx.aol.com (smtprly-dc01.mx.aol.com [205.188.170.1]) by cia-mc04.mx.aol.com (v129.10) with ESMTP id MAILCIAMC048-d1c64db84a6013; Wed, 27 Apr 2011 12:55:00 -0400 Original-Received: from webmail-m127 (webmail-m127.sim.aol.com [149.174.9.16]) by smtprly-dc01.mx.aol.com (v129.10) with ESMTP id MAILSMTPRLYDC017-d1c64db84a6013; Wed, 27 Apr 2011 12:54:56 -0400 X-AOL-IP: 98.185.24.91 In-Reply-To: <874o5k28e8.fsf@ossau.uklinux.net> X-MB-Message-Source: WebUI Original-Received: from 98.185.24.91 by webmail-m127.sysops.aol.com (149.174.9.16) with HTTP (WebMailUI); Wed, 27 Apr 2011 12:54:56 -0400 X-MB-Message-Type: User X-Mailer: AIM WebMail 33636-STANDARD X-AOL-SENDER: idirectscm@aim.com X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 205.188.91.97 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:12363 Archived-At: ----------MB_8CDD312F8A599BF_2538_2480B_webmail-m127.sysops.aol.com Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="us-ascii" >=20 > > From 80c6fd67b228ea8685def8ca4305bec9cdd98cd9 Mon Sep 17 00:00:00 2001 > [...] > > +@item -e @var{function} > > +Make @var{function} the @dfn{entry point} of the script. After loadi= ng > > +the script file (with @option{-s}) or evaluating the expression (with > > +@option{-c}), apply @var{function} to a list containing the program= name > > +and the command-line arguments---the list provided by the > > +@code{command-line} function. > > + > > +A @option{-e} switch can appear anywhere in the argument list, but Gu= ile > > +always invokes the @var{function} as the @emph{last} action it perfor= ms. > > +This is weird, but because of the way script invocation works under > > +POSIX, the @option{-s} option must always come last in the list. > > + > > +The @var{function} is most often a simple symbol that names a functio= n > > +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}. >=20 > 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? >=20 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. 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. > > +@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 compi= le > > +Scheme source files automatically. Starting with Guile 2.0, Scheme > > +source files will be compiled automatically, by default. >=20 > 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. >=20 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. --- =20 ----------MB_8CDD312F8A599BF_2538_2480B_webmail-m127.sysops.aol.com Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset="us-ascii" 
>=
;=20
> > From 80c6fd67b228ea8685def8ca4305bec9cdd98cd9 Mon Sep 17 00:00:0=
0 2001
> [...]
> > +@item -e @var{function}
> > +Make @var{function} the @dfn{entry point} of the script.  After=
 loading
> > +the script file (with @option{-s}) or evaluating the expression=
 (with
> > +@option{-c}), apply @var{function} to a list containing the pro=
gram name
> > +and the command-line arguments---the list provided by the
> > +@code{command-line} function.
> > +
> > +A @option{-e} switch can appear anywhere in the argument list,=
 but Guile
> > +always invokes the @var{function} as the @emph{last} action it=
 performs.
> > +This is weird, but because of the way script invocation works=
 under
> > +POSIX, the @option{-s} option must always come last in the list=
.
> > +
> > +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 @cod=
e{(@@
> > +@var{module-name} @var{symbol})}, and in that case, the symbol=
 is
> > +looked up in the module named @var{module-name}.
>=20
> 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?
>=20

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.

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.

> > +@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, Sc=
heme
> > +source files will be compiled automatically, by default.
>=20
> 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.
>=20

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.

---
----------MB_8CDD312F8A599BF_2538_2480B_webmail-m127.sysops.aol.com--