Formal comment #85 (defect) assorted small fixes and minor suggestions Reported by: Arthur A. Gleckler Component: other Version: 5.91 I finally had a chance to go through R5.91RS with a fine-toothed comb, and it was a real pleasure. Many, many thanks to the editors for all their hard work. This version of the standard will make for a huge improvement in the language, especially for practical uses. I've just finished putting together a large list of suggestions and fixes that I intend to submit formally over the next few days, I hope before the 15 Nov deadline. In this message, I'm submitting a batch of nearly trivial fixes and suggestions that I hope will be boring and not at all controversial. They're mostly spelling, grammar, punctuation, and typography errors or slight improvements along those lines. I used to be a professional copy editor, so some of them are nit-picky, but they should all be quick to implement. A few of these may have been covered by earlier contributions by other people, but I haven't been able to keep track of everything on the mailing list, so I hope you'll accept my apologies for any duplication. I hope that it's okay that I'm submitting these as a batch. Since they are all so minor and, I hope, non-controversial, I'm hoping that you won't mind. Please let me know right away if I should break them up. Here are the details: In <1. Overview of Scheme>, in the sentence "In Scheme, all data structures are passed by-reference," "by-reference" should not be hyphenated. It isn't being used to modify a noun. In <1.5. Procedures>, in the last paragraph, in "...takes a single number and add it to 42," "add" should be "adds." In <1.6. Procedure calls and syntactic keywords>, both uses of "second subform is" should be replaced with "rest of the subforms are." In <3.2.1. Formal account>, in the definition of "", angle brackets are not balanced on the right-hand side. In <5.5. Exception situations>, "the values returned depends" should be "the values returned depend." In <6.3.1. Primitive expression types>, under , capitalize the sentence in the comment and add a period at the end. We should follow basic English rules in all comments in examples. In <6.3.1. Primitive expression types>, the second paragraph in ends with two periods. Remove one. In <6.3.1. Primitive expression types>, in the example in , capitalize the comment and end it with a period. It is a sentence. In <6.3.2. Macros>, there are two periods separated by whitespace at the end of the second sentence, which ends "...or, simply, transformer." Remove one of the periods and the extra whitespace. In <6.3.2. Macros>, the first paragraph ends with "forms," but that should be "form." In <6.3.2. Macros>, the first bulleted item reads: A set of forms (define-syntax, section 9.3, let-syntax and letrec-syntax; see section 9.20)... The comma and semicolon are used in a confusing manner. The item would be better like this: A set of forms (define-syntax in section 9.3 and let-syntax and letrec-syntax in section 9.20)... In <6.4. Examples>, the indendation of the second use of "(car rest)" in the definition of find-dup is wrong. The form should align with (bound-identifier=? (car l) (car rest)) from the previous line. In <9.2. Definitions>, the fourth bullet reads: A syntax definition, see section 9.3. This is a run-on sentence. It should read: a syntax definition. See section 9.3. In <9.5.1. Literal expressions>, add a line break after "Syntax: should be a datum value" and before "Semantics." This will make the layout consistence with the rest of the document. In <9.5.2. Procedures>, in the Semantics paragraph, "...was evaluated is be extended...", the word "be" should be removed. In <9.5.2. Procedures>, in the Semantics paragraph, use the plural instead of "result(s)" and "is(are)." It's clearer and equally correct. In <9.5.3. Conditionals>, in the Semantics paragraph, use the plural instead of "value(s)" and "is(are)." It's clearer and equally correct. In <9.5.5. Derived conditionals>, the last sentence in the description of the syntax of case reads: The datums denoted by the s must not be distinct. Remove "not." They must be distinct. In <9.5.5. Derived conditionals>, the second sentence in the description of the semantics of case reads: Semantics: A case expression is evaluated as follows. is evaluated and its result is compared against each the datum denoted by each . The first use of the word "each" ("...each the datum...") should be removed. In <9.5.5. Derived conditionals>, add a line break before the descriptions of the semantics of and and of or. This will make the layout consistence with the rest of the document. In <9.5.7. Sequencing>, the word "intop" in the first bulleted paragraph should be "into." In <9.6. Equivalence predicates>, in the third and fourth bullets, "section see section" should just be "section." In <9.6. Equivalence predicates>, in the fourth bullet, there should be a closing parenthesis between "9.10" and "and yield." In <9.6. Equivalence predicates>, in the Rationale after the description of eq?, in "It is usually be possible...," the word "be" should be dropped. In <9.10.2. Numerical operations>, in , the first paragraph ends "... or monotonically nonincreasing #f otherwise." It should end "... or monotonically nonincreasing, and #f otherwise." (Add ", and".) In <9.10.2. Numerical operations>, in the description of zero?, etc. in , use "whether" throughout instead of "if," e.g. "The zero? procedure tests whether the number is = to zero...." In this case, "if" is clearer because it is less likely to begin a sentence like "The zero? procedure tests if the number is = to zero, and otherwise it sets the number." In <9.12. Pairs and lists>, the fourth paragraph reads: The empty list is a special object of its own type (it is not a pair); it has no elements and its length is zero. Making three separate sentences would be better: The empty list is a special object of its own type. (It is not a pair.) It has no elements and its length is zero. In <9.12. Pairs and lists>, the description of null? reads: Returns #t if obj is the empty list, otherwise returns #f. This is a run-on sentence. This would be better: Returns #t if obj is the empty list. Otherwise, returns #f. Similarly, the first sentence in the description of list? reads: Returns #t if obj is a list, otherwise returns #f. This would be better: Returns #t if obj is a list. Otherwise, returns #f. In <9.15. Strings>, the description of string=? reads: Returns #t if the strings are the same length and contain the same characters in the same positions, otherwise returns #f. This is a run-on sentence. This would be better: Returns #t if the strings are the same length and contain the same characters in the same positions. Otherwise, returns #f. In <9.15. Strings>, the example of string=? reads: (string=? "Strae" "Strasse") ==> #f A slightly better example would be to add the German ess-tsett character between the "a" and "e" in "Strae." That character is equivalent, here, to "ss", but the result should still be false. In <9.16. Vectors>, the description of vector? reads: Returns #t if obj is a vector, otherwise returns #f. This would be better: Returns #t if obj is a vector. Otherwise, returns #f. In <9.18. Control features>, in first paragraph of the description of call-with-current-continuation, "packages up" should be just "packages." "Up" adds no meaning. In <9.18. Control features>, in the Rationale after call-with-current-continuation, remove "extremely" in "...is extremely useful...." It doesn't add any meaning. In <9.19. Iteration>, the syntax for do uses "" where it should use "", which is the term used in the description in the third paragraph of Semantics. In <9.19. Iteration>, the title for the section on quasiquotation reads "sectionQuasiquotation." This looks like a TeX escaping error. In <9.19. Iteration>, a paragraph reads: If an (unquote-splicing . . . ) form appears inside a , then the s must evaluate to lists; the opening and closing parentheses of the list are then "stripped away" and the elements of the lists are inserted in place of the unquote-splicing form. "List" is used in the singular one time, but it should be plural there, too. In <9.19. Iteration>, there is an example that reads: `(( foo ,(- 10 3)) ,@(cdr '(c)) . ,(car '(cons))) Remove the extra space before "foo." In <9.20. Binding constructs for syntactic keywords>, the second sentence begins "Like begin...." It should begin "Like a begin form..." for symmetry with what it is being compared to, "...a let-syntax or letrec-syntax form...." In <9.20. Binding constructs for syntactic keywords>, the second paragraph describing the semantics of let-syntax begins: The
s of a let-syntax form are treated, whether in definition or expression context, as if wrapped in an implicit begin, see section 9.5.7. This is a run-on sentence. It should read: The s of a let-syntax form are treated, whether in definition or expression context, as if wrapped in an implicit begin. See section 9.5.7. In <9.21. syntax-rules>, a paragraph reads: Pattern variables match arbitrary input subforms and are used to refer to elements of the input. It is a syntax violation if the same pattern variable may appears more than once in a . Remove the word "may" in the second sentence. In <9.21. syntax-rules>, a paragraph begins "Pattern data and identifiers...." The final sentence of that paragraph has a spelling error: "consraints." 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?" In <10.2. Strings>, a paragraph reads: Since these procedures are locale-independent, they may not be completely appropriate for some locales. The word "completely" should be dropped as it doesn't add useful meaning. In <11. Bytes objects>, the fourth paragraph begins: Generally, the access procedures come in different flavors according to the size of the represented integer, and the endianness of the representation. Remove the comma before "and." The conjunction doesn't begin another independent clause. In <11. Bytes objects>, bytes->u8-list is used in examples long before it is described. It would be good to move its description before the examples. The <11. Bytes objects> is long. It should be divided into subsections for easier reference. In <11. Bytes objects>, there is a paragraph that reads: The procedures with native in their names employ the native endianness, and only work at aligned indices: k must be a multiple of 4.. The duplicate period should be removed. In <11. Bytes objects>, there is a paragraph that reads: The u8-list->bytes procedure returns a newly allocated bytes object whose elements are the elements of list list, in the same order. Analogous to list->vector. The second sentence is missing a verb. This would be better: It is analogous to list->vector. In <12. List utilities>, the ==> symbol in several of the examples for forall, exists, and fold-right overlap with other text. In <12. List utilities>, in the description of fold-left, it might be better to use a parameter name like "make" rather than "kons," which is a pun on "cons," which may not help new readers. In <12. List utilities>, in the description of fold-left, the parameters to the first example (x and count) are reversed: (fold-left (lambda (x count) (if (odd? x) (+ count 1) count)) 0 '(3 1 4 1 5 9 2 6 5)) ==> 6 The accumulator should be first. It just so happens that this example yields the same result because 5, the last element, is odd and (+ 5 1) is 6. To fix this, reverse the parameters. Even better, also replace the last 5 with 7 so that the coincidence doesn't happen. In <12. List utilities>, in the first example of remp, 2 should be removed from the result since it isn't even. It would be good to run all the examples in the report once more just to make sure that no errors have crept in. In <12. List utilities>, the first paragraph describing assp, etc. begins: Al (for "association list") must be the empty list or a chain of pairs where each car contains a pair of size according to the conditions specified below. This implies that a pair can have different sizes. It would be better to omit the part after "...contains a pair." The next paragraph explains this part clearly anyway. In <13. Records>, one paragraph reads: The two syntactic layers are designed to be fully compatible; the implicit-naming layer is simply a conservative extension of the explicit-naming layer. The design makes both explicit-naming and implicit-naming definitions reasonably natural while allowing a seamless transition between explicit and implicit naming. Remove the word "reasonably." It adds no meaning. In <13.1. Procedural layer>, a paragraph reads: A record type is considered immutable if each of its complete set of fields is immutable, and is mutable otherwise. The use of "each" here seems awkward. This might be clearer: A record type is considered immutable if all fields in its complete set of fields are immutable, and is mutable otherwise. In <13.1. Procedural layer>, a paragraph begins "The design allows the initial values..." and later mentions a "widget record." Remove the word "widget" since it doesn't add any meaning. Otherwise, explain what a widget is and why it might require finalization. In <13.1. Procedural layer>, a paragraph reads: For mutable records, but not necessarily for immutable ones, the following hold. (A record of an mutable record type is mutable; a record of an immutable record type is immutable.) "An mutable record" should be "a mutable record." In <13.2. Explicit-naming syntactic layer>, in the paragraph after the first bullet, there is a spelling error: "acccessor." 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? If so, choose a single name to use throughout so as not to confuse readers. 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. In <13.3. Implicit-naming syntactic layer>, the penultimate example is: ex3-instance* ==> ex3-i1 The initial asterisk is missing. In <13.4. Inspection>, the last sentence of the third paragraph should have a comma after record-type-descriptor, like this: If the program has access to the original rtd via make-record-type-descriptor or record-type-descriptor, it can still make use of the inspection procedures. In <13.4. Inspection>, the first sentence of the fourth paragraph reads: Any of the standard types mentioned in this report may or may not be implemented as a non-opaque record type. Rephrase to eliminate the double negative: Any of the standard types mentioned in this report may or may not be implemented as an opaque record type. In <14. Exceptions and conditions>, the final sentence reads: Scheme's condition system provides a standardized taxonomy of such descriptive objects, as well as facility for defining new condition types. How about rephrasing to refer back to the taxonomy that was just mentioned?: Scheme's condition system provides a standardized taxonomy of such descriptive objects, as well as facility for extending the taxonomy. In <14.1. Exceptions>, the last sentence in the fifth paragraph reads: It includes the dynamic-wind context, and the current exception handler. Remove the comma before "and." The conjunction doesn't begin another independent clause. In <14.1. Exceptions>, the sixth paragraph uses the phrase "other ('non-serious') condition." Perhaps it would be better to say simply "non-&serious condition," eliminating "other" and the parentheses. In <14.2.1. Condition objects>, add a period at the end of this sentence, which describes condition-type? : Returns #t if thing is a condition type, and #f otherwise In <14.2.1. Condition objects>, the second paragraph after the header line for make-compound-condition reads: The condition-ref procedure, when applied to a compound condition returns the value from the first of the condition s that has such a field. Add a comma between "condition" and "returns" in order to bracket the clause. 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 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. In <14.2.1. Condition objects>, after the header line for condition, a paragraph reads: Each must be of the form ( ) where is a field identifier from the definition of . x The are evaluated in some unspecified order; their values can later be extracted from the condition object via the accessors of the associated con- dition types or their supertypes. There are two errors here: There's an extraneous "x" after "." "The are..." should be plural: "The s are...." In <14.2.1. Condition objects>, after the header line for condition, a paragraph reads: The condition returned by condition is created by a call of form "Form" should be "the form." In <14.2.1. Condition objects>, after the header line for condition, the example of make-compound-condition should be re-indented. In <14.2.1. Condition objects>, after the header line for &condition, the first paragraph reads: This is the root of the entire condition type hierarchy. It has a no fields. Omit "a" in the last sentence. 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." In <15. I/O>, the first paragraph uses "input/output" where "input and output" might be clearer. In <15. I/O>, a paragraph reads: It is recommended, however, that an implementation provide all information about an exceptional situation in the condition object that is available at the place where it is detected. This is awkward. It's not the condition object that is being described as available; it's the information. This is clearer: It is recommended, however, that an implementation collect all information that is available about an exceptional situation at the place where it is detected and place it in the condition object. In addition, using the active voice would be better than "it is recommended," but I can understand why the editors might not want to say "we recommend." In <15. I/O>, the header line for &i/o-read is missing this paragraph before the example: This condition type could be defined by In <15. I/O>, a paragraph under &i/o-file-already-exists reads: A condition of this type specifies that an operation tried to operate on an existing named file under the assumption that it does not exist. "Does" should be "did" for tense agreement. In <15. I/O>, the paragraph after the example definition of &i/o-file-exists reads: A condition of this type specifies that an operation tried to operate on an non-existent named file under the assumption that it exists. "Exists" should be "existed" for tense agreement. In <15.2. Primitive I/O>, the second paragraph ends with "blocking-I/O." Remove the hyphen since this phrase isn't modifying a noun. In <15.2.2. File options>, the Rationale paragraph reads: Rationale: The flags specified above represent only a common subset of meaningful options on popular platforms. The file-options form does not restrict the s so that implementations can extend the file options by platform-specific flags. Add a comma after "s" and remove "that": Rationale: The flags specified above represent only a common subset of meaningful options on popular platforms. The file-options form does not restrict the s, so implementations can extend the file options by platform-specific flags. In <15.2.3. Readers and writers>, the first paragraph contains this sentence: Although some reader and writer objects might conceivably have something to do with files or devices, programmers should never assume it. Replace the last word, "it," with "so." In <15.2.4. I/O buffers>, the first paragraph contains this sentence: Callers of the procedures from the (r6rs i/o primitive) library are encouraged to use bytes objects created by make-i/o-buffer, because they might have alignment and placement characteristics that make reader-read! and writer-write! more efficient. Remove the comma before "because." In both <15.2.5 Readers> and <15.2.6 Writers>, the first paragraphs currently read: The purpose of reader objects is to represent the output of arbitrary algorithms in a form susceptible to imperative I/O. and: The purpose of writer objects is to represent the input of arbitrary algorithms in a form susceptible to imperative I/O. The word "amenable" would be better than "susceptible" here. "Susceptible" makes it sound like imperative I/O is a disease or misfortune. In <15.2.5. Readers>, the bulleted paragraph on end-position refers to the "next" end of file. It would be best to omit "next," but if it must remain, it should be explained here. Similarly in <15.2.6. Writers> after the header line for writer-end-position. In <15.2.5. Readers>, a paragraph reads: For a reader created by mmake-simple-reader, reader-end-position tail-calls the end-position procedure of reader. Remove the extra "m" at the beginning of make-simple-reader here. In <15.2.5. Readers>, the last sentence after the header line for open-bytes-reader reads: The effect of modifying the contents of bytes, after open-bytes-reader has been called, on the reader is unspecified. The delayed "on the reader" makes this sentence awkward. This would be clearer: If the contents of bytes is modified after open-bytes-reader has been called, the effect on the reader is unspecified. In <15.2.5. Readers>, the third paragraph after the header line for make-simple-writer contains this sentence: It is encouraged that these procedures check that their arguments are of the appropriate types. "It is encouraged that" is awkward. "It is recommended," like in the rest of the report, would be better, but "we recommend" would be best. In <15.2.5. Readers>, the bulleted paragraph describing write! contains this sentence: Bytes may or may not be a bytes object returned by make-i/o-buffer. It would be best to specify that it must, however, be some form of bytes object: Bytes must be a bytes object, but it may or may not be one returned by make-i/o-buffer. In <15.2.5. Readers>, the paragraph after the header line for writer-id begins "Returns string naming the writer...." Add "a" between "returns" and "string." In <15.2.5. Readers>, the last sentence in the paragraph after the header line for open-bytes-writer reads: The result writer supports the writer-get-position, writer-set-position!, and writer-end-position operations. operations. Remove the extraneous second "operations" and period. In <15.2.8. Examples>, the identifier make-writer is used when make-simple-writer was intended. In <15.3. Port I/O>, the last paragraph reads: This section uses the input-port, output-port, port parameter names for arguments that must be input ports (or combined input/output ports), output ports (or combined input/output ports), or any kind of port. Add "and" before "port parameter names." In <15.3.2. Buffer modes>, the first paragraph mentions the parameter buffer-name when it means buffer-mode. In <15.3.3. Text transcoders>, the first paragraph after the header line for make-transcoder reads: Codec must be a codec, eol-style, if present, an eol-style symbol, and handling-mode, if present, an error-handling-mode symbol. Semicolons should be used here because two uses for commas are being intermixed: Codec must be a codec; eol-style, if present, an eol-style symbol; and handling-mode, if present, an error-handling-mode symbol. Alternately, of course, this could be broken into three sentences. In <15.3.5. Input ports>, the paragraph after the header line for open-string-input-port ends with this sentence: The effect of modifying string, after open-string-input-port has been called, on the returned port is unspecified. The delayed "on the returned port" makes this sentence awkward. This would be clearer: If string is modified after open-string-input-port has been called, the effect on the returned port is unspecified. In <15.3.6. Output ports>, the last sentence in the paragraph after header line for get-output-bytes reads: If the returned bytes object is modified, the the effect on output-port is unspecified. Remove the duplicate "the." In <15.3.6. Output ports>, the last sentence in first the paragraph after header line for get-output-string reads: In either case, decoding errors are always handled analogously to the replace error-handling mode: the first byte of each invalid encoding is skipped and decoded as the U+FFFD replacement character. Replace "either" with "any" here since the previous sentences refer to three cases, not just two. Make the same change in the last sentence in the paragraph after header line for call-with-string-output-port. In <15.4. Simple I/O>, the last sentence in the paragraph after the header line for call-with-output-file reads: If proc does not return, then the port is not closed automatically, unless it is possible to prove that the port will never again be used for an I/O operation. This might be interpreted to mean that implementations must close the port automatically if it is possible to provide that it will not be used again for an I/O operation. However, I imagine that that must be optional. Therefore, rephrase the sentence: If proc does not return, then the port is not closed automatically, except perhaps if it is possible to prove that the port will never again be used for an I/O operation. In <15.4. Simple I/O>, in the entry for newline, there is a line break between "#" and "linefeed." This looks like a TeX escaping error. In <16.3.2. Signalling fixnum operations>, the entry for fxcopy-bit-field contains this sentence: Moreover, or fx2 must be less than or equal to fx. Remove the first "or." In <16.4. Flonums>, the paragraph under the header line for fl* contains this sentence: For implementations that represent flonums as IEEE binary floating point numbers, the meaning of "best" is reasonably well-defined by the IEEE standards. Remove "reasonably" here. It adds no meaning. In <17.4. Parsing input and producing output>, a long paragraph in the entry for syntax ends with this sentence: It is a syntax violation if the consraints of this paragraph are not met. There is a spelling error: "consraints". In <17.4. Parsing input and producing output>, there are three example forms after this paragraph: The following definitions of or illustrate syntax-case and syntax. The second is equivalent to the first but uses the the #' prefix instead of the full syntax form. However, this paragraph only describes the first two forms. There is no paragraph describing the third example, which defines case. In <18.1. Constructors>, the second paragraph in the entry for make-hash-table reads: Both the hash function hash-function and the equivalence function equiv should behave like pure functions on the domain of keys. For example, the string-hash and string=? procedures are permissible only if all keys are strings and the contents of those strings are never changed so long as any of them continue to serve as a key in the hash table. Furthermore any pair of values for which the equivalence function equiv returns true should be hashed to the same exact integers by hash-function. There are two errors here: "Continue" should be "continues" to agree with "any." A comma is missing after "furthermore." In <18.2. Procedures>, the paragraph after the header line for hash-table? reads: Returns #t if hash-table is a hash table, otherwise returns #f. This is a run-on sentence. It should read: Returns #t if hash-table is a hash table. Otherwise, returns #f. In <18.2. Procedures>, the paragraph after the header line for hash-table-contains? reads: Returns #t if hash-table contains an association for key, otherwise returns #f. This is a run-on sentence. It should read: Returns #t if hash-table contains an association for key. Otherwise, returns #f. In <19. Enumerations>, the second paragraph after the header line for enum-set=? reads: The enum-set-subset? procedure returns #t if the universe of enum-set1 is a subset of the universe of enum-set2 (considered as sets of symbols) and every element of enum-set1 is a member of its second. It returns #f otherwise. Replace "its second" with "enum-set2." In <20.3. Delayed evaluation>, in the entry for force, it's excessive to include "(see delay, section 20.3)" since that refers to the immediately preceding paragraph. In <20.4. Command-line access>, the last paragraph typesets R6RS incorrectly, resulting in "6rs" with a circle over the 6. This looks like a TeX escaping error. In , the "k" in the "runge-kutta-4" procedure name is capitalized in two different places, but this is a case mismatch with the definition, according the R6RS. If Scheme is going to become case sensitive, we should be consistent here. 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. That's the end of this batch. Again, thanks to the editors for all their work making the new standard a great one. RESPONSE: Most of these suggestions will be adopted in the next draft of the report, except where discussed on the r6rs-discuss mailing list.