Hi,

Here are my comments for chapter 6. Due to the length of this chapter,
this message is even longer than the ones I sent before... so here we go:

6. Standard procedures
======================

I find the statment that "the initial [...] Scheme environment is empty"
to be a bit ambiguous. Does that mean that there is no bound identifier
at all? Does this include the primitive expressions and "define"? How is
it that "import" is available then? I have the feeling that this needs
to be clarified.

6.3.2 Pairs and lists
=====================

It should be clarified whether "list-copy" copies recursively or if the
structures referred to by the cars are shared (I strongly suspect the
latter).

6.3.4 Characters
================

I'm missing a reference to the Unicode standard (or, while we're at it,
ASCII).

I would make "Characters are written [...]" the first sentence of a new
paragraph as it doesn't relate to the ASCII/Unicode matter discussed in
the preceding sentences anymore. (Yes, I am kind of a perfectionist...)

The remarks about Turkic casing pairs not being used for char-upcase /
char-downcase are somewhat disturbing. I needed to google to find out
about the conflicts about Latin and Turkic casing. To the uninformed,
these sentences just look anti-Turk at worst... I think this should be
moved to a note at the bottom, *including a rationale*. A proposal:

"Note: char-upcase and char-downcase must not use Turkic casing pairs as
they conflict with the casing pairs usually used in the Latin alphabet.
For instance, the Turkic alphabet considers the character "i" (U+0049)
to be the lowercase version of the uppercase dotted "İ" (U+0131) instead
of the "I" (U+0069) as known from the Latin alphabet."

Another possibility to just say that implementations "should not" use
Turkic casing pairs, but may do so if the environment it is running in
demands it (in practice: if the system locale is Turkish).

6.3.5. Strings
==============

I like how the description of the new string escape sequences is
embedded into the text. However, they need examples!

What I said about Turkic mappings above also applies to string-upcase /
string-downcase. Also, I would replace the phrase "What is more, [...]"
with something nicer and more useful, educationally. A proposal:

"[...] Like char-upcase and char-downcase, they must/should not use
Turkic case mappings. Note that these functions differ from applying
char-upcase or char-downcase on every character individually, as a few
characters [...]"

In the description of "make-string" and "string-fill!", what are the
"elements of a string"? Characters? Code points? Bytes? This is very
unclear. Specifically, can a string created via (make-string k) hold any
string k logical Unicode characters, and does "string-fill" applied on a
string of length k to yield a string of the same length (independent of
the number of bytes needed to represent the fill character)? These
things are crucial for portability among Unicode supporting Schemes.

6.3.6. Vectors
==============

Like in the case of "list-copy", the deepness of the "vector-copy"
operation is not specified.

6.3.7 Bytevectors
=================

"8-bit bytes" is redundant; "bytes" is enough, especially as the next
sentence defines them in the context of bytevectors.

It's great that the bytevector procedures defined here seem to be all
fully compatible to R6RS! However, I need to say that I very, very much
dislike the use of #u8(...) as external representation instead of R6RS'
#vu8(...). This is pure bikeshedding that does nothing but complicating
the lifes of implementors.

In general, I think it would be a good idea to make all the subsections
of 6.3 top-level sections of chapter 6. There is more in 6.3 now than a
single section should have, and the table of contents would also greatly
benefit.

6.4. Control features
=====================

Following the restructuring proposal above, "procedure?" could move to a
new top-level section. ("Control features" was never a good place for it.)

For consistency with the other descriptions in the same section, it
should be "Apply calls proc [...]" instead of "Calls proc [...]" with
implicit subject.

Now that it is defined what "map" does for differently long lists, there
should be an example illustrating it. For instance, one could alter the
example

(map + '(1 2 3) '(4 5 6))  ==> (5 7 9)

to read

(map + '(1 2 3) '(4 5 6 7))  ==> (5 7 9)

As the description of "force" discusses "delay" / "lazy" / "force" in
detail, it seems strange that it doesn't introduce the term "promise"
but refers to section 4.2.5 for that which, in turn, points to this
section for a detailed explanation. This should all be at one spot; I
propose to move everything there is to know about "delay" / "lazy" /
"force" to move to this section, and reduce the descriptions in 4.2.5 to
be not much more than forward references.

The description of "make-parameter" could be improved. It would be nice
if the "parameter object" notion would be introduced right after the
first mention of the term, not a few sentences earlier. Also, it is very
unfortunate that the question what parameter objects are actually for is
not answered until the very end of the description, even after the
possible implementation is presented. This needs a bit of reworking. A
proposal:

"Returns a new _parameter object_, which is a procedure that, if called
without arguments, returns its associated value. Initially, this value
is the one returned by the call (_converter_ _init_), or _init_ if
_converter_ is not specified. However, the associated value can be
temporarily changed with parameterize (see section 4.2.6).

The effect of passing arguments to a parameter object is explicitly
implementation-dependent.

Parameter objects can be used [...]

Here is a possible implementation [...]"

(Terms surrounded by an underscore are meant to be italic)

(By the way: shouldn't it be an error if "converter" returns multiple
values? I still hope that we'll go the CL way one dayand specify that
unused return values are ignored, but this is not the case currently.)

6.5. Exceptions
===============

IMO, the whole notion of "exceptions" is not really introduced; there
seems to be the assumption that this is already known. IMO, an
introductory, high-level overview might be nice here.

In the description for "raise-continuable", it should most probably say
"the equivalent to [...] raise", not "raise-continuable".

In the description of "error", the second sentence should say "Calls
raise [...]" instead of just "raise [...]". Also, "irritants" should be
highlighted as being a newly introduced term.

Other than that, I like the text in this section!

6.7 Input and output
====================

Given that that ModulesMedernach was (weakly) voted for, there should be
no trace left of (scheme io), but several procedures are still marked as
being "io module" procedures. It seems as if the section hasn't yet been
updated in this regard.

As there'll most probably be file-specs in the big language, we could go
ahead and just specify a behavior for "open-output-file" on
already-existing files (proposal: overwrite). Other behaviors could then
be specified with what can be found in the large report.

There is a newline missing before "(close-input-file port)".

The description of "close*-port" says that "is an error to apply the
first two procedures to a port which is not an input or output port",
but as "close-port" is listed at the beginning, it should be "the last
port". It would also be a good idea to say something like "Closes the
resource [...]" instead of "Closes the file [...]" as the former is more
general and doesn't feel restricted to file ports.

This suggestion might be a bit silly, but the descriptions of
"get-string-output" and "get-bytevector-output" might do good to say
that returned object contains the output characters / bytes *in the
order they were output*... but, well, maybe that's all too obvious. ;)

What is that note about the possibility of "u8-ready?" returning #t
while "read-char" might hang? I guess this is a left-over from the
previous drafts' combined character / binary ports. (By the way, I think
that character ports should be named "textual ports" for term
compatibility with R6RS, but there's already a ticket for that AFAIK.)

The description of "flush-output-port" refers to its argument as
"output-port" in the first sentence, but it is called "port".

6.7.4 System interface
======================

The description of "current-jiffy" contains so much "arbitrary" that you
could think it is a joke. ;) A proposal:

"Returns the number of _jiffies_ that elapsed since an arbitrary,
implementation-defined epoch. A jiffy is an implementation-defined
fraction of a second which is defined by the return value of the
jiffies-per-second procedure. The starting epoch is guaranteed to be
constant during a run of the program, but may vary between different
runs of a program."

In addition, a use case where current-jiffy is useful (and more useful
than "current-second") should be mentioned in a second paragraph.

That's it. Keep up the good work! More than enough said. ;)

Regards,
Denis

_______________________________________________
Scheme-reports mailing list
Scheme-reports@scheme-reports.org
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports