[plt-scheme] Tables in Scribblings

http://docs.plt-scheme.org/scribble/reader.html

says:

Informally, the concrete syntax of @-forms is

  @ ‹cmd› [ ‹datum›* ] { ‹text-body›* }

where all three parts after @ are optional, but at least one should be
present. (Note that spaces are not allowed between the three parts.) @
is set as a non-terminating reader macro, so it can be used as usual
in Scheme identifiers unless you want to use it as a first character
of an identifier; in this case you need to quote with a backslash
(\@foo) or quote the whole identifier with bars (|@foo|).

  (define |@foo| '\@bar at baz)

Of course, @ is not treated specially in Scheme strings, character
constants, etc.

--

But it doesn't give an example of just getting a solitary @. 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.
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.
<Lost for a while>
12. I've read the rest of this manual page. No examples.
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

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.

15. Alright, so I know how to get a Scheme expression in there. Pop
the stack. Now I need a Scheme string.

16. I type in @"@" and it works.

Painful.

The amazing power of the @-reader and all its subtleties are explained
in the manual. I think Doug is getting at the fact that many simple
things are hard to understand.

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 {}

Jay

On Thu, Sep 11, 2008 at 3:16 PM, Eli Barzilay <eli at barzilay.org> wrote:
> On Sep 11, Jay McCarthy wrote:
>> On Thu, Sep 11, 2008 at 3:07 PM, Doug Williams
>> <m.douglas.williams at gmail.com> wrote:
>> > No offense, but the Scribble manual does little to help me
>> > actually write Scribble documentation.  A Guide would be much more
>> > helpful.  I tend to look for examples in the existing
>> > documentation, but that's difficult when you don't know exactly
>> > what to look for.
>>
>> Agreed. Every time I want to get a literal @ I look at the manual
>> and it makes no sense. Then I look at the source of the manual and I
>> understand.
>
> Can you specify which parts made no sense, and how they can be
> improved?
>
> --
>          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
>                  http://www.barzilay.org/                 Maze is Life!
>



-- 
Jay McCarthy <jay at cs.byu.edu>
Assistant Professor / Brigham Young University
http://jay.teammccarthy.org

"The glory of God is Intelligence" - D&C 93