diff --git a/scribble-doc/scribblings/scribble/xref.scrbl b/scribble-doc/scribblings/scribble/xref.scrbl index 1ae68068..f208ed2c 100644 --- a/scribble-doc/scribblings/scribble/xref.scrbl +++ b/scribble-doc/scribblings/scribble/xref.scrbl @@ -20,6 +20,10 @@ by @racket[load-xref], @racket[#f] otherwise.} @defproc[(load-xref [sources (listof (-> (or/c any/c (-> list?))))] + [#:demand-source-for-use + demand-source-for-use + (tag? symbol? -> (or/c (-> any/c) #f)) + (lambda (_tag _use-id) (demand-source _tag))] [#:demand-source demand-source (tag? -> (or/c (-> any/c) #f)) (lambda (_tag) #f)] @@ -45,10 +49,22 @@ information, a @racket[#f] to be ignored, or a value produced by 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. +The @racket[demand-source-for-use] function can effectively add a new +source to @racket[sources] in response to a search for information on +the given tag in the given rendering, where @racket[_use-id] is unique +to a particular rendering request, a particular transfer (in the sense +of @racket[xref-transfer-info]), or all direct queries of the +cross-reference information (such as through +@racket[xref-binding->definition-tag]). The +@racket[demand-source-for-use] function should return @racket[#f] to +indicate that no new sources satisfy the given tag for the given +@racket[_use-id]. + +The default @racket[demand-source-for-use] function uses +@racket[demand-source], which is provided only for backward +compatibility. Since the @racket[demand-source] function accepts only +a tag, it is suitable only when the result of @racket[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 @racket[using-render%] argument accepts the @@ -72,7 +88,8 @@ 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.}]} +@history[#:changed "1.1" @elem{Added the @racket[#:doc-id] argument.} + #:changed "1.34" @elem{Added the @racket[#:demand-source-for-use] argument.}]} @defproc[(xref-binding->definition-tag [xref xref?] diff --git a/scribble-lib/info.rkt b/scribble-lib/info.rkt index 32eeca65..d72abc33 100644 --- a/scribble-lib/info.rkt +++ b/scribble-lib/info.rkt @@ -23,4 +23,4 @@ (define pkg-authors '(mflatt eli)) -(define version "1.33") +(define version "1.34") diff --git a/scribble-lib/scribble/xref.rkt b/scribble-lib/scribble/xref.rkt index 333333d9..ae24ab56 100644 --- a/scribble-lib/scribble/xref.rkt +++ b/scribble-lib/scribble/xref.rkt @@ -43,6 +43,8 @@ (define (load-xref sources #:demand-source [demand-source (lambda (key) #f)] + #:demand-source-for-use [demand-source-for-use + (lambda (key use-id) (demand-source key))] #:render% [render% (html:render-mixin render%)] #:root [root-path #f] #:doc-id [doc-id-str #f]) @@ -61,9 +63,15 @@ (send renderer deserialize-info data ci #:root root #:doc-id doc-id))))))] + [use-ids (make-weak-hasheq)] [ci (send renderer collect null null fp (lambda (key ci) - (define src (demand-source key)) + (define use-obj (collect-info-ext-ht ci)) + (define use-id (or (hash-ref use-ids use-obj #f) + (let ([s (gensym 'render)]) + (hash-set! use-ids use-obj s) + s))) + (define src (demand-source-for-use key use-id)) (and src (load-source src ci))))]) (for ([src sources])