▼ |  | Scribble: PLT Documentation Tool

1 | How to Scribble Documentation
2 | Scribble Layers
3 | @-Reader
4 | Structures And Processing
5 | Renderer
6 | Decoding Text
7 | Document Language
8 | Document Reader
9 | Basic Document Forms
10 | Scheme
11 | Manual Forms
12 | Evaluation and Examples
13 | BNF Grammars
14 | Cross-Reference Utilities
15 | Text Preprocessor
| Index

On this page:

xref?
load-xref
xref-binding->definition-tag
xref-tag->path+ anchor
xref-tag->index-entry
xref-render
xref-transfer-info
xref-index
entry

Version: 4.1.4
top← prev up next →

### 14`` Cross-Reference Utilities

(require scribble/xref)

The scribble/xref library provides utilities for querying cross-reference information that was collected from a document build.

(xref? v) → boolean?
v : any/c

Returns #t if v is a cross-reference record created by load-xref, #f otherwise.

(load-xref |  | sources |  |  |  |
| [ | #:render% using-render% |  |  |  |
|  | #:root root-path]) |  | → |  | xref?

sources : (listof (-> any/c))
using-render% : (subclass?/c render%) = (render-mixin render%)
root-path : (or/c path-string? false/c) = #f

Creates a cross-reference record given a list of functions that each produce a serialized information obtained from serialize-info in render%. If a sources element produces #f, its result is ignored.

Since the format of serialized information is specific to a rendering class, the optional using-render% argument accepts the relevant class. It default to HTML rendering.

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.

Use load-collections-xref from setup/xref to get all cross-reference information for installed documentation.

(xref-binding->definition-tag |  | xref |  |  |  |
|  | binding |  |  |  |
|  | mode) |  | → |  | (or/c tag? false/c)

xref : xref?

binding

:

(or/c identifier?
(list/c (or/c module-path?
module-path-index?)
symbol?)
(listof module-path-index?
symbol?
module-path-index?
symbol?
(one-of/c 0 1)
(or/c exact-integer? false/c)
(or/c exact-integer? false/c)))

mode : (or/c exact-integer? false/c)

Locates a tag in xref that documents a module export. The binding is specified in one of several ways, as described below; all possibilities encode an exporting module and a symbolic name. The name must be exported from the specified module. Documentation is found either for the specified module or, if the exported name is re-exported from other other module, for the other module (transitively).

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 |
| [ | #:render% using-render%]) |

→

(or/c false/c path?)
(or/c false/c string?)

xref : xref?
tag : tag?
using-render% : (subclass?/c render%) = (render-mixin render%)

Returns a path and anchor string designated by the key tag according the cross-reference xref. The first result is #f if no mapping is found for the given tag. The second result is #f if the first result is #f, and it can also be #f if the tag refers to a page rather than a specific point in a page.

The optional using-render% argument is as for load-xref.

(xref-tag->index-entry xref tag) → (or/c false/c entry?)
xref : xref?
tag : tag?

Extract an entry structure that provides addition information about the definition (of any) referenced by tag. This function can be composed with xref-binding->definition-tag to obtain information about a binding, such as the library that exports the binding and its original name.

(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% : (subclass?/c render%) = (render-mixin render%)
use-existing? : any/c = (not dest)

Renders doc using the cross-reference info in xref to the destination dest. For example, doc might be a generated document of search results using link tags described in xref.

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?

Transfers cross-reference information to ci, which is the initially collected information from renderer.

(xref-index xref) → (listof entry?)
xref : xref?

Converts indexing information xref into a list of entry structures.

(struct entry (words content tag desc))
words : (and/c (listof string?) cons?)
content : list?
tag : tag?
desc : any/c

Represents a single entry in a Scribble document index.

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.

top← prev up next →