6.4 Renderers

► |  | Scribble: The Racket Documentation Tool

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 | Low-Level Scribble API

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

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

On this page:

6.4.1`` Rendering Driver
render
6.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
traverse
start-traverse
traverse-part
traverse-flow
traverse-block
traverse-nested-flow
traverse-table
traverse-itemization
traverse-compound-paragraph
traverse-paragraph
traverse-content
traverse-target-element
traverse-index-element
collect
start-collect
collect-part
collect-part-tags
collect-flow
collect-block
collect-nested-flow
collect-table
collect-itemization
collect-compound-paragraph
collect-paragraph
collect-content
collect-target-element
collect-index-element
resolve
start-resolve
resolve-part
resolve-flow
resolve-block
resolve-nested-flow
resolve-table
resolve-itemization
resolve-compound-paragraph
resolve-paragraph
resolve-content
render
render-one
render-part
render-part-content
render-flow
render-block
render-nested-flow
render-table
render-auxiliary-table
render-itemization
render-compound-paragraph
render-intrapara-block
render-paragraph
render-content
render-other
6.4.3`` Text Renderer
render-mixin
6.4.4`` Markdown Renderer
render-mixin
current-markdown-link-sections
6.4.5`` HTML Renderer
render-mixin
new
set-external-tag-path
set-external-root-url
render-multi-mixin
set-directory-depth
6.4.6`` Latex Renderer
render-mixin
extra-character-conversions
6.4.7`` PDF Renderer
render-mixin
dvi-render-mixin
xelatex-render-mixin
lualatex-render-mixin
6.4.8`` Contract (Blue boxes) Renderer
override-render-mixin-multi
render
override-render-mixin-single
render

top contents ← prev up next →

#### 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 |
> > |  | #:keep-existing-helper-files? keep-existing-helper-files? |
> > |  | #: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
> keep-existing-helper-files? : any/c = #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, keep-existing-helper-files?, 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.
Changed in version 1.40: Added the --keep-existing-helper-files? initialization argument and fixed --helper-file-prefix to work correctly for HTML output.

##### 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) → list?
> > srcs : (listof part?)
> > dests : (listof (or/c path-string? #f))
> > 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.

> If an element of dests is #f, then the corresponding position of the result list contains a string for rendered document. Some renderers require that dest contains all path strings.

> > 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 |  |  |  |
> > > |  | #:pkg pkg]) |  | → |  | void?
> > v : any/c
> > ci : collect-info?
> > root-path : (or/c path-string? false/c) = #f
> > pkg : (or/c path? 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.

> If pkg is not #f, then deserialized information is recorded as being from a document in the named package.

> Changed in version 1.52 of package scribble-lib: Added the pkg argument.

> > 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] |
> > > |  | [helper-file-prefix helper-file-prefix] |
> > > |  | [keep-existing-helper-files? keep-existing-helper-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
> > helper-file-prefix : (or/c path-string? #f) = #f
> > keep-existing-helper-files? : any/c = #f
> > | 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 helper-file-prefix argument supplies a prefix that is used for any copied or generated files used by the main destination file. This prefix is not used for files listed in extra-files. If keep-existing-helper-files? is true, then any existing file that would otherwise be overwritten with a helper file is instead preserved, and the helper file is written to a different name, unless its content would be exactly the same as the existing file.

> 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.
> Changed in version 1.40: Added the --keep-existing-helper-files? initialization argument and fixed --helper-file-prefix to work correctly for HTML output.

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

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

> > method (send a-render traverse-part p fp) → (and/c hash? immutable?)
> > p : part?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-flow bs fp) → (and/c hash? immutable?)
> > bs : (listof block?)
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-block b fp) → (and/c hash? immutable?)
> > b : block?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-nested-flow nf fp)
> > → (and/c hash? immutable?)
> > nf : nested-flow?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-table t fp) → (and/c hash? immutable?)
> > t : table?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-itemization i fp)
> > → (and/c hash? immutable?)
> > i : itemization?
> > fp : (and/c hash? immutable?)

> > > method
> > > (send a-render traverse-compound-paragraph |  | cp |
> > > |  | fp) |
> > → (and/c hash? immutable?)
> > cp : compound-paragraph?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-paragraph p fp)
> > → (and/c hash? immutable?)
> > p : paragraph?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-content c fp) → (and/c hash? immutable?)
> > c : content?
> > fp : (and/c hash? immutable?)

> > > method
> > > (send a-render traverse-target-element |  | e |
> > > |  | fp) |
> > → (and/c hash? immutable?)
> > e : target-element?
> > fp : (and/c hash? immutable?)

> > method (send a-render traverse-index-element e fp)
> > → (and/c hash? immutable?)
> > e : index-element?
> > fp : (and/c hash? immutable?)

> These methods implement the traverse pass of document rendering. Except for the entry point traverse as described by as described at traverse in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.

> A renderer for a specific format is relatively unlikely to override any of these methods. Each method accepts the information accumulated so far and returns augmented information as a result.

> > method (send a-render collect parts dests fp [demand]) → collect-info?
> > parts : (listof part?)
> > dests : (listof path-string?)
> > fp : (and/c hash? immutable?)
> > | demand |  | : |  | (tag? collect-info? . -> . any/c)
> > |  |  | = |  | (lambda (tag ci) #f)

> > method (send a-render start-collect parts dests ci) → void?
> > parts : (listof part?)
> > dests : (listof path-string?)
> > ci : collect-info?

> > > method
> > > (send a-render collect-part |  | p |
> > > |  | parent |
> > > |  | ci |
> > > |  | number |
> > > |  | init-sub-number |
> > > |  | init-sub-numberers) |
> > | → |  |
> > part-number-item? |  | numberer?
> > p : part?
> > parent : (or/c #f part?)
> > ci : collect-info?
> > number : (listof part-number-item?)
> > init-sub-number : part-number-item?
> > init-sub-numberers : (listof numberer?)

> > > method
> > > (send a-render collect-part-tags |  | p |  |  |  |
> > > |  | ci |  |  |  |
> > > |  | number) |  | → |  | void?
> > p : part?
> > ci : collect-info?
> > number : (listof part-number-item?)

> > method (send a-render collect-flow bs ci) → void?
> > bs : (listof block?)
> > ci : collect-info?

> > method (send a-render collect-block b ci) → void?
> > b : block?
> > ci : collect-info?

> > method (send a-render collect-nested-flow nf ci) → void?
> > nf : nested-flow?
> > ci : collect-info?

> > method (send a-render collect-table t ci) → void?
> > t : table?
> > ci : collect-info?

> > method (send a-render collect-itemization i ci) → void?
> > i : itemization?
> > ci : collect-info?

> > > method
> > > (send a-render collect-compound-paragraph |  | cp |  |  |  |
> > > |  | ci) |  | → |  | void?
> > cp : compound-paragraph?
> > ci : collect-info?

> > method (send a-render collect-paragraph p ci) → void?
> > p : paragraph?
> > ci : collect-info?

> > method (send a-render collect-content c ci) → void?
> > c : content?
> > ci : collect-info?

> > method (send a-render collect-target-element e ci) → void?
> > e : target-element?
> > ci : collect-info?

> > method (send a-render collect-index-element e ci) → void?
> > e : index-element?
> > ci : collect-info?

> These methods implement the collect pass of document rendering. Except for the entry point collect as described at collect in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.

> A renderer for a specific format is most likely to override collect-part-tags, collect-target-element, and perhaps start-collect to set up and record cross-reference information in a way that is suitable for the target format.

> > method (send a-render resolve parts dests ci) → resolve-info?
> > parts : (listof part?)
> > dests : (listof path-string?)
> > ci : collect-info?

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

> > method (send a-render resolve-part p ri) → void?
> > p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-flow |  | bs |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > bs : (listof block?)
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-block |  | b |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > b : block?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-nested-flow |  | nf |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > nf : nested-flow?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-table |  | t |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > t : table?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-itemization |  | i |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > i : itemization?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-compound-paragraph |  | cp |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > cp : compound-paragraph?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-paragraph |  | p |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > p : paragraph?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render resolve-content |  | c |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | void?
> > c : content?
> > enclosing-p : part?
> > ri : resolve-info?

> These methods implement the resolve pass of document rendering. Except for the entry point resolve as described at resolve in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.

> A renderer for a specific format is unlikely to override any of these methods. Each method for a document fragment within a part receives the enclosing part as an argument, as well as resolve information as ri to update.

> > method (send a-render render parts dests ri) → list?
> > parts : (listof part?)
> > dests : (listof (or/c path-string? #f))
> > ri : resolve-info?

> > method (send a-render render-one part ri dest) → any/c
> > part : part?
> > ri : resolve-info?
> > dest : (or/c path-string? #f)

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

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

> > > method
> > > (send a-render render-flow |  | bs |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri |  |  |  |
> > > |  | first-in-part-or-item?) |  | → |  | any/c
> > bs : (listof block?)
> > enclosing-p : part?
> > ri : resolve-info?
> > first-in-part-or-item? : boolean?

> > > method
> > > (send a-render render-block |  | b |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri |  |  |  |
> > > |  | first-in-part-or-item?) |  | → |  | any/c
> > b : block?
> > enclosing-p : part?
> > ri : resolve-info?
> > first-in-part-or-item? : boolean?

> > > method
> > > (send a-render render-nested-flow |  | nf |
> > > |  | enclosing-p |
> > > |  | ri |
> > > |  | first-in-part-or-item?) |
> > → any/c
> > nf : nested-flow?
> > enclosing-p : part?
> > ri : resolve-info?
> > first-in-part-or-item? : boolean?

> > > method
> > > (send a-render render-table |  | t |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri |  |  |  |
> > > |  | first-in-part-or-item?) |  | → |  | any/c
> > t : table?
> > enclosing-p : part?
> > ri : resolve-info?
> > first-in-part-or-item? : boolean?

> > > method
> > > (send a-render render-auxiliary-table |  | t |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | any/c
> > t : table?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render render-itemization |  | i |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | any/c
> > i : itemization?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render render-compound-paragraph |
> > > |  | cp |
> > > |  | enclosing-p |
> > > |  | ri |
> > > |  | first-in-part-or-item?) |
> > → any/c
> > cp : compound-paragraph?
> > enclosing-p : part?
> > ri : resolve-info?
> > first-in-part-or-item? : boolean?

> > > method
> > > (send a-render render-intrapara-block |
> > > |  | p |
> > > |  | enclosing-p |
> > > |  | ri |
> > > |  | first-in-compound-paragraph? |
> > > |  | last-in-compound-paragraph? |
> > > |  | first-in-part-or-item?) |
> > → any/c
> > p : paragraph?
> > enclosing-p : part?
> > ri : resolve-info?
> > first-in-compound-paragraph? : boolean?
> > last-in-compound-paragraph? : boolean?
> > first-in-part-or-item? : boolean?

> > > method
> > > (send a-render render-paragraph |  | p |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | any/c
> > p : paragraph?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render render-content |  | c |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | any/c
> > c : content?
> > enclosing-p : part?
> > ri : resolve-info?

> > > method
> > > (send a-render render-other |  | c |  |  |  |
> > > |  | enclosing-p |  |  |  |
> > > |  | ri) |  | → |  | any/c
> > c : (and/c content? (not/c element?) (not/c convertible?))
> > enclosing-p : part?
> > ri : resolve-info?

> These methods implement the render pass of document rendering. Except for the entry point render as described at render in render<%>, these methods generally would not be called to render a document, but instead provide natural points to interpose on the default implementation.

> A renderer for a specific format is likely to override most or all of these methods. The result of each method can be anything, and the default implementations of the methods propagate results and collect them into a list as needed. The value of current-output-port is set by render for each immediate part before calling render-one, so methods might individually print to render, or they might return values that are used both other methods to print. The interposition points for this pass are somewhat different than for other passes:

> - render-one is called by the render method on each immediate part in the list for its first argument.

> - render-auxiliary-table is called by the default render-block on any table that has the 'aux style property.

> - render-intrapara-block is called on blocks within a compound-paragraph, where the default implementation just chains to render% render-block.

> - render-other is called by the default implementation of render-content for any content that does not satisfy element? or convertible?.

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

> parameter (current-markdown-link-sections) → boolean?
> (current-markdown-link-sections enabled?) → void?
> enabled? : any/c

Determines whether section links within an output document are rendered as a section link. The default is #f.

Added in version 1.31 of package scribble-lib.

##### 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. The result of get-doc-search-url is intended for use as url.

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

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

Like render-mixin, but generates PDF output via latex, dvips, and pstopdf.

Added in version 1.4 of package scribble-lib.

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

Like render-mixin, but generates PDF output via xelatex.

Added in version 1.19 of package scribble-lib.

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

Like render-mixin, but generates PDF output via lualatex.

Added in version 1.45 of package scribble-lib.

##### 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 contents ← prev up next →