On 3/27/13, Mark H Weaver <xxxxxx@netris.org> wrote:
> Hi David,
>
> "David A. Wheeler" <xxxxxx@dwheeler.com> writes:
>> I've attached an updated SRFI-110 that includes a tutorial section.
>>
>> Is this headed in the right direction? And no matter what, are there
>> suggestions for improvement?
>
> Yes, this is definitely headed in the right direction! I'm now able to
> understand most of the rules from the tutorial and basic specification.
>
> A few comments on the tutorial:
>
> * It would be helpful to describe what happens if '.' is encountered
> outside of any parentheses, in both the tutorial and the basic
> specification.
>
> * Re: "Block comments (#|...|#) are removed." I still don't know what
> this means exactly. Why do you say "removed" and not simply
> "ignored"? Is there a difference?
Yes
>Why don't you say that other kinds
> of comments are "removed"?
Because ;-comments are treated differently:
1. A sequence composed of indentation whitespace followed by ;
followed by any number of characters followed by an end-of-line
sequence is completely ignored - it doesn't count as a blank line.
So, you might think of it that internally, the following:
foo
; comment
bar
is the same as:
foo
bar
2. A #|...|# comment is "removed" and replaced with GROUP if it's the
first thing after indentation whitespace, or just "removed" otherwise.
Basically, it means that:
foo
#| comment
|# bar #|
comment
|# nitz
is the same as:
foo
\\ bar nitz
The reason we say "removed" is that *end-of-line sequences are also
removed*. It also means that the following text yields an error:
; view this in a fixed-width font
foo
! bar
!#|comment|# quux
==>
Error! inconsistent indent:
foo
! bar
!\\ quux
^ here
The reason for this is described fully in the design rationale
question "Why are the indentations of block comments and datum
comments significant?". It's not satisfactory, and you are free to
provide an alternative, but be reminded that there are largely only
two expected use cases of block comments anyway (described in the
design rationale section), and the current solution sidesteps the
subtle problem involved (basically, CJK characters and encoding).
I didn't put the explanation in the specification section because it's
long and handles an edge case which we don't expect anyway - we expect
people to use #||# "sensibly" - so it's delegated to the design
rationale.
>
> * Re: GROUP and SPLIT in the tutorial: Examples needed, especially for
> GROUP. The language "it represents no symbol at all" is confusing and
> unclear. Also "intepreted the start" => "interpreted as the start".
>
> * Re: SUBLIST item in tutorial: "last parameter" => "last element".
> Also, please add an example here where there is no LHS.
>
> * Re: /collecting list/ item in tutorial: "and the indentation level is
> temporary restarted at the left edge" is a bit confusing. Examples
> are needed.
>
> Maybe there should be a small block of examples underneath the numbered
> list of "advanced features" in the tutorial. Alternatively, maybe the
> entire "examples" section should be moved up to immediately follow the
> tutorial.
>
> Some more comments, unrelated to the recent changes:
>
> * I continue to find the use of unconventional indentation in the
> s-expression examples to be quite distracting. I've never seen Scheme
> or Lisp code indented that way.
>
> * I think you should consider using conventional indentation in your
> t-expression examples where reasonable, e.g. for 'if' and 'do'
> Personally, I find this:
>
> define gcd(x y)
> if {y = 0}
> x
> gcd y rem(x y)
>
> much easier to read than your convention of:
>
> define gcd(x y)
> if {y = 0}
> x
> gcd y rem(x y)
>
> and I suspect I'm not alone. De gustibus non est disputandum, but I'm
> not sure this is just a matter of taste. It is intuitive to see the
> operands lined up vertically, and most Schemers are used to that. Is
> there a compelling reason to break this tradition?
>
> * I have doubts whether the addition of '!' as an indentation character
> is worth the added complexity in the spec (which is far more complex
> than I'd prefer, and I'm sure I'm not alone in feeling that way).
> Python seems to do fine without such a character. So do Makefiles.
> If it's truly needed, then it presents authors with a dilemma about
> whether or not to put them in all the code that they write.
! is surprisingly useful. Here's an example which is readable, but
difficult to modify if you need to add an else clause:
define (foo x)
define something $ cond
(pred1? x) $ begin
something that is
very long
spanning several lines
and might
end up
with severe
changes in indentation
like this
and so on
so forth
whatsover ...
(pred2? x) $ begin
another long clause
involving several
more lines
and which
also ends
in
(severe)
changes
in indentation
at the end
quux something
In s-expressions, it's safe to lose a space or two when you insert a
clause at the end of the cond - the parens (should) guide the parser
to the correct insertion. But in t-expressions, the new clause at the
cond level *must* line up at the same levels as (pred1? x) and (pred2?
x).
By highlighting this important indentation level, you can more easily
facilitate adding an else clause - you just press space until you
reach the ! line and then type the new clause.
define (foo x)
define something $ cond
(pred1? x) $ begin
! something that is
! very long
! spanning several lines
! and might
! end up
! with severe
! changes in indentation
! like this
! and so on
! so forth
! whatsover ...
(pred2? x) $ begin
! another long clause
! involving several
! more lines
! and which
! also ends
! in
! (severe)
! changes
! in indentation
! at the end
quux something
FWIW this usage is not shown in the design rationale section (i.e. it
helps keeps track of the correct indentation level after several
lines), and we probably should list it as the foremost reason.
>
> Okay, that's enough for now. I still have yet to read carefully beyond
> the Basic specification, so no doubt I'll have more comments later.
>
> Regards,
> Mark
>
>
