A guide to the (planet dyoo/scribble-bootstrap:2:=0) Scribble library

The (planet dyoo/scribble-bootstrap:2:=0) library provides preliminary Scribble document support for the Bootstrap curriculum. Specifically, it allows documents to include conditional content (e.g. generating content for teachers or students), as well as commands to embed forms and embedded WeScheme instances.

It will eventually include support for validating the content of these forms, as well as saving the contents of the form to server-side storage.

1 Getting started

Let’s start with the following document:

"example.scrbl"
#lang planet dyoo/scribble-bootstrap
@title{Example}
This is a Scribble document that includes conditional output.

@;; Let us declare the following tags.
@declare-tags[reading instruction pedagogy exercise skit]

@;; We can tag certain content to be generated conditionally:
@tag[reading]{This is text for reading.}

@tag[instruction]{
This is text for instruction.
@tag[pedagogy]{This is text for pedagogy.}}

We can then generate different renderings of this document based on the audience, by using a SCRIBBLE_TAGS environmental variable to provide the necessary context.

For example, at the Unix command line:

$ SCRIBBLE_TAGS=reading scribble example.scrbl

should generate the file "example.html" with content for readers.

We can generate the code in an instructional context:

$ SCRIBBLE_TAGS=instruction scribble example.scrbl

which omits the content for the reading context, and also excludes the pedagogic content.

To generate content that shows for both instruction and pedagogy, use quotes (") so the Unix shell allows you to assign multiple tags into SCRIBBLE_TAGS:

$ SCRIBBLE_TAGS="instruction pedagogy" scribble \
example.scrbl

will show the content for both instruction and pedagogy.

2 API

The (planet dyoo/scribble-bootstrap:2:=0) library includes a Scribble-based language that provides all the bindings of scribble/base, as well as the following forms:

(declare-tags tags ...)

Declares the set of tags that will be used in this document. Any use of tag later in the document will verify that the tags have already been declared in a declare-tags.

For example:

#lang planet dyoo/scribble-bootstrap

@declare-tags[instruction pedagogy example]

(tag tags body ...)

This form acts as an ifdef, and blocks off a section of the scribble document with a tag. Its content shows only in a context that includes the given tag.

For example:

#lang planet dyoo/scribble-bootstrap
@declare-tags[student teacher]

@tag[student]{Can be seen by student.}
@tag[teacher]{Can be seen by teacher.}

A section can be tagged with multiple tags at a time by providing a parenthesized list of tags.

@tag[(student teacher)]{Can be seen by both students and teachers.}

This acts as as a union: if the document is generated in a context including any of the tags, then it will be rendered.

Nested tags act as intersection. For example:

@tag[teacher]{
  @tag[student]{
      Hello world.
  }
}

should generate no content unless both the teacher and student tags are in play.

Using tag with a tag that hasn’t been previously declared with declare-tags is a compile-time error.

Tagged content will be generated during Scribble-generation time if the SCRIBBLE_TAGS environmental variable includes them. For example:

$ SCRIBBLE_TAGS=reading scribble example.scrbl

generates "example.scrbl" in a context that enables tagged content using the reading tag.

(fill-in-the-blank #:id id
[ #:columns columns
#:label label]) → element?
  id : string?
  columns : number? = 50
  label : (or/c string? #f) = #f

Creates an empty one-line text element. The #:columns allows customization of the number of columns of the element. The #:label element shows placeholder text content when the element is empty.

Example:

#lang planet dyoo/scribble-bootstrap
This is a fill in the blank: @fill-in-the-blank[#:id "name"
#:label "What's your name?"]

(free-response #:id id
[ #:columns columns
#:rows rows
#:label label]) → element?
  id : string?
  columns : number? = 50
  rows : number? = 20
  label : (or/c string? #f) = #f

Creates an empty multi-line element. The #:columns and #:rows keywords allow customization of the number of columns and rows of the element. The #:label element shows placeholder text content when the element is empty.

Example:

#lang planet dyoo/scribble-bootstrap
This is a free-response: @free-response[#:id "summary"]

(embedded-wescheme #:id id
[ #:width width
#:height height
#:public-id pid
#:interactions-text interactions-text
#:hide-header? hide-header
#:hide-footer? hide-footer
#:hide-definitions? hide-definitions?])
→ element?
  id : string?
  width : (or/c number string?) = "90%"
  height : (or/c number string?) = "500px"
  pid : (or/c string? #f) = #f
  interactions-text : (or/c string #f) = #f
  hide-header : boolean? = #f
  hide-footer : boolean? = #t
  hide-definitions? : boolean? = #f

Creates an embedded WeScheme instance. The keywords #:width and #:height control the dimensions of the embedded instance.

If provided a #:public-id, the embedded instance will load the published WeScheme program with that id.

If provided a #:interactions-text, the embedded instance will initialize the interactions window with the given string.

3 Caveats

At the moment, the conditional tag logic is performed at compile-time rather than run-time. This means that if you compile a ".scrbl" file with raco make, that decision has been committed to the bytecode, so that if you re-render the document, scribble does not revisit the choice.

Scribble itself uses the term "tag" as a mechanism for cross-referencing and linking. The bootstrap support’s use of the "tag" term is not the same. (We may want to use different terminology to avoid this conflict.)