18 Extending and Configuring Scribble Output

Sometimes, Scribble’s primitives and built-in styles are insufficient to produce the output that you need. The cases in which you need to extend or configure Scribble fall into two groups:

• You may need to drop into the back-end “language” of CSS or Tex to create a specific output effect. For this kind of extension, you will mostly likely attach a `(css ,file) or `(tex ,file) style to a section and then use a string defined in the file as an element or block style. This kind of extension is described in Adding a Style.

• You may need to produce a document whose page layout is different from the PLT Scheme documentation style. For that kind of configuration, you will most likely run the scribble command-line tool and supply flags like --prefix or ++style. This kind of configuration is described in Configuring Output.

18.1 Adding a Style

When a string is uses as a style in an element, styled-paragraph, table, styled-itemization, or blockquote, it corresponds to a CSS class for HTML output or a Tex macro/environment for Latex output. In Latex output, the string is used as a command name for a styled-paragraph and an environment name for a table, itemization, or blockquote, except that a blockquote style name that starts with \ is used (sans \) as a command instead of an environment. In addition, for an itemization, the style string is suffixed with "Item" and used as a CSS class or Tex macro name to use for the itemization’s items (in place of item in the case of Latex).

Scribble includes a number of predefined styles that are used by the exports of scribble/manual, but they are not generally intended for direct use. For now, use them or redefine them at your own risk.

To add a mapping from your own style name to a CSS configuration, add a `(css ,file) style (in a list of styles) to an enclosing part. To map a style name to a Tex macro (or Latex environment), add a `(tex ,file) style to an enclosing part.

To avoid collisions with future additions to Scribble, start your style name with an uppercase letter that is not S. An uppercase letter helps to avoid collisions with macros defined by Latex packages, and future styles needed by scribble/manual will start with S.

For example, a Scribble document

#lang scribble/doc

@(require manual)

@title[#:style `((css "inbox.css") (tex "inbox.tex"))]{Quantum Pet}

Do not open: @elem[#:style "InBox"]{Cat}

combined with an "inbox.css" that contains

.inbox {

padding: 0.2em;

border: 1px solid #000000;

}

and an "inbox.tex" that contains

\newcommand{\InBox}[1]{\fbox{#1}}

generates

Quantum Pet

Do not open: Cat

18.2 Configuring Output

Scribble’s output is configured in two layers:

• A prefix determines the DOCTYPE line for HTML output or the documentclass configuration (and perhaps some addition package uses or other configuration) for Latex output. The default prefix is "scribble-prefix.html" or "scribble-prefix.tex" in the "scribble" collection.

• Style definitions for all of the “built-in” styles used by scribble/manual (as described in Adding a Style). The default style definitions are "scribble.css" or "scribble.tex" in the "scribble" collection.

When using the scribble command-line utility:

• Replace the prefix using the --prefix flag.

• Replace the style definitions using the --style flag.

• Add style definitions (that can override earlier ones) using the ++style flag.

For now, reading the default files is the best way to understand how they interact.