► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Text Generation
7 | Low-Level Scribble API
8 | Running scribble
| Index

▼ | 7 | Low-Level Scribble API

7.1 | Scribble Layers
7.2 | @ Reader Internals
7.3 | Structures And Processing
7.4 | Renderers
7.5 | Decoding Text
7.6 | Document Language
7.7 | Document Reader
7.8 | Cross-Reference Utilities
7.9 | Tag Utilities
7.10 | Extending and Configuring Scribble Output

► | 7.10 | Extending and Configuring Scribble Output

7.10.1 | Implementing Styles
7.10.2 | Configuring Output
7.10.3 | Predefined Latex Macros
7.10.4 | Latex Prefix Support

On this page:

7.10.1`` Implementing Styles
7.10.2`` Configuring Output
7.10.3`` Predefined Latex Macros
7.10.4`` Latex Prefix Support
unicode-encoding-packages

top ← prev up next →

#### 7.10`` 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 Latex to create a specific output effect. For this kind of extension, you will mostly likely attach a css-addition or tex-addition style property to style, where the addition implements the style name. This kind of extension is described in Implementing Styles.

- You may need to produce a document whose page layout is different from the Racket documentation style. For that kind of configuration, you can run the scribble command-line tool and supply flags like --prefix or ++style, or you can associate a html-defaults or latex-defaults style property to the main document’s style. This kind of configuration is described in Configuring Output.

##### 7.10.1`` Implementing Styles

When a string is used as a style in an element, a multiarg-element, paragraph, table, itemization, nested-flow, or compound-paragraph, it corresponds to a CSS class for HTML output or a Latex macro/environment for Latex output. In Latex output, the string is used as a command name for a paragraph and an environment name for a table, itemization, nested-flow, or compound-paragraph; if the style has a 'command style property for a nested-flow or compound-paragraph, then the style name is used as a command instead of an environment; and if the style has a 'multicommand style property for a nested-flow, then the style name is used as a command with multiple arguments. In addition, for an itemization, the style string is suffixed with "Item" and used as a CSS class or Latex macro name to use for the itemization’s items (in place of \item in the case of Latex).

To add a mapping from your own style name to a CSS configuration, add a css-addition structure instance to a style’s style property list. To map a style name to a Latex macro or environment, add a tex-addition structure instance. A css-addition or tex-addition is normally associated with the style whose name is implemented by the adition, but it can also be added to the style for an enclosing part.

Scribble includes a number of predefined styles that are used by the exports of scribble/base. You can use them or redefine them. The styles are specified by "scribble.css" and "scribble.tex" in the "scribble" collection.

The styles used by scribble/manual are implemented by "racket.css" and "racket.tex" in the "scribble" collection. Other libraries, such as scriblib/autobib, similarly implement styles through files that are associated by css-addition and tex-addition style properties.

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/base and scribble/manual will start with S.

For example, a Scribble document

#lang scribble/manual
@(require scribble/core
scribble/html-properties
scribble/latex-properties)
@(define inbox-style
(make-style "InBox"
(list (make-css-addition "inbox.css")
(make-tex-addition "inbox.tex"))))
@title{Quantum Pet}
Do not open: @elem[#:style inbox-style]{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

Scribble documents can also embed specific html tags and attributes. For example, this Scribble document:

> #lang scribble/base
> @(require scribble/core
> scribble/html-properties)
> @(define external-image
> (elem
> #:style
> (style #f
> (list (alt-tag "img")
> (attributes
> '((src . "http://racket-lang.org/icon.png")))))))
> @external-image

renders as the the Racket logo at the url http://racket-lang.org/logo.png when producing html.

##### 7.10.2`` Configuring Output

The implementation of styles used by libraries depends to some degree on separately configurable parameters, and configuration is also possible by replacing style implementations. Latex output is more configurable in the former way, since a document class determines a set of page-layout and font properties that are used by other commands. The style-replacement kind of configuration corresponds to re-defining Latex macros or overriding CSS class attributes. When setup-plt builds PDF documentation, it uses both kinds of configuration to produce a standard layout for Racket manuals; that is, it selects a particular page layout, and it replaces some racket/base styles.

Two kinds of files implement the two kinds of configuration:

- A prefix file determines the DOCTYPE line for HTML output or the \documentclass configuration (and perhaps some addition package uses or other configurations) for Latex output.

  The default prefix files are "scribble-prefix.html" and "scribble-prefix.tex" in the "scribble" collection.

- A style file refines the implementation of styles used in the document—typically just the “built-in” styles used by scribble/base.

  The default style files, "scribble-style.css" and "scribble-style.tex" in the "scribble" collection, change no style implementations.

For a given configuration of output, typically a particular prefix file works with a particular style file. Some prefix or style files may be more reusable. For now, reading the default files is the best way to understand how they interact. A prefix and/or style file may also require extra accomanying files; for example, a prefix file for Latex mode may require a corresponding Latex class file. The default prefix and style files require no extra files.

When rendering a document through the scribble command-line tool, use flags to select a prefix file, style file, and additional accompanying files:

- Select the prefix file using the --prefix flag. (Selecting the prefix file also cancels the default list of accompanying files, if any.)

- Replace the style file using the --style flag. Add additional style definitions and re-definitions using the ++style flag.

- Add additional accompanying files with ++extra.

When using the scribble command-line utility, a document can declare its default style, prefix, and extra files through a html-defaults and/or latex-defaults style property. In particular, when using the scribble command-line tool to generate Latex or PDF a document whose main part is implemented with #lang scribble/manual, the result has the standard Racket manual configuration, because scribble/manual associates a latex-defaults style property with the exported document. The scribble/sigplan language similarly associates a default configuration with an exported document. As libraries imported with require, however, scribble/manual and scribble/sigplan simply implement new styles in a composable way.

Whether or not a document has a default prefix- and style-file configuration through a style property, the defaults can be overridden using scribble command-line flags. Furthermore, languages like scribble/manual and scribble/sigplan add a html-defaults and/or latex-defaults style property to a main-document part only if it does not already have such a property added through the #:style argument of title.

##### 7.10.3`` Predefined Latex Macros

The "scribble.tex" Latex configuration includes several macros and environments that you can redefine to adjust the output style:

- \preDoc — called before the document content; the default does nothing, while the scribble/manual configuration enabled \sloppy.

- \postDoc — called after the document content; the default does nothing.

- \sectionNewpage — called before each top-level section starts; the default does nothing, while the scribble/manual configuration uses \newpage to start each chapter on a new page.

- \SecRefLocal{}{}{} — the first argument is a Latex label, the second argument is a section number, and the third argument is a section title. This macro is used by secref to reference a section (other than a document or top-level section within a document) that has a number and that is local to the current document. The default expands to \SecRef, passing along just the second and third arguments (so that the label is ignored).

- \SecRef{}{} — like \SecRefLocal, but used when the referenced section is in a different document, so that no label is available. The default shows “section” followed by the section number (ignoring the title). The scribble/manual redefinition of this macro shows “§”, the section number, and the title in quotes.

- \ChapRefLocal{}{}{} and \ChapRef{}{} — like \SecRefLocal and \SecRef, but for a top-level section within a document. The default implementation defers to \SecRefLocal or \SecRef.

- \PartRefLocal{}{}{} and \PartRef{}{} — like \SecRefLocal and \SecRef, but for a top-level section within a document whose part has the 'grouper style property. The default \PartRef shows “part” followed by the section number (ignoring the title).

- \BookRefLocal{}{}{} and \BookRef{}{} — like \SecRefLocal and \SecRef, but for a document (as opposed to a section within the document). The default \BookRef implementation shows the title in italic.

- \SecRefLocalUC{}{}{} and \SecRefUC{}{} — like \SecRefLocal and \SecRef, but for Secref. The default \SecRefUC shows “Section” followed by the section number.

- \ChapRefLocalUC{}{}{} and \ChapRefUC{}{} — like \ChapRefLocal and \ChapRef, but for Secref. The default \ChapRefUCimplementation defers to \SecRefUC.

- \PartRefLocalUC{}{}{} and \PartRefUC{}{} — like \PartRefLocal and \PartRef, but for Secref. The default \PartRefUC shows “Part” followed by the section number.

- \BookRefLocalUC{}{}{} and \BookRefUC{}{} — like \BookRefLocal and \BookRef, but for Secref. The default \BookRefUC defers to \BookRef.

- \SecRefLocalUN{}{}, \SecRefUCUN{}, \SecRefLocalUCUN{}{}, \SecRefUN{}, \PartRefLocalUN{}{}, \PartRefUN{}, \PartRefLocalUCUN{}{}, \PartRefUCUN{}, \BookRefLocalUN{}{}, \BookRefUN{}, \BookRefLocalUCUN{}{}, \BookRefUCUN{}, \ChapRefLocalUN{}{}, \ChapRefUN{}, \ChapRefLocalUCUN{}{}, and \ChapRefUCUN{} — like \SecRefLocal, etc., but in the case that a section/part/chapter number is unavailable. The default implementation of \BookRefUN uses \BookRef with an empty first argument. The default \SecRefLocalUN expands to its second argument in quotes followed by “on page” as a \pageref using the first argument, while the default \SecRefUN expands to its only argument in quotes. The default \PartRef and \ChapRef variants expand to the corresponding \SecRef variant.

- \Ssection{}{}, \Ssubsection{}{}, \Ssubsubsection{}{}, \Ssubsubsubsection{}{}, \Ssubsubsubsubsection{}{} — for a top-level section, a second-level section, etc., where the last variant is used for all sections that are deeper than four levels. The first argument corresponds to the optional argument to \section, which is used for the table of contents.

- \Ssectionstar{}, \Ssubsectionstar{}, \Ssubsubsectionstar{}, \Ssubsubsubsectionstar{}, \Ssubsubsubsubsectionstar{} — like \Ssection, etc., but for unnumbered sections that are omitted from the table of contents.

- \Ssectionstarx{}{}, \Ssubsectionstarx{}, \Ssubsubsectionstarx{}{}, \Ssubsubsubsectionstarx{}{}, \Ssubsubsubsubsectionstarx{}{} — like \Ssection, etc., but for unnumbered sections (that nevertheless appear in the table of contents).

- \Sincsection, \Sincsubsection, \Sincsubsubsection, \Sincsubsubsubsection, \Sincsubsubsubsubsection — increments the section counter.

- \Spart{}{}, \Spartstar{}, \Spartstarx{}{}, \Sincpart — like the section commands, but used for in place of \Ssection{}{}, \Ssectionstar{}, etc. for a part with the 'grouper style property.

##### 7.10.4`` Latex Prefix Support

(require scribble/latex-prefix) | package: scribble-lib

Provides a string that is useful for constructing a Latex document prefix.

> value unicode-encoding-packages : string?

A string containing Latex code that is useful after a \documentclass declaration to make Latex work with Unicode characters.
top ← prev up next →