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

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.