[plt-scheme] Tables in Scribblings

Thanks for the feedback -- I'll try to improve some things based on
it, but here are a few quick comments before I do that:

On Sep 11, Jay McCarthy wrote:
> 
> But it doesn't give an example of just getting a solitary @.

It doesn't feel right to me to jump right into the relevant
subtelties, and the paragraph that you quoted is basically the
introduction.  (But I will try to put some clarifying examples close
to that paragraph.)


> So, I'm supposed to go through the following process:
> 
> 1. I want a textual @.
> 2. I can get a scheme identifier with an @ by following those
> examples. But that's not what I want.
> 3. "Of course, @ is not treated specially in Scheme strings  ..." --
> none of these sounds like what I want... I'm not making a Scheme
> string, I want just plain old text.

[I hope that it is clear that the scribble reader represents `text' as
(sequences of) strings.]

> 4. So what do I do?
> 5. Oh wait, Scheme values are evaluated and displayed.
> 6. Thus by 4, a Scheme string with an @ in it is what I want.
> 7. Okay, so "@", because "..." is a Scheme string
> 8. Error: read: expected a closing '"'
> 9. Hmm, that's strange. Oh right, "..." is not a Scheme string, it is a "body"
> 10. How do I get just a string?
> 11. The concrete syntax only has function calls. Strings aren't
>     function calls.

OK, that's probably should be demonstrated sooner, with the above
addition, probably.


> <Lost for a while>
> 12. I've read the rest of this manual page. No examples.

There's this example, which is pretty explicit:

  @foo{The prefix: @"@".}     reads as  (foo "The prefix: @.")

and then there is an example that involves both Scheme strings, and
double-quotes in the text part:

  @foo{@"@x{y}" --> (x "y")}  reads as  (foo "@x{y} --> (x \"y\")")

Both of these examples come before the "Alternative Body Syntax"
section that has the `|{'s, and demonstrates more ways to get an
at-sign in a string.


> 13. I read it again, now I notice that in 3.1.2 in the third set of
> examples, the third example shows that
> 
> @foo => foo

The "Scheme Expression Escapes" has lots of examples that are more
than just identifiers.  But I think that to make this point better,
some examples should be added to "the command part" section.


> 14. It takes a great leap to realize that this applies not only to
> identifiers, but any Scheme expression. I could also have noticed this
> by reading in 3.1.1 in the third paragraph where examples are given of
> lambdas and unquote. I didn't notice these earlier, because they are
> so complicated.

That sounds like a possible problem, but I'm not sure how to deal with
it.  If I leave out the "complicated" examples, then it's not going to
be complete, and leaving them in is clearly a problem.  Perhaps the
right approach to solve all this would be to follow the intro with a
few quick common examples, but I'm not sure which set to choose that
is both useful and not too confusing (for example, I'm not sure if
|{...|} should be included in something like that).


> [...]
> Another example is that the manual libraries are documented as
> Scheme calls. It is true that they are Scheme functions, but they
> feel like markup. Just putting examples in the @ syntax would be an
> amazing improvement. It is hard to tell where to use [] and where to
> use {}

That's a known problem.  It comes from the current implementation of
the `scheme' macro, which organizes the code according to the source
information of the syntax -- but that source information is roughly
the same for `@foo[x]{y}' and for `(foo x "y")'.  There are certain
syntax properties that mark scribble-read expressions, but
reconstructing the input form from that is too difficult.

Actually, Matthew: the whole expression will have a `scribble' syntax
property that has '(form <n> <m>), where <n> is the number of datum
arguments (or #f if no [] were used), and <m> is the number of the
following argument that originated from a body part (again, #f is
there was no body).  So perhaps this can be used for a simple
rendering using the scribble notation?

A complete solution for this would be a new `scheme'-like construct
that has its body as text (eg, @scheme{...}), and it will parse this
text to get to the scheme parts and to highlight them properly, but
keep the text as is for the rendered version.

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!