[racket] Scribble in continue

Three minutes ago, Stephen De Gabrielle wrote:
> I meant the @ syntax just like your example, but I was thinking of
> the @syntax being entered by the user via the browser

That's a really good idea, and if you do that we can definitely use
it.  We've been looking for a while for some wiki solution, and IMO
the scribble syntax has a good balance between being convenient enough
to be considered almost markdown, yet formal enough to not suffer from
various markdown diseases (you can see these when you get to some
cornder cases, and the syntax becomes very complex, or just see any
wikipedia source -- the convenient lightweight wiki language has long
ago turned into a massive pile of ad-hoc syntaxes and templates, which
you can only use by copy+pasting examples if you want to keep your
sanity.)

However, the actual documentation system is way to heavy for a quick
wiki blurb -- most definitely not something that people can learn in
the 10 seconds they'll allocate to glancing at the help blurb when
they type a quick comment.  That's in addition to it being slow enough
that you don't want to use it to render pages dynamically.  So IMO
going in this direction (using the syntax only) is a good idea.

Note that the Scribble syntax has a convenient shortcut for quoted
(and quasiquoted and unquoted etc) forms.  For example,

  @`html{@head{@title{...}}
         @body{...}}

will work fine.

But there is a major problem with xexprs.  The whole quoted/unquoted
context makes it very difficult to know where you currently are.  As
an example, at some point in the past the PLT web pages had a bunch
of:

  <quote>&nbsp;</quote>

because 'nbsp was used deep inside some already quoted xexpr.

Another problem is that xexprs are picky about the kind of data that
goes into them.  You can't just have a list somewhere, and that makes
you run into all kinds of complex situations -- one common byproduct
is using `apply append' too much; anothert common result is returning
`(span ...) because the result of a function is expected to be a
single xexpr, or returning `((p "blah")) because it's expected to be
multiple expressions.


I solved both of these problems by making a (yet another) new kind of
xml representation, but the new thing is how it's used.  Instead of
abusing quotes, it's all just functions.  So instead of

  `(foo ([blah "blah"]) "bar")

you use

  (foo blah: "blah" "bar")

(I used `keywords:' to keep them separate from racket keywords.)  The
main thing here is that `foo' is a function -- so when you nest them
you nest function calls, which means that you never need to remember
if it's quoted or not.  Even better, when you need to change
something, you can define new functions that behave just the same --
so instead of doing new markup which is awkward to use:

  (define (path . body) `(b (tt "\"" , at body "\"")))
  (define my-page `(html ... (body "Here is " ,(path "x.rkt") ...)))

you just make up a new function:

  (define (path . body) (b (apply tt `("\"" , at body "\""))))
  (define my-page (html ... (body "Here is " (path "x.rkt") ...)))

and to avoid the list problem, I made it so if there's a list, its
contents is rendered, so there's no need to do any flattening:

  (define (path . body) (b (tt "\"" body "\"")))
  (define my-page (html ... (body "Here is " (path "x.rkt") ...)))

and with scribble syntax:

  (define @path{@body} @b{@tt{"@body"}})
  (define my-page @html{ ... @body{Here is @path{x.rkt} ...}})

You can see all of this in the web page sources -- in
collects/meta/web.  It's close to being useful as a library, the main
thing that I need to do is document it.  If you do a wiki based on
this, it will definitely be a strong motivator to finally doing it.

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