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

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