Thank you very much for your review!  I and/or David A. Wheeler will
look through your list and try to clarify these.

On 3/22/13, Mark H Weaver <xxxxxx@netris.org> wrote:
> Hello all,
>
> First of all, I should admit that I have only begun reading about sweet
> expressions in the last hour or so.  I don't yet understand the rules.
>
> I began to try to learn about them by jumping directly to the
> "Specification" section of SRFI-110.  I'm sorry to say that I find that
> section extraordinarily unclear.  Below, I've made notes about the parts
> that I found confusing.
>
> No doubt, I could find answers to all of these questions by reading the
> rest of the document more carefully, and/or by reading the website of
> the Readable Lisp S-expressions Project.  However, I don't think I
> should have to.  The specification should stand on its own to a
> reasonable extent, IMO anyway.
>
> [In the list below, "first list", "second list", and "third list" refer
> to the three numbered lists of rules in the "Basic specification"
> section.]
>
> * "term" is used before it is defined.

Okay, I propose to define a "term" as "a Neoteric-expression
(n-expression or n-expr), as defined by SRFI-105".

>
> * The concepts of "parent" and "child" are not defined.

Okay, I propose to clarify:

* a "parent" is a line, which may have an empty indentation.
* a "child" is a line following a parent line that is more indented
than that line.

>
> * The use of the term "parameter" is confusing.  This is a datum reader
>   after all, which deals with "lists", not "parameters".  I'd prefer for
>   it to describe more clearly what data structure is created.

Okay, I propose to change "parameter" to "term" or "sub-term" in general.

>
> * Item 1 (first list): What is an "indented line"?  Does that mean any
>   line with non-empty indentation, or does it mean "indented more than
>   some other line"?  If the latter, which other line?

Okay, maybe a parenthetical "(a line that is more indented than its
parent line)"

Actually, you know, maybe the first list can be clarified.

>
> * Item 3 (first list): Does "multiple terms" mean "multiple terms on
>   the same line"?  If so, isn't this redundant with item 2 (but IMO
>   more clearly stated)?

Possibly, yes.

>
> * Item 4 (first list): What is an "empty line"?  Is whitespace allowed?
>   What about exclamation points?  What about comments?

Okay, we may need to put a link to "empty line" somewhere.

I propose to use "blank line" as the preferred term rather than "empty line".

I propose to add "A blank line is a line composed only of horizontal
whitespace (space or tab), exclamation points, and ;-comments".

>
> * Item 6 (first list): What does "prefixed" mean?

May need to link to SRFI-105, which defines "prefixed".

>
> * Are '!', '$', '\\', '$$$', '<*' and '*>' recognized as special tokens
>   only if they are surrounded by whitespace?  (All of these characters
>   except for backslash are considered extended alphabetic characters in
>   standard scheme.)

The "markers" are: $ \\ <* *> and $$$.

The indentation whitespace "!" is not: it's allowed to have !!!!! as
part of indentation whitespace.

>
> * Later in the design rationale, it is mentioned in passing that '!'
>   is only recognized as indentation at the beginning of a line.  Does
>   that mean before any whitespace?  If so, that fact should be
>   mentioned in the specification (which currently suggests that '!'
>   could mixed freely with spaces or tabs).

I propose to replace this "beginning of a line" with "inside an
indentation".  "!" *can* be mixed freely with spaces or tabs - but
only in indentation.  Between terms, it is not whitespace.

>
> * Item 1 (second list): What are lines with "initial indent"?

Erk, a local term in readable-discuss that escaped into this, sorry.
"initial indent" is a problem when you're in a top-level context and
read an indented line; basically, if the reader is in a top-level
context (start of file or after a blank line), and encounters a line
with non-empty indentation.

>  What
>   happens if a line is not consistently indented?

"It is an error if the line is not consistently indented"

>  What is meant by
>   "preceding line"?  Does that mean "preceding non-empty line"?  (if
>   so, what does "empty line" mean?)

No, just "the line before it, ignoring completely ;-comment-only
lines", directly.

>
> * Item 3 (second list): What does "completely ignored" mean?  How does
>   this relate to the "preceding line" of item 1 (second list)?

It means that, conceptually, you can consider a line composed of
(optional) indentation followed by ; followed by whatever followed by
an end-of-line to be completely non-existent - so in item 1 above, a
"preceding line" means a line that is not a ;-comment-only line.

>
> * Is '!' considered whitespace?

Only in indentation.  It is not considered whitespace elsewhere.

>
> * Item 5 (second list): What does it mean for an expression to "start
>   indented"?

Basically the "initial indents" line problem.  Also need to clarify
"until the first end-of-line outside an n-expr".

>
> * Item 6 (second list): Do datum comments ignore intervening '!'
>   characters as well?

No.  "!" is whitespace only in indentation.

>
> * In the rules that say neoteric expression are read (not sweet
>   expressions), how are '!', '$', '\\' and '$$$' handled?

As datums.

>
> * Item 7 (second list): What does it mean exactly that block comments
>   are "removed"?

They are deleted from the input stream, any spaces and newlines inside
them are ignored.

>
> * Item 1 (third list): Regarding GROUP, what does it mean "it
>   represents no symbol at all, located at that indentation"?

It's a marker that indicates nothingness, it is not a datum, it's
nothing at all.  However, the indentation at that point *is*
significant.

>
> * Item 2 (third list): What does "restart list processing" mean?  What
>   is "the right-hand-side"?  What are "its sub-blocks"?  What happens
>   if there's more than one '$' on a line?

Basically: on encountering a SUBLIST, it eats horizontal whitespace
and acts as if it is on a new line at its current indentation.  It
then gets the sweet-expression (acting as if the sweet-expression
starts at the indentation of the current line) and makes it the last
item of the current line.  In case of multiple SUBLIST, the subsequent
SUBLIST just does that again.

>
> * Item 3 (third list): Does "indentation" mean "non-empty
>   indentation"?  (and does that definition apply generally?)

No, and no.  It's possible to have at the top-level, unindented:

` foo bar
==>
(quasiquote (foo bar))

>  In the
>   "entire sweet-expression that follows" what is considered the
>   indentation of the first line of that expression?

The indentation of this line.

>
> * Item 4 (third list): What are "un-indented sweet expressions"?

I propose "top-level" instead of "un-indented".

>
> * Why is there a distinction made between "advanced sweet-expression
>   features" and the rest of the spec?

Because these features are not indentation-processing per se.

>
> * In the paragraph immediately following the third list:
>
>    * "MUST only be accepted ... is active"
>       => "MUST NOT be accepted ... is not active"

Seems okay to me.

>
>    * When are sweet expressions accepted but "indentation processing"
>      is not active?  (in collecting lists?)

Inside parentheses.  indentation processing is restarted inside
collecting lists.

>
>    * What does it mean that a "character sequence" begins with
>      "exactly the marker's first character"?  In "{$}", why is the '$'
>      not considered a "character sequence"?

Should probably change the clause about "character sequence" to:
"inside { } () [] indentation processing is not active, so for
example, {$} MUST NOT ...."

>
> * IMO, it should probably be specified whether "#!no-sweet" disables
>   curly-infix.
>
> * In the examples, why are the s-expressions not indented according to
>   the nearly-universally accepted conventions?

Okay, will fix.

>
> * The use of '$', '$$$', '<*', and '*>' as special tokens should be
>   mentioned in the "Backwards compatibility" section.  These are all
>   considered extended alphabetic characters by standard scheme.
>
> * If an implementation implements sweet expressions by default, then
>   they will have to be careful about writing symbols that contain '$',
>   '<*' or '*>'.

Will clarify that these markers only have those meanings if they are
separated by whitespace.  So a symbol like <*> is fine to print as-is,
but <* needs to be printed as {<*}.

>
> * In the design rationale, there's a section entitled "Blank lines".
>   Are these the same as the "empty lines" referenced in the
>   specification?  If so, I suggest using just one term, and defining
>   it clearly in the spec.

Mostly.  I propose "blank lines"

>
> * When you speak of "traditional abbreviations", you might want to
>   make a suggestion about how to handle additional non-standard
>   abbreviations.  In particular, the abbreviations #', #`, #, and #,@
>   are widely used by the syntax-case macro system.

Okay.

--

Will look into this at more detail later - little busy for now.

Sincerely,
AmkG