6 Core Datatypes
A Scribble document is meant to be independent of its rendered form (HTML, PDF, etc.), and Scribble’s plug-in architecture accommodates new rendering back-ends. In particular, Scribble defers detailed typesetting work to LaTeX or to HTML browsers.
Scribble’s documentation abstraction reflects a least-common denominator among such document formats. For example, Scribble has a baked-in notion of itemization, since LaTeX, HTML, and other document formats provide specific support to typeset itemizations. For many other layout tasks, such as formatting Scheme code, Scribble documents fall back to a generic “table” abstraction. Similarly, Scribble itself resolves most forms of cross-references and document dependencies, since different formats provide different levels of automatic support; tables of contents and indexes are mostly built within Scribble, instead of the back-end.
A Scribble document is a program that generates an instance of a part structure type. A part can represent a section or a book, and it can have sub-parts that represent sub-sections or chapters. This paper, for example, is generated by a Scribble document whose resulting part represents the whole paper, and it contains sub-parts for individual sections. The part produced by a Scheme document for a reference manual is rendered as a book, where the immediate sub-parts are chapters.
Figure 2 summarizes the structure of a document under part in a UML-like diagram. When a field contains a list, the diagram shows a double arrow, and when a field contains a lists of lists, the diagram shows a triple arrow. The dashed arrows call attention to delayed fields, as explained below.
Each part has a flow that is typeset before its sub-parts (if any), and that represents the main content of a section. A flow is a list of blocks, where each block is one of the following:
A paragraph, which contains a list of elements that are typeset inline with automatic line breaks.
A table, which contains a list of rows; each row is a list of flows, one for each cell in the table.
An itemization, which contains a list of flows, one for each item.
A blockquote, which contains a single flow that is typically typeset with more indentation than its surrounding flow.
A delayed-block, which eventually expands to another block, using information gathered elsewhere in the document. Accordingly, the block field of a delayed-block is not just a block, but a function that computes a block when given that other information. For example, a delayed-block is used to implement a table of contents.
A Scribble document can construct other kinds of blocks that are implemented in terms of the above built-in kinds. For example, a defproc block that describes a procedure is implemented in terms of a table.
An element within a paragraph can be one of the following:
A plain string.
An instance of the element structure type, which wraps a list of elements with a typesetting style, such as 'bold, whose detailed interpretation depends on the back-end format.
A target-element, which associates a cross-reference tag with a list of elements. The typeset elements are the target for cross-references using the tag.
A link-element, which associates a cross-reference tag to a list of elements. The tag designates a cross-reference from the elements to elsewhere in the document (which is rendered in HTML as a hyperlink from the elements).
A delayed-element eventually expands to a list of elements. Like a delayed-block, it typically generates the elements using information gathered from elsewhere in the document. A delayed-element often generates a link-element after it locates a suitable target for cross-referencing.
A collect-element is the complement of delayed-element: it includes an immediate list of elements, but also a procedure to record information that might be used elsewhere in the document. A collect-element often includes a target-element, in which case its procedure might register the target’s cross-reference tag for discovery by delayed-element instances.
A few other element types support more specialized tasks, such as communicating between phases and specifying tooltips.
A document as represented by a part instance is an immutable value. This value is transformed in several passes to eliminate delayed-block instances, delayed-element instances, and collect-element instances. The result is a part instance and associated cross-reference information. Once the cross-reference information has been computed, it is saved for use when building other documents that have cross-references to this one. Finally, the part instance is consumed by a rendering back-end to produce the final document.
In the current implementation of Scribble, all documents are transformed in only two passes: a collect pass that collects information about the document (e.g., through collect-elements), and a resolve pass that turns delayed blocks and elements into normal elements. We could easily generalize to multiple passes, but so far, two passes have been sufficient within a single document. When multiple documents that refer to each other are built separately, these passes are iterated as explained in Building and Installing Documentation.
In some cases, the output of Scribble needs customization that is specific to a back-end. Users of Scribble provide the customization information by supplying a mapping from the contents of the style field in the various structures the style’s back-end rendering. For HTML output, a CSS fragment can extend or override the default Scribble style sheet. For LaTeX output, a ".tex" file can extend or redefine the default Scribble LaTeX commands.