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
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 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
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.
Represents a renderer.
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.
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.
Performs the
collect pass. See
render for
information on the
dests argument. The
fp argument
is a result from the
traverse method.
Performs the
resolve pass. See
render for
information on the
dests argument. The
ci argument
is a result from the
collect method.
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.
Serializes the collected info in ri.
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.
Returns a list of tags that were defined within the documents
represented by ci.
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).
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.
7.4.3 Text Renderer
Specializes a
render% class for generating plain text.
7.4.4 HTML Renderer
Specializes a
render% class for generating HTML output.
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.
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.
Further specializes a rendering class produced by
render-mixin for generating multiple HTML
files.
7.4.5 Latex Renderer
Specializes a
render% class for generating Latex input.
7.4.6 PDF Renderer