6.8 Cross-Reference Utilities

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

▼ | 6 | Low-Level Scribble API

6.1 | Scribble Layers
6.2 | @ Reader Internals
6.3 | Structures And Processing
6.4 | Renderers
6.5 | Decoding Text
6.6 | Document Language
6.7 | Document Reader
6.8 | Cross-Reference Utilities
6.9 | Tag Utilities
6.10 | Blue Boxes Utilities
6.11 | Extending and Configuring Scribble Output

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
data+ root?
make-data+ root
data+ root+ doc-id?
make-data+ root+ doc-id

top contents ← prev up next →

#### 6.8`` Cross-Reference Utilities🔗ℹ

(require scribble/xref) | package: scribble-lib

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

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

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

> > procedure
> > (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

Creates a cross-reference record given a list of functions, sources.

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.

> > procedure
> > (xref-binding->definition-tag |  | xref |
> > |  | binding |
> > |  | mode |
> > | [ | #:space space |
> > |  | #:suffix suffix]) |
> → (or/c tag? false/c)
> xref : xref?
> | binding |  | : |  |
> (or/c identifier?
> (list/c (or/c module-path?
> module-path-index?)
> symbol?)
> (list/c 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))
> (list/c (or/c module-path?
> 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? #f)
> space : #f = (or/c symbol? #f)
> suffix : space = any/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.

The space argument indicates a binding space (in the sense of for-space) to search. The suffix argument specifies an additional suffix for the tag, which may be used to distinguish bindings for different spaces or components of a binding.

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.

Changed in version 1.55 of package scribble-lib: Added the #:space and #:suffix arguments.

> > procedure
> > (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%)

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.

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.

> procedure (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.

> > procedure
> > (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)

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.

> procedure (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.

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

Converts indexing information xref into a list of entry structures.

> > struct
> > (struct |  | entry (words content tag desc)
> #:extra-constructor-name make-entry)
> 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.

> procedure (data+root? v) → boolean?
> v : any/c
> procedure (make-data+root data root) → data+root?
> data : any/c
> root : (or/c #f path-string?)

A value constructed by make-data+root can be returned by a source procedure for load-xref to specify a path used for deserialization.

> procedure (data+root+doc-id? v) → boolean?
> v : any/c
> procedure (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?

Extends make-data+root+doc-id to support an document-identifying string (see load-xref).

Added in version 1.1 of package scribble-lib.

top contents ← prev up next →