► |  | Scribble: The Racket Documentation Tool

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

► | 6 | Low-Level Scribble API

6.1 | Scribble Layers
6.2 | @ Reader Internals
6.3 | Structures And Processing
6.4 | Renderers
6.5 | Decoding Text
6.6 | Document Language
6.7 | Document Reader
6.8 | Cross-Reference Utilities
6.9 | Tag Utilities
6.10 | Blue Boxes Utilities
6.11 | Extending and Configuring Scribble Output

▼ | 6.11 | Extending and Configuring Scribble Output

6.11.1 | Implementing Styles
6.11.2 | Configuring Output
6.11.3 | Base CSS Style Classes
6.11.4 | Manual CSS Style Classes
6.11.5 | Base Latex Macros
6.11.6 | Latex Prefix Support

top ← prev up next →

##### 6.11.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 raco setup 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.

top ← prev up next →