► |  | 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 | Extending and Configuring Scribble Output
7.10 | Connecting to "racket"

► | 7.4 | Renderers

7.4.1 | Rendering Driver
7.4.2 | Base Renderer
7.4.3 | Text Renderer
7.4.4 | HTML Renderer
7.4.5 | Latex Renderer
7.4.6 | PDF Renderer

On this page:

7.4.1`` Rendering Driver
render
7.4.2`` Base Renderer
render%
traverse
collect
resolve
render
serialize-info
deserialize-info
get-defined
get-external
get-undefined
7.4.3`` Text Renderer
render-mixin
7.4.4`` HTML Renderer
render-mixin
set-external-tag-path
set-external-root-url
render-multi-mixin
7.4.5`` Latex Renderer
render-mixin
7.4.6`` PDF Renderer
render-mixin

top← prev up next →

#### 7.4`` Renderers

A renderer is an object that provides four main methods: traverse, collect, resolve, and render. Each method corresponds to a pass described in Structures And Processing, and they are chained together by the render function to render a document.

##### 7.4.1`` Rendering Driver

(require scribble/render)

> > procedure
> > (render |  | docs |  |  |  |
> > |  | names |  |  |  |
> > | [ | #:render-mixin render-mixin |  |  |  |
> > |  | #:dest-dir dest-dir |  |  |  |
> > |  | #:helper-file-prefix helper-file-prefix |  |  |  |
> > |  | #:prefix-file prefix-file |  |  |  |
> > |  | #:style-file style-file |  |  |  |
> > |  | #:style-extra-files style-extra-files |  |  |  |
> > |  | #:extra-files extra-files |  |  |  |
> > |  | #:xrefs xrefs |  |  |  |
> > |  | #:info-in-files info-in-files |  |  |  |
> > |  | #:info-out-file info-out-file |  |  |  |
> > |  | #:redirect redirect |  |  |  |
> > |  | #:redirect-main redirect-main |  |  |  |
> > |  | #:quiet? quiet? |  |  |  |
> > |  | #:warn-undefined? warn-undefined?]) |  | → |  | void?
> docs : (listof part?)
> names : (listof path-string?)
> render-mixin : (class? . -> . class?) = render-mixin
> dest-dir : (or/c #f path-string?) = #f
> helper-file-prefix : (or/c #f string?) = #f
> prefix-file : (or/c #f path-string?) = #f
> style-file : (or/c #f path-string?) = #f
> style-extra-files : (listof path-string?) = #f
> extra-files : (listof path-string?) = #f
> xrefs : (listof xref?) = null
> info-in-files : (listof path-string?) = null
> info-out-file : (or/c #f path-string?) = #f
> redirect : (or/c #f string?) = #f
> redirect-main : (or/c #f string?) = #f
> quiet? : any/c = #t
> warn-undefined? : any/c = (not quiet?)

Renders the given docs, each with an output name derived from the corresponding element of names. A directory path (if any) for a name in names is discarded, and the file suffix is replaced (if any) with a suitable suffix for the output format.

The render-mixin argument determines the output format. By default, it is render-mixin from scribble/html-render.

The dest-dir argument determines the output directory, which is created using make-directory* if it is non-#f and does not exist already.

The helper-file-prefix, prefix-file, style-file, extra-style-files, and extra-files arguments are passed on to the render% constructor.

The xrefs argument provides extra cross-reference information to be used during the documents’ resolve pass. The info-in-files arguments supply additional cross-reference information in serialized form. When the info-out-file argument is not #f, cross-reference information for the rendered documents is written in serialized for to the specified file.

The redirect and redirect-main arguments correspond to the set-external-tag-path and set-external-root-url methods of render-mixin from scribble/html-render, so they should be non-#f only for HTML rendering.

If quiet? is a false value, output-file information is written to the current output port.

If warn-undefined? is a true value, then references to missing cross-reference targets trigger a warning message on the current error port.

##### 7.4.2`` 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.rkt" 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.

class render% : class?
superclass: object%

Represents a renderer.

> > > constructor
> > > (new render% |
> > > |  | [dest-dir dest-dir] |
> > > | [ | [refer-to-existing-files refer-to-existing-files] |
> > > |  | [root-path root-path] |
> > > |  | [prefix-file prefix-file] |
> > > |  | [style-file style-file] |
> > > |  | [style-extra-files style-extra-files] |
> > > |  | [extra-files extra-files] |
> > > |  | [helper-file-prefix helper-file-prefix]]) |
> > → (is-a?/c render%)
> > dest-dir : path-string?
> > refer-to-existing-files : any/c = #f
> > root-path : (or/c path-string? #f) = #f
> > prefix-file : (or/c path-string? #f) = #f
> > style-file : (or/c path-string? #f) = #f
> > style-extra-files : (listof path-string?) = null
> > extra-files : (listof path-string?) = null
> > helper-file-prefix : (or/c string? #f) = #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 refer-to-existing-files is true, then when a document refers to external files, such as an image or a style file, then the file is referenced from its source location instead of copied to the document destination.

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

> The prefix-file, style-file, and style-extra-files arguments set files that control output styles in a formal-specific way; see Configuring Output for more information.

> The extra-files argument names files to be copied to the output location, such as image files or extra configuration files.

> The helper-file-prefix argument specifies a string that is added as a prefix to the name of each support file that is generated or copied to the destination—not including files specified in extra-files, but including prefix-file, style-file, and style-extra-files.

> > method (send a-render traverse srcs dests) → (and/c hash? immutable?)
> > srcs : (listof part?)
> > dests : (listof path-string?)

> Performs the traverse pass, producing a hash table that contains the replacements for and traverse-blocks and traverse-elementss. See render for information on the dests argument.

> > method (send a-render collect srcs dests fp) → collect-info?
> > srcs : (listof part?)
> > dests : (listof path-string?)
> > fp : (and/c hash? immutable?)

> Performs the collect pass. See render for information on the dests argument. The fp argument is a result from the traverse method.

> > method (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. The ci argument is a result from the collect method.

> > method (send a-render render srcs dests ri) → void?
> > srcs : (listof part?)
> > dests : (listof path-string?)
> > ri : resolve-info?

> Produces the final output. The ri argument is a result from the render method.

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

> > method (send a-render serialize-info ri) → any/c
> > ri : resolve-info?

> Serializes the collected info in ri.

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

> > method (send a-render get-defined ci) → (listof tag?)
> > ci : collect-info?

> Returns a list of tags that were defined within the documents represented by ci.

> > method (send a-render get-external ri) → (listof tag?)
> > ri : resolve-info?

> Returns a list of tags that were referenced but not defined within the documents represented by ri (though possibly found in cross-reference information transferred to ri via xref-transfer-info).

> > method (send a-render get-undefined ri) → (listof tag?)
> > ri : resolve-info?

> Returns a list of tags that were referenced by the resolved documents with no target found either in the resolved documents represented by ri or cross-reference information transferred to ri via xref-transfer-info.

> If multiple tags were referenced via resolve-search and a target was found for any of the tags using the same dependency key, then no tag in the set is included in the list of undefined tags.

##### 7.4.3`` Text Renderer

(require scribble/text-render)

mixin render-mixin : (class? . -> . class?)
argument extends/implements: | render%

Specializes a render% class for generating plain text.

##### 7.4.4`` HTML Renderer

(require scribble/html-render)

mixin render-mixin : (class? . -> . class?)
argument extends/implements: | render%

Specializes a render% class for generating HTML output.

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

> > method (send a-render set-external-root-url url) → void?
> > url : string?

> Configures the renderer to redirect links to documents installed in the distribution’s documentation directory to the given URL, using the URL as a replacement to the path of the distribution’s document directory.

mixin render-multi-mixin : (class? . -> . class?)
argument extends/implements: | render%

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

##### 7.4.5`` Latex Renderer

(require scribble/latex-render)

mixin render-mixin : (class? . -> . class?)
argument extends/implements: | render%

Specializes a render% class for generating Latex input.

##### 7.4.6`` PDF Renderer

(require scribble/pdf-render)

mixin render-mixin : (class? . -> . class?)
argument extends/implements: | render%

Specializes a render% class for generating PDF output via Latex, building on render-mixin from scribble/latex-render.

top← prev up next →