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 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
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.
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 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.
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.
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).
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.
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.
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.
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.
7.4.3 Text Renderer
Specializes a
render<%> class for generating plain text.
7.4.4 Markdown Renderer
Specializes a
render<%> class for generating Markdown text.
so that they are lexed and
formatted as Racket code.
7.4.5 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.
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
Specializes a
render<%> class for generating Latex input.
7.4.7 PDF Renderer
7.4.8 Contract (Blue boxes) Renderer
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.
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.
Just like
render, except
that it saves the file
"blueboxes.rktd" in
the same directory where each
dests element resides.