[Scheme-reports] Draft 3 Comments: Chapter 6

[Denis Washington <denisw@x>]

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@x
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports