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

Danny Yoo <[email protected]>

The (planet dyoo/scribble-bootstrap:3: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:3

@title{Example}

This is a Scribble document that includes conditional output.

@;; Let us declare the following tags.

@declare-tags[reading pedagogy group]

@;; We can tag certain content to be generated conditionally:

@tag[reading]{This is text for reading.}

@tag[group]{

This is text for group work.

@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.

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

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:

2 API

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

2.1 Tagging Content

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.

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

2.2 Question types and formatting

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.

The selection will have the CSS style BootstrapWorksheet.

The selection will have the CSS style BootstrapLesson.

The selection will have the CSS style BootstrapDrill.

The selection will have the CSS style BootstrapExercise.

The selection will have the CSS style BootstrapDemo.

The selection will have the CSS style BootstrapSkit.

For example:

#lang planet dyoo/scribble-bootstrap

@materials[@item{Rock}

@item{Paper}

@item{Scissors}

]

The list will have the CSS style BootstrapMaterialsList, and each item will have the CSS style BootstrapMaterialsListItem.

For example:

#lang planet dyoo/scribble-bootstrap

@goals[@item{Eat}

@item{Sleep}

@item{Study}

]

The list will have the CSS style BootstrapGoalsList, and each item will have the CSS style BootstrapGoalsListItem.

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.)