[racket-dev] Scribble Racket Code with Here Strings

At Fri, 29 Oct 2010 15:53:57 -0600, Doug Williams wrote:
> I sometimes use here strings for readability when building queries, etc.
> [...]
> But I haven't found a good way to document this (as Racket code) in
> Scribble. Everything I've tried renders like:

I guess it's time for me to stop saying how this should be done and
just do it.

Scribble now provides `codeblock' from `scribble/manual'. The
`codeblock' form is similar to `racketblock', except that it works on
strings instead of S-expressions. Roughly, you use curly braces with
`codeblock' instead of square brackets. The code is typeset with the
formatting of the source strings as with `verbatim', and then coloring
and hyperlinking are applied on top of that --- more like DrRacket's
Check Syntax than the `read'-and-`write' approach of `racketblock'.

The example below produces the output you would expect, except that the
last `codeblock' and `racketblock' are not hyperlinked correctly (i.e.,
a bug that I haven't yet sorted out).

The "Getting Started" section of the Scribble manual is now
syntax-colored, since its source now uses `codeblock' instead of
`verbatim'.

The `#:expand' argument to `codeblock' isn't fully implemented, yet.
When you supply `expand', hyperlinks should be based on bindings as
they appear in the expanded code, but they currently use `for-label'
bindings in the context of the `codeblock' form. I'll get to that soon.
I expect there will be further generalizations eventually, such as
being able to include Scribble elements among the string arguments to
`codeblock'.

----------------------------------------

#lang scribble/manual
@(require scribble/private/manual-code
          (for-label racket/base
                     scribble/manual))

@title{Examples of @racket[codeblock]}

The following an example illustrates how @racket[codeblock] handles
here strings:

@codeblock{
  #lang racket

  (define (explain-family name)
    (printf #<<EOS
  They're creepy and they're kooky,
  Mysterious and spooky,
  They're all together ooky,
  The ~a Family.
  EOS
            name))

  (explain-family "Addams")
}


The @racket[codeblock] form is also good for showing Scribble examples
with syntax coloring:

@codeblock|{
 #lang scribble/manual
 @(require "utils.rkt")

 @title{Example Scribble Code}

 You should use @racket[codeblock] instead of @racket[racketblock].
}|