xref.scrbl (11539B)
1 #lang scribble/doc 2 @(require scribble/manual "utils.rkt" 3 (for-label scribble/xref 4 scribble/base-render 5 scribble/html-render 6 setup/xref)) 7 8 @title[#:tag "xref"]{Cross-Reference Utilities} 9 10 @defmodule[scribble/xref]{The @racketmodname[scribble/xref] library 11 provides utilities for querying cross-reference information that was 12 collected from a document build.} 13 14 @; ------------------------------------------------------------------------ 15 16 @defproc[(xref? [v any/c]) boolean?]{ 17 18 Returns @racket[#t] if @racket[v] is a cross-reference record created 19 by @racket[load-xref], @racket[#f] otherwise.} 20 21 22 @defproc[(load-xref [sources (listof (-> (or/c any/c (-> list?))))] 23 [#:demand-source-for-use 24 demand-source-for-use 25 (tag? symbol? -> (or/c (-> any/c) #f)) 26 (lambda (_tag _use-id) (demand-source _tag))] 27 [#:demand-source demand-source 28 (tag? -> (or/c (-> any/c) #f)) 29 (lambda (_tag) #f)] 30 [#:render% using-render% (implementation?/c render<%>) 31 (render-mixin render%)] 32 [#:root root-path (or/c path-string? false/c) #f] 33 [#:doc-id doc-id-str (or/c path-string? false/c) #f]) 34 xref?]{ 35 36 Creates a cross-reference record given a list of functions, 37 @racket[sources]. 38 39 Let @racket[_source] be a function in @racket[sources]. The 40 @racket[_source] function normally returns serialized information, 41 @racket[_info], which was formerly obtained from @xmethod[render<%> 42 serialize-info]. The result of @racket[_source] can optionally be 43 another function, which is in turn responsible for returning a list of 44 @racket[_info]s. Finally, each @racket[_info] can be either serialized 45 information, a @racket[#f] to be ignored, or a value produced by 46 @racket[make-data+root] or @racket[make-data+root+doc-id], from which 47 @racket[_data] part is used as serialized information, the 48 @racket[_root] part overrides @racket[root-path] for deserialization, 49 and the @racket[_doc-id] part (if any) overrides 50 @racket[doc-id-string] to identify the source document. 51 52 The @racket[demand-source-for-use] function can effectively add a new 53 source to @racket[sources] in response to a search for information on 54 the given tag in the given rendering, where @racket[_use-id] is unique 55 to a particular rendering request, a particular transfer (in the sense 56 of @racket[xref-transfer-info]), or all direct queries of the 57 cross-reference information (such as through 58 @racket[xref-binding->definition-tag]). The 59 @racket[demand-source-for-use] function should return @racket[#f] to 60 indicate that no new sources satisfy the given tag for the given 61 @racket[_use-id]. 62 63 The default @racket[demand-source-for-use] function uses 64 @racket[demand-source], which is provided only for backward 65 compatibility. Since the @racket[demand-source] function accepts only 66 a tag, it is suitable only when the result of @racket[load-xref] will 67 only have a single use context, such as a single rendering. 68 69 Since the format of serialized information is specific to a rendering 70 class, the optional @racket[using-render%] argument accepts the 71 relevant class. It defaults to HTML rendering, partly because 72 HTML-format information is usable by other formats (including 73 Latex/PDF and text). 74 75 If @racket[root-path] is not @racket[#f], then file paths that are 76 serialized as relative to an instantiation-supplied @racket[root-path] 77 are deserialized as relative instead to the given @racket[root-path], 78 but a @racket[make-data+root] result for any @racket[_info] supplies 79 an alternate path for deserialization of the @racket[_info]'s 80 @racket[_data]. 81 82 If @racket[doc-id-str] is not @racket[#f], it identifies each 83 cross-reference entry as originating from @racket[doc-id-str]. This 84 identification is used when a rendering link to the cross-reference 85 entry as an external query; see the @racket[set-external-tag-path] 86 method of @racket[render-mixin]. 87 88 Use @racket[load-collections-xref] from @racketmodname[setup/xref] to 89 get all cross-reference information for installed documentation. 90 91 @history[#:changed "1.1" @elem{Added the @racket[#:doc-id] argument.} 92 #:changed "1.34" @elem{Added the @racket[#:demand-source-for-use] argument.}]} 93 94 95 @defproc[(xref-binding->definition-tag [xref xref?] 96 [binding (or/c identifier? 97 (list/c (or/c module-path? 98 module-path-index?) 99 symbol?) 100 (list/c module-path-index? 101 symbol? 102 module-path-index? 103 symbol? 104 (one-of/c 0 1) 105 (or/c exact-integer? false/c) 106 (or/c exact-integer? false/c)) 107 (list/c (or/c module-path? 108 module-path-index?) 109 symbol? 110 (one-of/c 0 1) 111 (or/c exact-integer? false/c) 112 (or/c exact-integer? false/c)))] 113 [mode (or/c exact-integer? false/c)]) 114 (or/c tag? false/c)]{ 115 116 Locates a tag in @racket[xref] that documents a module export. The 117 binding is specified in one of several ways, as described below; all 118 possibilities encode an exporting module and a symbolic name. The name 119 must be exported from the specified module. Documentation is found 120 either for the specified module or, if the exported name is 121 re-exported from other other module, for the other module 122 (transitively). 123 124 The @racket[mode] argument specifies the relevant phase level for the 125 binding. The @racket[binding] is specified in one of four ways: 126 127 @itemize[ 128 129 @item{If @racket[binding] is an identifier, then 130 @racket[identifier-binding] is used with @racket[mode] to 131 determine the binding.} 132 133 @item{If @racket[binding] is a two-element list, then the first 134 element provides the exporting module and the second the 135 exported name. The @racket[mode] argument is effectively 136 ignored.} 137 138 @item{If @racket[binding] is a seven-element list, then it corresponds 139 to a result from @racket[identifier-binding] using 140 @racket[mode].} 141 142 @item{If @racket[binding] is a five-element list, then the first 143 element is as for the two-element-list case, and the remain 144 elements are as in the last four elements of the seven-element 145 case.} 146 147 ] 148 149 If a documentation point exists in @racket[xref], a tag is returned, 150 which might be used with @racket[xref-tag->path+anchor] or embedded in 151 a document rendered via @racket[xref-render]. If no definition point 152 is found in @racket[xref], the result is @racket[#f].} 153 154 155 @defproc[(xref-tag->path+anchor [xref xref?] 156 [tag tag?] 157 [#:external-root-url root-url (or/c string? #f) #f] 158 [#:render% using-render% (implementation?/c render<%>) 159 (render-mixin render%)]) 160 (values (or/c false/c path?) 161 (or/c false/c string?))]{ 162 163 Returns a path and anchor string designated by the key @racket[tag] 164 according the cross-reference @racket[xref]. The first result is 165 @racket[#f] if no mapping is found for the given tag. The second 166 result is @racket[#f] if the first result is @racket[#f], and it can 167 also be @racket[#f] if the tag refers to a page rather than a specific 168 point in a page. 169 170 If @racket[root-url] is provided, then references to documentation in 171 the main installation are redirected to the given URL. 172 173 The optional @racket[using-render%] argument is as for 174 @racket[load-xref].} 175 176 177 @defproc[(xref-tag->index-entry [xref xref?] [tag tag?]) 178 (or/c false/c entry?)]{ 179 180 Extract an @racket[entry] structure that provides addition information 181 about the definition (of any) referenced by @racket[tag]. This 182 function can be composed with @racket[xref-binding->definition-tag] to 183 obtain information about a binding, such as the library that exports 184 the binding and its original name.} 185 186 187 @defproc[(xref-render [xref xref?] 188 [doc part?] 189 [dest (or/c path-string? false/c)] 190 [#:render% using-render% (implemenation?/c render<%>) 191 (render-mixin render%)] 192 [#:refer-to-existing-files? use-existing? any/c (not dest)]) 193 (or/c void? any/c)]{ 194 195 Renders @racket[doc] using the cross-reference info in @racket[xref] 196 to the destination @racket[dest]. For example, @racket[doc] might be a 197 generated document of search results using link tags described in 198 @racket[xref]. 199 200 If @racket[dest] is @racket[#f], no file is written, and the result is 201 an X-expression for the rendered page. Otherwise, the file 202 @racket[dest] is written and the result is @|void-const|. 203 204 The optional @racket[using-render%] argument is as for 205 @racket[load-xref]. It determines the kind of output that is 206 generated. 207 208 If @racket[use-existing?] is true, then files referenced during 209 rendering (such as image files) are referenced from their existing 210 locations, instead of copying to the directory of @racket[dest].} 211 212 213 @defproc[(xref-transfer-info [renderer (is-a?/c render<%>)] 214 [ci collect-info?] 215 [xref xref?]) 216 void?]{ 217 218 Transfers cross-reference information to @racket[ci], which is the 219 initially collected information from @racket[renderer].} 220 221 222 @defproc[(xref-index [xref xref?]) (listof entry?)]{ 223 224 Converts indexing information @racket[xref] into a list of 225 @racket[entry] structures.} 226 227 228 @defstruct[entry ([words (and/c (listof string?) cons?)] 229 [content list?] 230 [tag tag?] 231 [desc any/c])]{ 232 233 Represents a single entry in a Scribble document index. 234 235 The @racket[words] list corresponds to 236 @racket[index-element-plain-seq]. The @racket[content] list 237 corresponds to @racket[index-element-entry-seq]. The @racket[desc] 238 value corresponds to @racket[index-element-desc]. The @racket[tag] is 239 the destination for the index link into the main document.} 240 241 242 @deftogether[( 243 @defproc[(data+root? [v any/c]) boolean?] 244 @defproc[(make-data+root [data any/c] [root (or/c #f path-string?)]) data+root?] 245 )]{ 246 247 A value constructed by @racket[make-data+root] can be returned by a 248 source procedure for @racket[load-xref] to specify a path used for 249 deserialization.} 250 251 @deftogether[( 252 @defproc[(data+root+doc-id? [v any/c]) boolean?] 253 @defproc[(make-data+root+doc-id [data any/c] [root (or/c #f path-string?)] [doc-id string?]) data+root+doc-id?] 254 )]{ 255 256 Extends @racket[make-data+root+doc-id] to support an 257 document-identifying string (see @racket[load-xref]). 258 259 @history[#:added "1.1"]}