6.8 Cross-Reference Utilities
|(require scribble/xref)||package: scribble-lib|
(load-xref sources [ #:demand-source-for-use demand-source-for-use #:demand-source demand-source #:render% using-render% #:root root-path #:doc-id doc-id-str]) → xref? sources : (listof (-> (or/c any/c (-> list?))))
demand-source-for-use : (tag? symbol? -> (or/c (-> any/c) #f)) = (lambda (tag use-id) (demand-source tag))
demand-source : (tag? -> (or/c (-> any/c) #f)) = (lambda (tag) #f)
using-render% : (implementation?/c render<%>) = (render-mixin render%) root-path : (or/c path-string? false/c) = #f doc-id-str : (or/c path-string? false/c) = #f
Let source be a function in sources. The source function normally returns serialized information, info, which was formerly obtained from serialize-info in render<%>. The result of source can optionally be another function, which is in turn responsible for returning a list of infos. Finally, each info can be either serialized information, a #f to be ignored, or a value produced by make-data+root or make-data+root+doc-id, from which data part is used as serialized information, the root part overrides root-path for deserialization, and the doc-id part (if any) overrides doc-id-string to identify the source document.
The demand-source-for-use function can effectively add a new source to sources in response to a search for information on the given tag in the given rendering, where use-id is unique to a particular rendering request, a particular transfer (in the sense of xref-transfer-info), or all direct queries of the cross-reference information (such as through xref-binding->definition-tag). The demand-source-for-use function should return #f to indicate that no new sources satisfy the given tag for the given use-id.
The default demand-source-for-use function uses demand-source, which is provided only for backward compatibility. Since the demand-source function accepts only a tag, it is suitable only when the result of load-xref will only have a single use context, such as a single rendering.
Since the format of serialized information is specific to a rendering class, the optional using-render% argument accepts the relevant class. It defaults to HTML rendering, partly because HTML-format information is usable by other formats (including Latex/PDF and text).
If root-path is not #f, then file paths that are serialized as relative to an instantiation-supplied root-path are deserialized as relative instead to the given root-path, but a make-data+root result for any info supplies an alternate path for deserialization of the info’s data.
If doc-id-str is not #f, it identifies each cross-reference entry as originating from doc-id-str. This identification is used when a rendering link to the cross-reference entry as an external query; see the set-external-tag-path method of render-mixin.
Use load-collections-xref from setup/xref to get all cross-reference information for installed documentation.
Changed in version 1.1 of package scribble-lib: Added the #:doc-id argument.
Changed in version 1.34: Added the #:demand-source-for-use argument.
(xref-binding->definition-tag xref binding mode) → (or/c tag? false/c) xref : xref?
binding : mode : (or/c exact-integer? false/c)
The mode argument specifies the relevant phase level for the binding. The binding is specified in one of four ways:
If binding is an identifier, then identifier-binding is used with mode to determine the binding.
If binding is a two-element list, then the first element provides the exporting module and the second the exported name. The mode argument is effectively ignored.
If binding is a seven-element list, then it corresponds to a result from identifier-binding using mode.
If binding is a five-element list, then the first element is as for the two-element-list case, and the remain elements are as in the last four elements of the seven-element case.
If a documentation point exists in xref, a tag is returned, which might be used with xref-tag->path+anchor or embedded in a document rendered via xref-render. If no definition point is found in xref, the result is #f.
(xref-tag->path+anchor xref tag [ #:external-root-url root-url #:render% using-render%])
(or/c false/c path?) (or/c false/c string?) xref : xref? tag : tag? root-url : (or/c string? #f) = #f
using-render% : (implementation?/c render<%>) = (render-mixin render%)
If root-url is provided, then references to documentation in the main installation are redirected to the given URL.
The optional using-render% argument is as for load-xref.
(xref-render xref doc dest [ #:render% using-render% #:refer-to-existing-files? use-existing?]) → (or/c void? any/c) xref : xref? doc : part? dest : (or/c path-string? false/c)
using-render% : (implemenation?/c render<%>) = (render-mixin render%) use-existing? : any/c = (not dest)
If dest is #f, no file is written, and the result is an X-expression for the rendered page. Otherwise, the file dest is written and the result is #<void>.
The optional using-render% argument is as for load-xref. It determines the kind of output that is generated.
If use-existing? is true, then files referenced during rendering (such as image files) are referenced from their existing locations, instead of copying to the directory of dest.
(xref-transfer-info renderer ci xref) → void?
renderer : (is-a?/c render<%>) ci : collect-info? xref : xref?
(xref-index xref) → (listof entry?)
xref : xref?
(struct entry (words content tag desc) #:extra-constructor-name make-entry) words : (and/c (listof string?) cons?) content : list? tag : tag? desc : any/c
The words list corresponds to index-element-plain-seq. The content list corresponds to index-element-entry-seq. The desc value corresponds to index-element-desc. The tag is the destination for the index link into the main document.
(data+root? v) → boolean?
v : any/c
(make-data+root data root) → data+root?
data : any/c root : (or/c #f path-string?)
(data+root+doc-id? v) → boolean?
v : any/c
(make-data+root+doc-id data root doc-id) → data+root+doc-id?
data : any/c root : (or/c #f path-string?) doc-id : string?
Added in version 1.1 of package scribble-lib.