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

6.8 Cross-Reference Utilities

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

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.