#lang scribble/doc
@(require scribble/manual "utils.rkt"
          (for-label scribble/xref
                     scribble/base-render
                     scribble/html-render
                     setup/xref))

@title[#:tag "xref"]{Cross-Reference Utilities}

@defmodule[scribble/xref]{The @racketmodname[scribble/xref] library
provides utilities for querying cross-reference information that was
collected from a document build.}

@; ------------------------------------------------------------------------

@defproc[(xref? [v any/c]) boolean?]{

Returns @racket[#t] if @racket[v] is a cross-reference record created
by @racket[load-xref], @racket[#f] otherwise.}


@defproc[(load-xref [sources (listof (-> (or/c any/c (-> list?))))]
                    [#:demand-source demand-source 
                                     (tag? -> (or/c (-> any/c) #f)) 
                                     (lambda (_tag) #f)]
                    [#:render% using-render% (implementation?/c render<%>)
                               (render-mixin render%)]
                    [#:root root-path (or/c path-string? false/c) #f]
                    [#:doc-id doc-id-str (or/c path-string? false/c) #f])
         xref?]{

Creates a cross-reference record given a list of functions,
@racket[sources]. 

Let @racket[_source] be a function in @racket[sources]. The
@racket[_source] function normally returns serialized information,
@racket[_info], which was formerly obtained from @xmethod[render<%>
serialize-info]. The result of @racket[_source] can optionally be
another function, which is in turn responsible for returning a list of
@racket[_info]s. Finally, each @racket[_info] can be either serialized
information, a @racket[#f] to be ignored, or a value produced by
@racket[make-data+root] or @racket[make-data+root+doc-id], from which
@racket[_data] part is used as serialized information, the
@racket[_root] part overrides @racket[root-path] for deserialization,
and the @racket[_doc-id] part (if any) overrides
@racket[doc-id-string] to identify the source document.

The @racket[demand-source] function can effectively add a new source
to @racket[sources] in response to a search for information on the
given tag. The @racket[demand-source] function returns @racket[#f]
to indicate that no new sources satisfy the given tag.

Since the format of serialized information is specific to a rendering
class, the optional @racket[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 @racket[root-path] is not @racket[#f], then file paths that are
serialized as relative to an instantiation-supplied @racket[root-path]
are deserialized as relative instead to the given @racket[root-path],
but a @racket[make-data+root] result for any @racket[_info] supplies
an alternate path for deserialization of the @racket[_info]'s
@racket[_data].

If @racket[doc-id-str] is not @racket[#f], it identifies each
cross-reference entry as originating from @racket[doc-id-str]. This
identification is used when a rendering link to the cross-reference
entry as an external query; see the @racket[set-external-tag-path]
method of @racket[render-mixin].

Use @racket[load-collections-xref] from @racketmodname[setup/xref] to
get all cross-reference information for installed documentation.

@history[#:changed "1.1" @elem{Added the @racket[#:doc-id] argument.}]}


@defproc[(xref-binding->definition-tag [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)])
         (or/c tag? false/c)]{

Locates a tag in @racket[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 @racket[mode] argument specifies the relevant phase level for the
binding. The @racket[binding] is specified in one of four ways:

@itemize[

 @item{If @racket[binding] is an identifier, then
       @racket[identifier-binding] is used with @racket[mode] to
       determine the binding.}

 @item{If @racket[binding] is a two-element list, then the first
       element provides the exporting module and the second the
       exported name. The @racket[mode] argument is effectively
       ignored.}

 @item{If @racket[binding] is a seven-element list, then it corresponds
       to a result from @racket[identifier-binding] using
       @racket[mode].}

 @item{If @racket[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 @racket[xref], a tag is returned,
which might be used with @racket[xref-tag->path+anchor] or embedded in
a document rendered via @racket[xref-render]. If no definition point
is found in @racket[xref], the result is @racket[#f].}


@defproc[(xref-tag->path+anchor [xref xref?]
                                [tag tag?]
                                [#:external-root-url root-url (or/c string? #f) #f]
                                [#:render% using-render% (implementation?/c render<%>)
                                           (render-mixin render%)])
         (values (or/c false/c path?)
                 (or/c false/c string?))]{

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

If @racket[root-url] is provided, then references to documentation in
the main installation are redirected to the given URL.

The optional @racket[using-render%] argument is as for
@racket[load-xref].}


@defproc[(xref-tag->index-entry [xref xref?] [tag tag?])
         (or/c false/c entry?)]{

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


@defproc[(xref-render [xref xref?]
                      [doc part?]
                      [dest (or/c path-string? false/c)]
                      [#:render% using-render% (implemenation?/c render<%>)
                                 (render-mixin render%)]
                      [#:refer-to-existing-files? use-existing? any/c (not dest)])
         (or/c void? any/c)]{

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

If @racket[dest] is @racket[#f], no file is written, and the result is
an X-expression for the rendered page. Otherwise, the file
@racket[dest] is written and the result is @|void-const|.

The optional @racket[using-render%] argument is as for
@racket[load-xref]. It determines the kind of output that is
generated.

If @racket[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 @racket[dest].}


@defproc[(xref-transfer-info [renderer (is-a?/c render<%>)]
                             [ci collect-info?]
                             [xref xref?])
         void?]{

Transfers cross-reference information to @racket[ci], which is the
initially collected information from @racket[renderer].}


@defproc[(xref-index [xref xref?]) (listof entry?)]{

Converts indexing information @racket[xref] into a list of
@racket[entry] structures.}


@defstruct[entry ([words (and/c (listof string?) cons?)]
                  [content list?]
                  [tag tag?]
                  [desc any/c])]{

Represents a single entry in a Scribble document index.

The @racket[words] list corresponds to
@racket[index-element-plain-seq]. The @racket[content] list
corresponds to @racket[index-element-entry-seq]. The @racket[desc]
value corresponds to @racket[index-element-desc]. The @racket[tag] is
the destination for the index link into the main document.}


@deftogether[(
@defproc[(data+root? [v any/c]) boolean?]
@defproc[(make-data+root [data any/c] [root (or/c #f path-string?)]) data+root?]
)]{

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

@deftogether[(
@defproc[(data+root+doc-id? [v any/c]) boolean?]
@defproc[(make-data+root+doc-id [data any/c] [root (or/c #f path-string?)] [doc-id string?]) data+root+doc-id?]
)]{

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

@history[#:added "1.1"]}