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?  Why don't you say that other kinds
  of comments are "removed"?

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

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