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?)
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 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.
|
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
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.
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 |
| ||
|
6.4.4 Markdown Renderer
| (require scribble/markdown-render) | |
| package: scribble-lib | |
| ||
|
```racket |
6.4.5 HTML Renderer
| (require scribble/html-render) | package: scribble-lib |
| ||
|
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.
| ||
|
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 |
| ||
|
6.4.7 PDF Renderer
| (require scribble/pdf-render) | package: scribble-lib |
| ||
|
6.4.8 Contract (Blue boxes) Renderer
| (require scribble/contract-render) | |
| package: scribble-lib | |
| ||
|
method
(send an-override-render-mixin-multi render srcs dests ri) → void? srcs : (listof part?) dests : (listof path?) ri : render-info? 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.
| ||
|