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]. }| _________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev