Re: [racket-dev] Scribble Racket Code with Here Strings

[Matthew Flatt]

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

Re: [racket-dev] Scribble Racket Code with Here Strings

[Sam Tobin-Hochstadt]

On Sat, Oct 30, 2010 at 11:56 AM, Eli Barzilay e...@barzilay.org wrote:

 That is, the here string has been rendered as a normal string with lots of
 whitespace after.

 There's lots of ways to create strings and the documentation system
 can't tell them apart -- so it rendered it as a string, but then
 noticed that the other pieces of code are a few lines later.

Isn't that a sign that we need a syntax property for here-strings,
similar to 'paren-shape?
-- 
sam th
sa...@ccs.neu.edu
_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev

[racket-dev] Scribble Racket Code with Here Strings

[Doug Williams]

I sometimes use here strings for readability when building queries, etc.
For example:

(let-values (((variables results)
  (get-repository-query-tuple r
#---
select * from {x} sys:repositoryID {y}
using namespace
  sys = http://www.openrdf.org/config/repository#
---
  #:query-language 'SERQL)))
  (printf Repository ids = ~s~n
  (for/list ((bindings (in-list results)))
(binding-string (bindings-ref bindings 'y)

But I haven't found a good way to document this (as Racket code) in
Scribble. Everything I've tried renders like:

  (let-values (((variables results)(
get-repository-query-tuple r  select * from {x}
sys:repositoryID {y}\r\nusing namespace\r\n  sys = 
http://www.openrdf.org/config/repository#\r
#:query-language 'SERQL)))(printf Repository ids = ~s~n(
for/list ((bindings (in-list results)))  (binding-string (
bindings-ref bindings 'y)

That is, the here string has been rendered as a normal string with lots of
whitespace after.

Any ideas?

Doug
_
  For list-related administrative tasks:
  http://lists.racket-lang.org/listinfo/dev