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.

interface
render<%> : interface?

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.

class
render% : class?

superclass: object%

extends:

render<%>

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]])
→ (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
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.

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.

7.4.7 Contract (Blue boxes) Renderer

(require scribble/contract-render)

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

argument extends/implements:

render<%>

Overrides the render method of given renderer to record the content of the blue boxes (generated by defproc, defform, etc) that appear in the document.

method
(send an-override-render-mixin-multi render srcs
dests
ri) → void?
  srcs : (listof part?)
  dests : (listof path?)
  ri : render-info?
Overrides render in render<%>.
In addition to doing whatever the super method does, also save the content of the blue boxes (rendered via a scribble/text-render renderer).
It saves this information in three pieces in a file inside the dests directories called "blueboxes.rktd". The first piece is a single line containing a (decimal, ASCII) number. That number is the number of bytes that the second piece of information occupies in the file. The second piece of information is a hash that maps tag? values to a list of offsets and line numbers that follow the hash table. For example, if the hash maps '(def ((lib "x/main.rkt") abcdef)) to '((10 . 3)), then that means that the documentation for the abcdef export from the x collection starts 10 bytes after the end of the hash table and continues for 3 lines. Multiple elements in the list mean that that tag? has multiple blue boxes and each shows where one of the boxes appears in the file.

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

argument extends/implements:

render<%>

Just like override-render-mixin-multi, except it saves the resulting files in a different place.

method
(send an-override-render-mixin-single render srcs
dests
ri) → void?
  srcs : (listof part?)
  dests : (listof path?)
  ri : render-info?
Overrides render in render<%>.
Just like render, except that it saves the file "blueboxes.rktd" in the same directory where each dests element resides.

top← prev up next →

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.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.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
7.4.7	Contract (Blue boxes) Renderer