((( [logo]Racket )))Need Help?
AboutDownloadDocumentationPLaneTCommunityLearning

[plt-scheme] Tables in Scribblings

From: Eli Barzilay (eli at barzilay.org)
Date: Thu Sep 11 21:15:30 EDT 2008		 
On Sep 11, Matthew Flatt wrote:
> At Thu, 11 Sep 2008 18:27:49 -0500, "Grant Rettke" wrote:
> > > Can you specify which parts made no sense, and how they can be
> > > improved?
> > 
> > I was sort of expecting the documentation to have everything you
> > would need to know to do %80 of your tasks in one or two
> > pages. Instead there is a lot of material, but it isn't obvious
> > (to me) where to look or where to start. I was excited to see
> > Scribble when it came out; but quickly found that I just "didn't
> > get it". I assumed it was too powerful for what I wanted to do
> > with it, which basically amounts to what one wants to do with
> > HTML. The best place I have to figure things out is to look at the
> > source code for the documentation.
> > 
> > Sometimes obvious operations seem confusing, so people post about
> > them and knowledgeable folks answer so quickly that I feel like it
> > must be confusing to you guys why people don't get it! :)
> 
> I think Eli was asking more specifically about documentation for the
> "@" reader syntax,

(Yes.)


> but your point is well taken.  It will take us a while to refine
> Scribble into something that meets our documentation needs, is easy
> to use, and has good documentation for itself.

One more thing that I want to add: if by "what one wants to do with
HTML" you mean that you want to *generate* html (not generate
documentation that can be rendered in html) then that's very doable,
and it's the reason that the @-reader description is detailed; it can
be used for anything -- including functions that will generate html.
Here's a very rough example (note that #reader should come before the
#lang):

  ----------------------------------------------------------------------
  #reader scribble/reader
  #lang scheme/base
  
  (define (html . body)
    (display "<html>\n")
    (for-each display body)
    (display "\n</html>\n"))
  
  (define (my-page)
    @html{blah
          1 + 2 = @(+ 1 2)
          blah})
  
  (my-page)
  ----------------------------------------------------------------------

Running this code will print this out:

  ----------------------------------------------------------------------
  <html>
  blah
  1 + 2 = 3
  blah
  </html>
  ----------------------------------------------------------------------

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!
Posted on the users mailing list.