[r6rs-discuss] assorted small fixes (spelling, grammar, punctuation, and typo fixes; rephrasing; etc.)

From: Arthur A. Gleckler <arthur>
Date: Mon Nov 20 12:52:33 2006

On Nov 20, 2006, at 4:47 AM, Michael Sperber wrote:

>> * In <9.22. Declarations>, a sentence says "...the
>> implementation... may terminate the computation in an unpleasant
>> fashion...." This is an amusing way to describe it. It makes me
>> imagine high-voltage electricity through the keyboard, etc. Would it
>> be accurate to leave out "in an unpleasant fashion," leaving just
>> "may
>> terminate the computation?"
>
> I think the unpleasantness was very much intentional, and meant to
> wake up the reader to the almost certainly undesirable outcome here.
> In a computer-related context, "terminate" sounds almost benign, and
> would more likely to be ignored. (And who knows about the high
> voltage?)

Makes sense. I mostly wrote this comment because it sounded so amusing.

>> * In <13.2. Explicit-naming syntactic layer>, in the examples after
>> the description of record-constructor-descriptor, some protocol
>> expressions use the variable p and some use the variable new. Isn't
>> this inconsistent?
>
> No, the distinction is explained:

Okay.

>> * In <13.2. Explicit-naming syntactic layer>, in the final
>> define-record-type example after the description of
>> record-constructor-descriptor, there is extra whitespace on the three
>> lines of the call to new. Remove them for consistency.
>
> I can't find this one. What's the name of the record type?

It's the last one: unit-vector.

Sorry, I'll use page numbers next time. I was afraid that they would
change by the time I collected all my comments and submitted them.

>> * In <14.2.1. Condition objects>, the Semantics description for
>> define-condition-type uses the verb "defines... to" repeatedly, e.g.:
>>
>> The define-condition-type form also defines <predicate> to a
>> predicate that identifies conditions associated with that type, or
>> with any of its subtypes.
>>
>> This is awkward. It would be better either to use "binds" instead of
>> "defines" or to use "defines... to be" throughout.
>
> Could you explain why this is awkward? To my mind, this "defines" is
> exactly right as it refers to the underlying semantics, which (as far
> as binding is concerned) acts precisely like `define'. "Binding" is
> more general, and thus more vague in this context.

"Defines... to" is not really English. That preposition isn't used
with define. I think "defines... to be" would be just fine. In that
case, "to" isn't a prepoistion, but is the infinitive, which is fine.

>> * In <14.2.1. Condition objects>, after the header line for
>> condition, the example of make-compound-condition should be
>> re-indented.
>
> I can't find that one. Which example is this exactly?

About half-way down the left column on p. 76, this appears:

(make-compound-condition
   (make-condition (condition-type) '<field-name> <value> ...)
   . . . )

All the other examples are indented slightly, but this one isn't.

>> * In <14.3. Standard condition types>, the paragraph after the header
>> line for &non-continuable reads:
>>
>> This type denotes that an exception handler invoked via
>> raise returned.
>>
>> The word "is" should appear before "returned."
>
> No. :-)

Oh, I see. I was looking for "is returned" or "has returned" or
"returned FOO." You're right that "returned" by itself is correct.
However, I found it misleading. I suggest "has returned" to make
this read even more smoothly.

>> * The index is missing entries for define-condition-type and
>> &eval-definition. Add these and check for other missing entries.
>> Now
>> that the document is longer, a complete index makes a big difference.
>
> `&eval-definition' is actually a mistake; it's meant to be `&syntax'.

Ah, I see. In any case, if there's something automatic you can do to
make sure that everything that should be in the index is actually
there, you should. A complete index is a huge gift to the community.

Thanks for all your replies to my comments!
Received on Mon Nov 20 2006 - 12:52:08 UTC