Thank you for your comment

Beau­tiful Racket / tuto­rials

Finishing moves: jsonic

Intro­ducing Scribble

Many of the links in this book, including func­tion names in code samples, lead into Racket’s browser-based docu­men­ta­tion. For instance, here’s the entry on pairs and lists.

A copy of all Racket docu­men­ta­tion is main­tained online at docs.racket-lang.org. But Racket also builds a local copy of the docu­men­ta­tion for every installed package.

This allows the docu­men­ta­tion to be inte­grated with DrRacket without depending on a network connec­tion. For instance, if we right-click a func­tion name in DrRacket, the context menu will let us View docu­men­ta­tion for that func­tion, which will open a browser and send us to the right place.

Given every­thing we’ve learned so far, it shouldn’t surprise anyone to find out that Racket’s docu­men­ta­tion is made with a domain-specific language called Scribble.

We don’t have to make our docu­men­ta­tion with Scribble. (We don’t have to make docu­men­ta­tion at all.) But as we saw with DrRacket, the advan­tage of using Scribble is that it provides a set of conve­niences that are avail­able to any Racket-imple­mented language:

The cost, however, is that using Scribble is not as easy as, say, writing a Python docstring. A Scribble docu­men­ta­tion file is itself a program. As of today, there’s no way to auto­mat­i­cally generate Scribble docu­men­ta­tion from existing source code. We have to write our docu­men­ta­tion by hand. Unde­ni­ably, it creates extra house­keeping.

But if Scribble demands a higher base­line of effort, it also raises the ceiling of what we can accom­plish. We can do a lot more with Scribble than we can with the lowly docstring. After all, no soft­ware user has ever said “gosh, this docu­men­ta­tion is just too vast, thor­ough, and detailed.”

In that sense, we can see Scribble partly as a policy deci­sion about the culture of docu­men­ta­tion Racket wants to encourage among its devel­opers: namely, to write a lot of docu­men­ta­tion, and make it consis­tent and cross-refer­enced. And if we look through the existing docu­men­ta­tion—vast, thor­ough, and detailed—that policy is working.

Scribble basics

Seman­ti­cally, Scribble builds on top of Racket. The big differ­ence is the syntax: rather than embed­ding text within S-expres­sions, Scribble allows us to embed S-expres­sions within plain text using @-expres­sions. Scribble supports two styles of @-expres­sions:

  1. The first starts with an @ sign and a func­tion name, option­ally followed by a sequence of Racket expres­sions between square brackets, and then option­ally ending with text between curly brackets. So this S-expres­sion in Racket:

    (list 42 #f "hello world")
    1
    (list 42 #f "hello world")
    copy to clipboard

    Is the same as this @-expres­sion in Scribble:

    @list[42 #f]{hello world}
    1
    @list[42 #f]{hello world}
    copy to clipboard

    The curly brackets are similar to here strings in that they generate a string without requiring us to escape any char­ac­ters. But they’re also more flex­ible than here strings, because other @-expres­sions can be nested inside.

  2. We can also make an @-expres­sion by simply prefixing any paren­the­sized S-expres­sion with an @ sign. So this @-expres­sion is also equiv­a­lent to the above list:

    @(list 42 #f "hello world")
    1
    @(list 42 #f "hello world")
    copy to clipboard

Overall, we can think of Scribble as just a more conve­nient way of writing Racket programs that handle a lot of text. For instance, consider this simple program:

(define (greet . words)
   (format "Good morning, ~a" (string-append* words)))
(define surname "Trevor")
(display (greet "Mr. " surname "!")) (display " How are you?")
1
2
3
4
(define (greet . words)
   (format "Good morning, ~a" (string-append* words)))
(define surname "Trevor")
(display (greet "Mr. " surname "!")) (display " How are you?")
copy to clipboard
Good morning, Mr. Trevor! How are you?
1
Good morning, Mr. Trevor! How are you?
copy to clipboard

We can convert this to equiv­a­lent @-expres­sions like so (though we’ll omit the calls to display, because the scribble/text dialect will auto­mat­i­cally display its results):

#lang scribble/text
@(define (greet . words)
   (format "Good morning, ~a" (string-append* words)))
@(define surname "Trevor")
@greet{Mr. @surname}! How are you?
1
2
3
4
5
#lang scribble/text
@(define (greet . words)
   (format "Good morning, ~a" (string-append* words)))
@(define surname "Trevor")
@greet{Mr. @surname}! How are you?
copy to clipboard
Good morning, Mr. Trevor! How are you?
1
Good morning, Mr. Trevor! How are you?
copy to clipboard

We’re mixing both styles of @-expres­sions: the simpler style for the func­tion and vari­able defi­n­i­tions, and the curly-brace style for the text content. But beyond that, both code frag­ments work the same way.

Writing Scribble docu­men­ta­tion

The scribble/manual dialect used for making docu­men­ta­tion uses the same syntax as scribble/text. But it also provides a core set of func­tions for handling common docu­men­ta­tion tasks. And rather than rendering the source as text, it creates a data object that’s passed to an HTML or PDF renderer.

By conven­tion, the main Scribble docu­men­ta­tion file for a Racket package lives in a subdi­rec­tory called scribblings and is called package-name.scrbl. So let’s create our jsonic.scrbl file now, and put #lang scribble/manual at the top to invoke the Scribble docu­men­ta­tion dialect:

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual
1
#lang scribble/manual
copy to clipboard

When we use scribble/manual, it adds two buttons to the DrRacket toolbar: Scribble PDF and Scribble HTML. We can use these buttons at any time to preview our Scribble file rendered as PDF or HTML.

In fact, let’s click the Scribble HTML button right now. We’ll see some status messages in the DrRacket REPL:

scribble: loading xref
scribble: rendering
1
2
scribble: loading xref
scribble: rendering
copy to clipboard

Then a web browser will be opened with the rendered page. This page will be blank in the main column, and have some ??? signals in the left column. That’s not surprising: no source = no result.

So let’s add some. The only three indis­pens­able elements of docu­men­ta­tion for a language are a title, a defmodulelang decla­ra­tion, and at least one char­acter in the body (we’ll use a sentence):

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual

@title{jsonic: because JSON is boring}

@defmodulelang[jsonic]

This is a domain-specific language.
1
2
3
4
5
6
7
#lang scribble/manual

@title{jsonic: because JSON is boring}

@defmodulelang[jsonic]

This is a domain-specific language.
copy to clipboard

The title of the main docu­men­ta­tion file is the name that will show up in the table of contents. This func­tion takes a text argu­ment that we put between curly brackets. The title can be anything we want, though of course it’s nice to make it descrip­tive.

The defmodulelang decla­ra­tion tells Racket that this is the starting point for the docu­men­ta­tion for a partic­ular language. That way, if someone searches the Racket docu­men­ta­tion for jsonic, it will take them to this page. defmodulelang takes the name of our language as input, which is an iden­ti­fier, not a string, so we put it between square brackets, not curly ones.

The body is entered as plain text.

If we save our "jsonic.scrbl" and click Scribble HTML again, we’ll now see this in our web browser:

What we’re seeing is a preview of the docu­men­ta­tion that will be added locally when a user installs our language (and, if we upload our language to the the package server, the docu­men­ta­tion that will be added to docs.racket-lang.org).

We can also add an author name and section title:

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
#lang scribble/manual

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language.
copy to clipboard

Again, we can preview these changes by clicking Scribble HTML:

How about adding cross-refer­ences to other Racket libraries and func­tions? We can refer to a top-level module like json by using racketmodname, which will auto­mat­i­cally create a hyper­linked cross-refer­ence to the main page of the json docu­men­ta­tion:

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#lang scribble/manual

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.
copy to clipboard

Which will look like this:

Inserting a cross-refer­ence to a specific func­tion like jsexpr->string happens in two steps. First, we wrap the term in racket, which flags it as a Racket iden­ti­fier. Scribble will link this to a docu­men­ta­tion entry if the iden­ti­fier is bound, other­wise it will be typeset as plain code. To bind the iden­ti­fier so Scribble can see it, we require the json module using the special for-label qual­i­fier:

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual
@(require (for-label json))

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.

In particular, the @racket[jsexpr->string] function.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
#lang scribble/manual
@(require (for-label json))

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.

In particular, the @racket[jsexpr->string] function.
copy to clipboard

The result:

Beyond that, we can docu­ment our language however we like. We’ll prob­ably want to show some sample code and results. For that, we’ll use verbatim to print before-and-after samples:

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual
@(require (for-label json))

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.

In particular, the @racket[jsexpr->string] function.

If we start with this:

@verbatim{
#lang jsonic
[
  @$ 'null $@,
  @$ (* 6 7) $@,
  @$ (= 2 (+ 1 1)) $@
]
}

We'll end up with this:

@verbatim{
[
  null,
  42,
  true
]
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
#lang scribble/manual
@(require (for-label json))

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.

In particular, the @racket[jsexpr->string] function.

If we start with this:

@verbatim{
#lang jsonic
[
  @$ 'null $@,
  @$ (* 6 7) $@,
  @$ (= 2 (+ 1 1)) $@
]
}

We'll end up with this:

@verbatim{
[
  null,
  42,
  true
]
}
copy to clipboard

But this time, when we click on Scribble HTML, we get an error:

unexpected whitespace after @
1
unexpected whitespace after @
copy to clipboard

The problem is that Scribble sees the @ signs within the jsonic sample code and thinks they intro­duce nested @-expres­sions. As the docs for verbatim would tell us, we can disable this assump­tion by using |{...}| as delim­iters rather than plain {...}:

jsonic/scribblings/jsonic.scrbl
#lang scribble/manual
@(require (for-label json))

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.

In particular, the @racket[jsexpr->string] function.

If we start with this:

@verbatim|{
#lang jsonic
[
  @$ 'null $@,
  @$ (* 6 7) $@,
  @$ (= 2 (+ 1 1)) $@
]
}|

We'll end up with this:

@verbatim{
[
  null,
  42,
  true
]
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
#lang scribble/manual
@(require (for-label json))

@title{jsonic: because JSON is boring}
@author{Roxy Lexington}

@defmodulelang[jsonic]

@section{Introduction}

This is a domain-specific language
that relies on the @racketmodname[json] library.

In particular, the @racket[jsexpr->string] function.

If we start with this:

@verbatim|{
#lang jsonic
[
  @$ 'null $@,
  @$ (* 6 7) $@,
  @$ (= 2 (+ 1 1)) $@
]
}|

We'll end up with this:

@verbatim{
[
  null,
  42,
  true
]
}
copy to clipboard

This time, we’ll get the right result:

Of course, in real life we’d want to elab­o­rate further. But this will suffice for now.

By the way

When we use the Scribble HTML button to preview our docu­men­ta­tion, it creates a number of CSS and JavaScript files in the same direc­tory. These are needed to display the page. But they can be deleted after­ward. When Scribble builds the local docu­men­ta­tion during the package instal­la­tion, it relies on shared copies of these files.

Alter­na­tively, the project server included in the Pollen package can be used to preview Scribble source files. This can be conve­nient if we’re editing Scribble sources in some­thing other than DrRacket (in which case the Scribble HTML button won’t be avail­able).

← prev next →