On this page:
Scribble:   The Racket Documentation Tool
6.5

Scribble: The Racket Documentation Tool

Matthew Flatt
and Eli Barzilay

Scribble is a collection of tools for creating prose documents—papers, books, library documentation, etc.—in HTML or PDF (via Latex) form. More generally, Scribble helps you write programs that are rich in textual content, whether the content is prose to be typeset or any other form of text to be generated programmatically.

This document is itself written using Scribble. You can see its source at https://github.com/racket/scribble/tree/master/scribble-doc/scribblings/scribble, starting with the "scribble.scrbl" file.

    1 Getting Started

      1.1 A First Example

      1.2 Multiple Sections

      1.3 Splitting the Document Source

      1.4 Document Styles

      1.5 More Functions

        1.5.1 Centering

        1.5.2 Margin Notes

        1.5.3 Itemizations

        1.5.4 Tables

      1.6 Text Mode vs. Racket Mode for Arguments

      1.7 @ Syntax Basics

      1.8 Decoding Sequences

      1.9 Pictures

      1.10 Next Steps

    2 @ Syntax

      2.1 The Scribble Syntax at a Glance

      2.2 The Command Part

      2.3 The Datum Part

      2.4 The Body Part

        2.4.1 Alternative Body Syntax

        2.4.2 Racket Expression Escapes

        2.4.3 Comments

        2.4.4 Spaces, Newlines, and Indentation

    3 High-Level Scribble API

      3.1 Base Document Format

        3.1.1 Document Structure

        3.1.2 Blocks

        3.1.3 Text Styles and Content

        3.1.4 Images

        3.1.5 Spacing

        3.1.6 Links

        3.1.7 Indexing

        3.1.8 Tables of Contents

        3.1.9 Tags

      3.2 Racket Manual Format

      3.3 Book Format

      3.4 Report Format

      3.5 SIGPLAN Paper Format

      3.6 JFP Paper Format

      3.7 LNCS Paper Format

        3.7.1 Example

    4 Scribbling Documentation

      4.1 Getting Started with Documentation

        4.1.1 Setting Up Library Documentation

        4.1.2 Racket Typesetting and Hyperlinks

        4.1.3 Section Hyperlinks

        4.1.4 Defining Racket Bindings

        4.1.5 Showing Racket Examples

        4.1.6 Multi-Page Sections

      4.2 Style Guide

        4.2.1 Prose and Terminology

        4.2.2 Typesetting Code

        4.2.3 Typesetting Prose

        4.2.4 Section Titles

        4.2.5 Indexing

        4.2.6 Examples

      4.3 Manual Forms

        4.3.1 Typesetting Code

          4.3.1.1 #lang-Specified Code

          4.3.1.2 Racket Code

          4.3.1.3 Preserving Comments

          4.3.1.4 Code Fonts and Styles

        4.3.2 Documenting Modules

        4.3.3 Documenting Forms, Functions, Structure Types, and Values

        4.3.4 Documenting Classes and Interfaces

        4.3.5 Documenting Signatures

        4.3.6 Various String Forms

        4.3.7 Links

        4.3.8 Indexing

        4.3.9 Bibliography

        4.3.10 Version History

        4.3.11 Miscellaneous

        4.3.12 Index-Entry Descriptions

        4.3.13 Manual Rendering Style

      4.4 Racket

      4.5 Evaluation and Examples

        4.5.1 Legacy Evaluation

      4.6 In-Source Documentation

        4.6.1 Source Annotations for Documentation

        4.6.2 Extracting Documentation from Source

      4.7 BNF Grammars

      4.8 Compatibility Libraries

        4.8.1 Compatibility Structures And Processing

        4.8.2 Compatibility Basic Functions

    5 Literate Programming

      5.1 scribble/lp2 Language

      5.2 scribble/lp Language

      5.3 scribble/lp-include Module

    6 Low-Level Scribble API

      6.1 Scribble Layers

        6.1.1 Typical Composition

        6.1.2 Layer Roadmap

      6.2 @ Reader Internals

        6.2.1 Using the @ Reader

        6.2.2 Syntax Properties

        6.2.3 Adding @-expressions to a Language

        6.2.4 Interface

      6.3 Structures And Processing

        6.3.1 Parts, Flows, Blocks, and Paragraphs

        6.3.2 Tags

        6.3.3 Styles

        6.3.4 Collected and Resolved Information

        6.3.5 Structure Reference

        6.3.6 HTML Style Properties

        6.3.7 Latex Style Properties

      6.4 Renderers

        6.4.1 Rendering Driver

        6.4.2 Base Renderer

        6.4.3 Text Renderer

        6.4.4 Markdown Renderer

        6.4.5 HTML Renderer

        6.4.6 Latex Renderer

        6.4.7 PDF Renderer

        6.4.8 Contract (Blue boxes) Renderer

      6.5 Decoding Text

      6.6 Document Language

        6.6.1 scribble/doclang

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

    7 Running scribble

      7.1 Extra and Format-Specific Files

      7.2 Handling Cross-References

      7.3 Selecting an Image Format

      7.4 Passing Command-Line Arguments to Documents

    Index