► |  | 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 | Tag Utilities
7.10 | Extending and Configuring Scribble Output

► | 7.4 | Renderers

7.4.1 | Rendering Driver
7.4.2 | Base Renderer
7.4.3 | Text Renderer
7.4.4 | Markdown Renderer
7.4.5 | HTML Renderer
7.4.6 | Latex Renderer
7.4.7 | PDF Renderer
7.4.8 | Contract (Blue boxes) Renderer

On this page:

7.4.1`` Rendering Driver
render
7.4.2`` Base Renderer
render<%>
traverse
collect
resolve
render
serialize-info
serialize-infos
deserialize-info
get-defined
get-defineds
get-external
get-undefined
render%
new
7.4.3`` Text Renderer
render-mixin
7.4.4`` Markdown Renderer
render-mixin
7.4.5`` HTML Renderer
render-mixin
set-external-tag-path
set-external-root-url
render-multi-mixin
set-directory-depth
7.4.6`` Latex Renderer
render-mixin
7.4.7`` PDF Renderer
render-mixin
7.4.8`` Contract (Blue boxes) Renderer
override-render-mixin-multi
render
override-render-mixin-single
render

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) | package: scribble-lib

> > 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 |  |  |  |
> > |  | #:directory-depth directory-depth |  |  |  |
> > |  | #: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
> directory-depth : exact-nonnegative-integer? = 0
> 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, style-extra-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.

The directory-depth arguments correspond to the set-directory-depth method of render-multi-mixin.

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) | package: scribble-lib

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/markdown-render, or 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 [demand]) → collect-info?
> > srcs : (listof part?)
> > dests : (listof path-string?)
> > fp : (and/c hash? immutable?)
> > | demand |  | : |  | (tag? collect-info? . -> . any/c)
> > |  |  | = |  | (lambda (tag ci) #f)

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

> The demand argument supplies external tag mappings on demand. When the collect-info result is later used to find a mapping for a tag and no mapping is already available, demand is called with the tag and the collect-info. The demand function returns true to indicate when it adds information to the collect-info so that the lookup should be tried again; the demand function should return #f if it does not extend collect-info.

> > 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 serialize-infos ri count doc) → list?
> > ri : resolve-info?
> > count : exact-positive-integer?
> > doc : part?

> Like serialize-info, but produces count results that together have the same information as produced by serialize-info. The structure of doc is used to drive the partitioning (on the assumption that ri is derived from doc).

> > > 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-defineds ci count doc)
> > → (listof (listof tag?))
> > ci : collect-info?
> > count : exact-positive-integer?
> > doc : part?

> Analogous to serialize-infos: returns a list of tags for each of count partitions of the result of get-defined, using the structure of doc to drive the partitioning.

> > 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) | package: scribble-lib

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

Specializes a render<%> class for generating plain text.

##### 7.4.4`` Markdown Renderer

(require scribble/markdown-render)
| package: scribble-lib

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

Specializes a render<%> class for generating Markdown text.

Code blocks are marked using the Github convention

```racket

so that they are lexed and formatted as Racket code.

##### 7.4.5`` HTML Renderer

(require scribble/html-render) | package: scribble-lib

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.

> > method (send a-render-multi set-directory-depth depth) → void?
> > depth : exact-nonnegative-integer?

> Sets the depth of directory structure used when rendering parts that are own their own pages. A value of 0 is treated the same as 1.

##### 7.4.6`` Latex Renderer

(require scribble/latex-render) | package: scribble-lib

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

Specializes a render<%> class for generating Latex input.

##### 7.4.7`` PDF Renderer

(require scribble/pdf-render) | package: scribble-lib

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

(require scribble/contract-render)
| package: scribble-lib

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 →