Re: [Scheme-reports] Draft 3 Comments: Chapter 6

[John Cowan <cowan@x>]

Denis Washington scripsit:

> 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).

It is the latter, per SRFI-1.  Fixed on trunk.

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

References will be updated.

> 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...)

Fixed on trunk.

> 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:

Changed to speak of language-sensitive rather than Turkic
casing/folding.  No rationale is given, but I don't think it's
really needed.

> 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).

These procedures are not meant to be locale-sensitive: different
locale-sensitive procedures would be appropriate for massaging natural
language text.

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

Editorial ticket filed.

> 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.

Yes, definitely characters.  Fixed on trunk.

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

I think it unlikely that people will assume a deep copy.  Still, I added
a sentence on trunk.

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

Fixed on trunk.

> 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.

As you noted later, it's SRFI-4 compatible.

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

Discussed in a separate post.

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

Fixed on trunk.

> 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)

Fixed on trunk.

> 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.

For better and worse, we are explicitly following the R5RS layout, and
syntax is in Chapter 4, procedures in Chapter 6.  I have reworded the
first sentence to read "Forces the value of a \var{promise} created by
\ide{delay} or \ide{lazy}".

> The description of "make-parameter" could be improved.

I have adopted a close variant of your suggestion.

> (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.)

Some implementations really don't want you to return the wrong number of
values, and I don't think we can make them non-standard.

> 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.

Editorial ticket filed.

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

No, it means what it says: the continuation of the call to the handler
is the same as that of the call to raise-continuation.  I invite the
proposal of better wording, though.

> 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.

Fixed on trunk.

> 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.

Indeed.  There will probably be a revote.

> 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                                                                 

Substantive ticket filed.

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

Fixed on trunk.

> 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.

Fixed on trunk.

> 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. ;)

Fixed on trunk.

> 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.                 

There is nothing to *forbid* combined character/binary ports.  But I
agree that the note is no longer very useful and have removed it.

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

That's pretty much true of all the port procedures.

> 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."

Adopted.

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

Editorial ticket filed.  Note that one can never be sure that
current-jiffy is more useful.

-- 
You know, you haven't stopped talking           John Cowan
since I came here. You must have been           http://www.ccil.org/~cowan
vaccinated with a phonograph needle.            cowan@x
        --Rufus T. Firefly

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