extend load-xref to support multi-use on-demand information

The result of `load-xref` with an on-demand function only made sense
for a single use context, such as a single rendering request. Add an
on-demand callback that can work right for multiple uses.

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
+The @racket[demand-source-for-use] function can effectively add a new
-to @racket[sources] in response to a search for information on the
+source to @racket[sources] in response to a search for information on
-given tag. The @racket[demand-source] function returns @racket[#f]
+the given tag in the given rendering, where @racket[_use-id] is unique
-to indicate that no new sources satisfy the given tag.
+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?]

scribble-lib/info.rkt

@@ -23,4 +23,4 @@
 
 (define pkg-authors '(mflatt eli))
 
-(define version "1.33")
+(define version "1.34")

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])