Re: Patch: New section "Invoking Guile" for chapter "Programming in Scheme"

[Mark Harig <idirectscm@aim.com>]

[-- Attachment #1: Type: text/plain, Size: 2787 bytes --]



> 
> > From 80c6fd67b228ea8685def8ca4305bec9cdd98cd9 Mon Sep 17 00:00:00 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 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 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 @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.

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, 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.

---

 

[-- Attachment #2: Type: text/html, Size: 3411 bytes --]