|
[Scheme-reports] Draft 3 Comments: Chapter 5 Denis Washington (01 Aug 2011 18:02 UTC)
|
|
Re: [Scheme-reports] Draft 3 Comments: Chapter 5
Alex Shinn
(03 Aug 2011 06:22 UTC)
|
Hi,
I finally found the time to review chapter 5. Here is what I noticed:
5.1. Programs
=============
From what I can see, this is mostly R5RS (except for small adjustments
to mention modules) and inherits a certain lack of preciseness from it.
Specifically, it is not really said what the mentioned "top level" of a
program actually is (it is somewhat deducible from the context, but
"somewhat deducible" isn't quite enough for a standards document IMO). I
know I have pointed to R6RS more than enough in my last review message,
but its section 8 ("Top-level Programs") might be helpful here.
5.2. Definitions
================
"Some implementations of Scheme use an initial environment in which all
possible variables are bound to locations, most of which contain
undefined values. [...]" I am not sure if this is needed. I know, it's
from R5RS and not added to the draft, but this sounds more like the old
approach of a Scheme "report" in the original sense (as in, observation
of the state of the art) rather than its modern interpretation as
standards document. I already noticed something similar in chapter 2
(the title "Lexical conventions" rather than "rules" or "syntax", or
"The precise rules for forming identifiers vary among implementations of
Scheme [...]" in section 2.1).
We should ask ourselves if this is OK, or if we want to give the
document a slightly more standards-like feeling.
5.3. Syntax definitions
=======================
Rather than saying that the transformer should be a syntax-rules form,
it might be preferable to say that it should be a macro transformer but
that syntax-rules is the only one defined in this report. Later, this
can be augmented with a reference to "syntax-case" in the big language.
Again, see R6RS (section 11.2.2).
The added paragraph regarding ambiguous definitions is very, very hard
to understand; the sentences are not particularly well digestible. But I
admit that it is very hard to explain. ;) A proposal:
"Macros may expand into (syntax) definitions in any context that permits
them. However, it is an error for a (syntax) definition to define an
identifier whose binding must be known to determine the meaning of the
definition itself, or of any preceding definition that belongs to the
same group of internal definitions. Similarly, it is an error for an
internal definition to define an identifier whose binding must be known
to determine the boundary between the internal definitions and the
expressions of the <body> it belongs to. For example, the following are
errors:"
It would be nice if the last example would use a more descriptive macro
name than "foo". For the fun of it, one could make it a macro that
resembles CL's "defun" and call it that. Also, I would remove the "let"
and the last body expression, as IMO it is not needed to illustrate the
boundary problem (correct me if I'm wrong). Like so:
(let-syntax
((defun (syntax-rules ()
((defun proc (args ...) body ...)
(define proc
(lambda (args ...)
body ...))))))
(defun plus (x y) (+ x y))
(define defun #f))
5.4. Record-type definitions
============================
The header and the first paragraphs uses "record-type" with a hyphen
while the rest of the section's text uses the whitespaced "record type".
This should be consistent. I like the latter much better.
I feel that the introductory paragraph could be improved. It doesn't
really explain what records / record types actually are. A proposal:
"Record type definitions are used to introduce new data types, called
_record types_. The values of a record types are called records and are
aggregations of zero or more _fields_, each of which holds a single
value (similarly to a variable)."
(Terms surrounded with underscores are supposed to be italic.)
"<pred> is a predicate [...]" should be "<pred> is bound to a predicate
[...]". Likewise "Each <accessor name> is [...]" and "Each <modifier
name> is [...]".
The "kons" example should begin with a phrase signalling that an example
follows: "For instance, the following definition [...]"
5.5. Modules
============
The report doesn't introduce the notion of a "namespace", yet it is used
in the introductory sentence. I think that part of the sentence can just
be dropped. I also don't like "encapsulate programs"; it's not a vey
useful explanation IMO. A proposal:
"Modules provide a way to organize Scheme programs into reusable parts
with explicitly defined interfaces to the rest of the program. This
section [...]"
5.5.1. Module Syntax
====================
There is another instance of the un-introduced "form" term here ("[...]
read all top-level forms from the files [...]") which probably stems
from the fact that this section is mostly took from R6RS. The "reader"
term is used as well; I propose to rephrase
"include-ci uses a case-folding reader when reading the forms from the
file."
to read
"The difference between the two is that include-ci reads each file as if
it began with the #!fold-case directive (see section 2.1), while include
does not."
In the paragraph about "cond-expand", I would rather use the term
"implementation environment" than "platform", but your mileage may vary.
As section 5.5 has no other subsection than 5.5, it would seem to make
sense to just put all of 5.5.1 into 5.5 directly.
That's it for this chapter. As always, I sincerely hope that my comments
are helpful for you.
Regards,
Denis
P.S.: In section 1.3.5, "predicate" should be italic as the term is
introduced there.
_______________________________________________
Scheme-reports mailing list
Scheme-reports@scheme-reports.org
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports