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

[Neil Jerram <neil@ossau.uklinux.net>]

Mark Harig <idirectscm@aim.com> 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