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: Sun, 24 Apr 2011 17:58:53 -0400 Message-ID: <8CDD0E1EF6EF23A-1820-110A6@webmail-m029.sysops.aol.com> References: <8CDD0063C9BEB29-FC8-5987@web-mmc-d08.sysops.aol.com><8CDD0D662A18273-1820-10289@webmail-m029.sysops.aol.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="--------MB_8CDD0E1EF76165D_1820_1D7C1_webmail-m029.sysops.aol.com" X-Trace: dough.gmane.org 1303682362 7867 80.91.229.12 (24 Apr 2011 21:59:22 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sun, 24 Apr 2011 21:59:22 +0000 (UTC) Cc: guile-devel@gnu.org To: wingo@pobox.com Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sun Apr 24 23:59:14 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 1QE7Kk-0003UJ-5x for guile-devel@m.gmane.org; Sun, 24 Apr 2011 23:59:14 +0200 Original-Received: from localhost ([::1]:34330 helo=lists2.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QE7Ki-0001bV-SC for guile-devel@m.gmane.org; Sun, 24 Apr 2011 17:59:12 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:59447) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QE7Kf-0001an-27 for guile-devel@gnu.org; Sun, 24 Apr 2011 17:59:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QE7Kd-0000af-NF for guile-devel@gnu.org; Sun, 24 Apr 2011 17:59:08 -0400 Original-Received: from imr-ma02.mx.aol.com ([64.12.206.40]:44607) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QE7Kd-0000ab-Jy for guile-devel@gnu.org; Sun, 24 Apr 2011 17:59:07 -0400 Original-Received: from imo-ma03.mx.aol.com (imo-ma03.mx.aol.com [64.12.78.138]) by imr-ma02.mx.aol.com (8.14.1/8.14.1) with ESMTP id p3OLx0CW014205; Sun, 24 Apr 2011 17:59:00 -0400 Original-Received: from idirectscm@aim.com by imo-ma03.mx.aol.com (mail_out_v42.9.) id w.eac.134d1d93 (45072); Sun, 24 Apr 2011 17:58:55 -0400 (EDT) Original-Received: from smtprly-dc03.mx.aol.com (smtprly-dc03.mx.aol.com [205.188.170.3]) by cia-mc02.mx.aol.com (v129.10) with ESMTP id MAILCIAMC024-d3a24db49d1d375; Sun, 24 Apr 2011 17:58:55 -0400 Original-Received: from webmail-m029 (webmail-m029.sim.aol.com [64.12.101.212]) by smtprly-dc03.mx.aol.com (v129.10) with ESMTP id MAILSMTPRLYDC032-d3a24db49d1d375; Sun, 24 Apr 2011 17:58:53 -0400 X-AOL-IP: 98.185.24.91 In-Reply-To: X-MB-Message-Source: WebUI Original-Received: from 98.185.24.91 by webmail-m029.sysops.aol.com (64.12.101.212) with HTTP (WebMailUI); Sun, 24 Apr 2011 17:58:53 -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: 64.12.206.40 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:12332 Archived-At: ----------MB_8CDD0E1EF76165D_1820_1D7C1_webmail-m029.sysops.aol.com Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" On Sun, Apr 24, 2011 at 11:00:16PM +0200, Andy Wingo wrote: > Hi Mark, >=20 > Thanks for the revisions. >=20 > On Sun 24 Apr 2011 22:36, Mark Harig writes: >=20 > > On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote: > >> your patches should be "atomic" > > > > "3. No patch introduces a regression: after applying any > > initial part of the series, the resulting project still > > compiles and works, and has no bugs that it didn=E2=80=99t have > > before." >=20 > Right, at the end of applying all of your patches, I'm sure that's the > case; however the first patch adds an @include without adding the > appropriate file, so applying just the first patch without the following > two would yield a project that doesn't compile. I just meant that you > need to squish the first two or three of them together. I can do that > when I apply them, though. >=20 What do guile developers normally do when generating the patches? ('git format-patch origin' is generating three separate files. Do you concatenate the patch files that 'git' emits?) Please let me know if there is a documented recipe that guile-devel uses that I can follow for future changes. > By @itemx I just meant to do instead of: >=20 > > +@item -s @var{script} @var{arg...} >=20 > you would >=20 > @item @var{script} @var{arg...} > @itemx -s @var{script} @var{arg} >=20 > The other option would be >=20 > @item [-s] @var{script} @var{arg} >=20 > which is not as clear IMO. I feel that it's important to have a good > example up there, and making it clear that it's OK to just invoke Guile > as "guile foo.scm" is important. But your description is good too. Thanks for the clarification. I will add the two-line @item/@itemx pair. >=20 > > +For compatibility with some versions of Guile 1.4, you can also use= the > > +form @code{(symbol ...)} (that is, a list of only symbols that doesn'= t > > +start with @code{@@}), which is equivalent to @code{(@@ (symbol ...) > > +main)}, or @code{(symbol ...) symbol} (that is, a list of only symbo= ls > > +followed by a symbol), which is equivalent to @code{(@@ (symbol ...) > > +symbol)}. We recommend to use the equivalent forms directly since th= ey > > +correspond to the @code{(@@ ...)} read syntax that can be used in > > +normal code. See @ref{Using Guile Modules} and @ref{Scripting > > +Examples}. >=20 > Again, probably worth eliding the deprecated 1.4 stuff... >=20 It's not clear to me what you mean here. Please provide the text that you would like. (I did not review the "command-line options" section for content because my original proposal was to keep that section and add a missing "environment variables" section.) > > +@item --auto-compile > > +Compile source files automatically (default behavior). > > + > > +@vnew{2.0} > > + > > +@item --no-auto-compile > > +Disable automatic source file compilation. > > + > > +@vnew{2.0} >=20 > Need --fresh-auto-compile here too >=20 > > +@item GUILE_AUTO_COMPILE > > +@vindex GUILE_AUTO_COMPILE >=20 > Need to note GUILE_AUTO_COMPILE=3Dfresh, and @ref to Compilation >=20 I do not know what that option does (other than a guess). There has been no update to the Guile manual page or the reference manual mentioning it. It appears that this "fresh" feature (no pun intended) has been added since Guile 2.0.0. 'guile --help' does not mention it for Guile 2.0.0. I will add the text to update my patches, if wanted, but I need for someone to provide me with the text that they would like (i.e., the specification for what the user should know). Alternatively, they could be added independently by a separate patch. Once the "environment variables" section has been added to the Guile Reference Manual, developers should be able to add updates about them as part of an "atomic" patch that describes the new feature and implements it. Depending on the change, this might involve updating: 1) The text of the Guile Reference Manual 2) The text provided by Guile's "--help" option 3) The text of the Guile manual page 4) The NEWS file: to describe new features and mark features as deprecated or obsolete. -- =20 ----------MB_8CDD0E1EF76165D_1820_1D7C1_webmail-m029.sysops.aol.com Content-Transfer-Encoding: quoted-printable Content-Type: text/html; charset="utf-8" 

On Sun, Apr 24, 2011 at 11:00:16PM +0200, Andy Wingo wrote:
> Hi Mark,
>=20
> Thanks for the revisions.
>=20
> On Sun 24 Apr 2011 22:36, Mark Harig <idirectscm@aim.com> write=
s:
>=20
> > On Sun, Apr 24, 2011 at 04:33:44PM +0200, Andy Wingo wrote:
> >> your patches should be "atomic"
> >
> > "3. No patch introduces a regression: after applying any
> > initial part of the series, the resulting project still
> > compiles and works, and has no bugs that it didn=E2=80=99t have
> > before."
>=20
> Right, at the end of applying all of your patches, I'm sure that's th=
e
> case; however the first patch adds an @include without adding the
> appropriate file, so applying just the first patch without the follow=
ing
> two would yield a project that doesn't compile.  I just meant that yo=
u
> need to squish the first two or three of them together.  I can do tha=
t
> when I apply them, though.
>=20

What do guile developers normally do when generating the
patches?  ('git format-patch origin' is generating three
separate files.  Do you concatenate the patch files that
'git' emits?)  Please let me know if there is a documented
recipe that guile-devel uses that I can follow for future
changes.

> By @itemx I just meant to do instead of:
>=20
> > +@item -s @var{script} @var{arg...}
>=20
> you would
>=20
> @item @var{script} @var{arg...}
> @itemx -s @var{script} @var{arg}
>=20
> The other option would be
>=20
> @item [-s] @var{script} @var{arg}
>=20
> which is not as clear IMO.  I feel that it's important to have a good
> example up there, and making it clear that it's OK to just invoke Gui=
le
> as "guile foo.scm" is important.  But your description is good too.

Thanks for the clarification.  I will add the two-line @item/@itemx pair.

>=20
> > +For compatibility with some versions of Guile 1.4, you can also=
 use the
> > +form @code{(symbol ...)} (that is, a list of only symbols that=
 doesn't
> > +start with @code{@@}), which is equivalent to @code{(@@ (symbol=
 ...)
> > +main)}, or @code{(symbol ...)  symbol} (that is, a list of only=
 symbols
> > +followed by a symbol), which is equivalent to @code{(@@ (symbol=
 ...)
> > +symbol)}.  We recommend to use the equivalent forms directly si=
nce they
> > +correspond to the @code{(@@ ...)}  read syntax that can be used=
 in
> > +normal code.  See @ref{Using Guile Modules} and @ref{Scripting
> > +Examples}.
>=20
> Again, probably worth eliding the deprecated 1.4 stuff...
>=20

It's not clear to me what you mean here.  Please provide the
text that you would like.  (I did not review the
"command-line options" section for content because my
original proposal was to keep that section and add a missing
"environment variables" section.)

> > +@item --auto-compile
> > +Compile source files automatically (default behavior).
> > +
> > +@vnew{2.0}
> > +
> > +@item --no-auto-compile
> > +Disable automatic source file compilation.
> > +
> > +@vnew{2.0}
>=20
> Need --fresh-auto-compile here too
>=20
> > +@item GUILE_AUTO_COMPILE
> > +@vindex GUILE_AUTO_COMPILE
>=20
> Need to note GUILE_AUTO_COMPILE=3Dfresh, and @ref to Compilation
>=20

I do not know what that option does (other than a guess).
There has been no update to the Guile manual page or the
reference manual mentioning it.

It appears that this "fresh" feature (no pun intended) has
been added since Guile 2.0.0.  'guile --help' does not
mention it for Guile 2.0.0.  I will add the text to update
my patches, if wanted, but I need for someone to provide me
with the text that they would like (i.e., the specification
for what the user should know).  Alternatively, they could
be added independently by a separate patch.

Once the "environment variables" section has been added to
the Guile Reference Manual, developers should be able to add
updates about them as part of an "atomic" patch that
describes the new feature and implements it.  Depending on
the change, this might involve updating:

   1) The text of the Guile Reference Manual
   2) The text provided by Guile's "--help" option
   3) The text of the Guile manual page
   4) The NEWS file: to describe new features and mark
   features as deprecated or obsolete.

--
 ----------MB_8CDD0E1EF76165D_1820_1D7C1_webmail-m029.sysops.aol.com--