[plt-scheme] Tables in Scribblings

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

On Sep 11, Jay McCarthy wrote:
> On Thu, Sep 11, 2008 at 7:08 PM, Eli Barzilay <eli at barzilay.org> wrote:
> > There's this example, which is pretty explicit:
> >
> >  @foo{The prefix: @"@".}     reads as  (foo "The prefix: @.")
> 
> Now that you show them, these should have helped me a lot. But as I
> read through I saw @foo and said, "But I'm not writing a call or
> something inside a call, ignore it." If I were an extreme reader, I
> should have noticed. But I'm lazy documentation reader and didn't
> see it. (In fact, I'm sure its been there the last 6 or 7 times I've
> tried to remember this and I've missed it every time.)

(Yes it has, the whole thing didn't change much since it was in
doc.txt form.  But the fact that you missed it so many times is what
makes me think that there's a problem in the current organization of
the text.)

> Clearly something is wrong, but it's probably me. Forgive my honesty
> :)

Well, I think that most people are lazy readers when it comes to
reference manuals.  You want to get to the point that gives you what
you want.  Since the reader chapter reads almost like a story with
lots of examples, I think that a simpler "quick intro" paragraph will
be a good thing.

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


Posted on the users mailing list.