5 Renderer

A renderer is an object that provides two main methods: collect and render. The first method is called to collect global information about the document, including information that spans multiple documents rendered together; the collection pass tends to be format-independent, and it usually implemented completely by the base renderer. The latter method generates the actual output, which is naturally specific to a particular format.

5.1 Base Renderer

(require scribble/base-render)

The scribble/base-render module provides render%, which implements the core of a renderer. This rendering class must be refined with a mixin from scribble/text-render, scribble/html-render, or scribble/latex-render.

The mixin structure is meant to support document-specific extensions to the renderers. For example, the scribble command-line tool might, in the future, extract rendering mixins from a document module (in addition to the document proper).

See the "base-render.ss" source for more information about the methods of the renderer. Documents built with higher layers, such as scribble/manual, generally do not call the render object’s methods directly.

render% : class?

superclass: object%

Represents a renderer.

(new render%       [dest-dir dest-dir]      [ [refer-to-existing-files refer-to-existing-files]       [root-path root-path]])

→ (is-a?/c render%)

dest-dir : path-string?

refer-to-existing-files : any/c = #f

root-path : (or/c path-string? false/c) = #f

Creates a renderer whose output will go to dest-dir. For example, dest-dir could name the directory containing the output Latex file, the HTML file for a single-file output, or the output sub-directory for multi-file HTML output.

If root-path is not #f, it is normally the same as dest-dir or a parent of dest-dir. It causes cross-reference information to record destination files relative to root-path; when cross-reference information is serialized, it can be deserialized via deserialize-info with a different root path (indicating that the destination files have moved).

(send a-render collect srcs dests) → collect-info?

srcs : (listof part?)

dests : (listof path-string?)

Performs the collect pass. See render for information on the dests argument.

(send a-render resolve srcs dests ci) → resolve-info?

srcs : (listof part?)

dests : (listof path-string?)

ci : collect-info?

Performs the resolve pass. See render for information on the dests argument.

(send a-render render srcs dests ri) → void?

srcs : (listof part?)

dests : (listof path-string?)

ri : resolve-info?

Produces the final output.

The dests provide names of files for Latex or single-file HTML output, or names of sub-directories for multi-file HTML output. If the dests are relative, they’re relative to the current directory; normally, they should indicates a path within the dest-dir supplied on initialization of the render% object.

(send a-render serialize-info ri) → any/c

ri : resolve-info?

Serializes the collected info in ri.

(send a-render deserialize-info   v             ci            [ #:root root-path])   →   void?

v : any/c

ci : collect-info?

root-path : (or/c path-string? false/c) = #f

Adds the deserialized form of v to ci.

If root-path is not #f, then file paths that are recorded in ci as relative to an instantiation-supplied root-path are deserialized as relative instead to the given root-path.

5.2 Text Renderer

(require scribble/text-render)

render-mixin : (class? . -> . class?)

argument extends/implements:  render%

Specializes a render% class for generating plain text.

5.3 HTML Renderer

(require scribble/html-render)

render-mixin : (class? . -> . class?)

argument extends/implements:  render%

Specializes a render% class for generating HTML output.

(send a-render set-external-tag-path url) → void?

url : string?

Configures the renderer to redirect links to external via url, adding a tag query element to the end of the URL that contains the Base64-encoded, printed, serialized original tag (in the sense of link-element) for the link.

render-multi-mixin : (class? . -> . class?)

argument extends/implements:  render%

Further specializes a rendering class produced by render-mixin for generating multiple HTML files.

5.4 Latex Renderer

(require scribble/latex-render)

render-mixin : (class? . -> . class?)

argument extends/implements:  render%

Specializes a render% class for generating Latex input.