[plt-scheme] Tables in Scribblings

From: Eli Barzilay (eli at barzilay.org)
Date: Thu Sep 11 21:08:57 EDT 2008

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!

Posted on the users mailing list.