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 #: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?)
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.
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]]) → (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.
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.
| ||
|