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?)

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])   →   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]         [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?.

parameter (current-markdown-link-sections) → boolean?

(current-markdown-link-sections enabled?) → void?

enabled? : any/c

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.

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.

parameter (extra-character-conversions) → (-> char? (or/c string? #f))

(extra-character-conversions convs) → void?

convs : (-> char? (or/c string? #f))

Added in version 1.4 of package scribble-lib.

Added in version 1.19 of package scribble-lib.

Added in version 1.45 of package scribble-lib.

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.