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

6.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
#:image-preferences image-preferences
#: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
   image-preferences : (listof (or/c 'ps 'pdf 'png 'svg 'gif))
= null
  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 image-preferences argument specified preferred formats for image files and conversion, where formats listed earlier in the list are more preferred. The renderer specified by render-mixin may not support all of the formats listed in image-preferences.

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.

Changed in version 1.4 of package scribble-lib: Added the #:image-preferences argument.

6.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]
    [image-preferences image-preferences]])
→ (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
   image-preferences : (listof (or/c 'ps 'pdf 'png 'svg 'gif))
= 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.
The image-preferences argument specified preferred formats for image files and conversion, where formats listed earlier in the list are more preferred. The renderer may not support all of the formats listed in image-preferences.
Changed in version 1.4 of package scribble-lib: Added the image-preferences initialization argument.

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

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

6.4.5 HTML Renderer

(require scribble/html-render)

package: scribble-lib

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

argument extends/implements:

render<%>

constructor
(new render-mixin
    [ [search-box? search-box?]]
    ...superclass-args...)
→ (is-a?/c render-mixin)
  search-box? : boolean? = #f
Specializes a render<%> class for generating HTML output. The arguments are the same as render<%>, except for the addition of search-box.
If search-box? is #t and the document is created with scribble/manual, then it will be rendered with a search box, similar to this page. Note that the search-box? argument does not create the search page itself. Rather, it passes the search query to whatever page is located at search/index.html. The query is passed as an HTTP query string in the q field.
method
(send a-render set-external-tag-path url) → void?
  url : string?
Configures the renderer to redirect links to external documents 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.
If the link is based on a cross-reference entry that has a document-identifying string (see load-xref and its #:doc-id argument), the document identifier is added as a doc query element, and a path to the target within the document is added as a rel query element.
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.

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

parameter
(extra-character-conversions) → (-> char? (or/c string? #f))
(extra-character-conversions convs) → void?
convs : (-> char? (or/c string? #f))

Function that maps (special) characters to strings corresponding to the Latex code that should be used to render them. This function should return false for any character it does not know how to handle.

Scribble already converts many special characters to the proper Latex commands. This parameter should be used in case you need characters it does not support yet.

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

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

1	Getting Started
2	@ Syntax
3	High-Level Scribble API
4	Scribbling Documentation
5	Literate Programming
6	Low-Level Scribble API
7	Running scribble
	Index

6.1	Scribble Layers
6.2	@ Reader Internals
6.3	Structures And Processing
6.4	Renderers
6.5	Decoding Text
6.6	Document Language
6.7	Document Reader
6.8	Cross-Reference Utilities
6.9	Tag Utilities
6.10	Blue Boxes Utilities
6.11	Extending and Configuring Scribble Output

6.4.1	Rendering Driver
6.4.2	Base Renderer
6.4.3	Text Renderer
6.4.4	Markdown Renderer
6.4.5	HTML Renderer
6.4.6	Latex Renderer
6.4.7	PDF Renderer
6.4.8	Contract (Blue boxes) Renderer