commit 3d7ded8a33fe74de912bbf561da2823b5bfe78c2
parent 340c60ef541163c81f45fd74426fae2381986e36
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 24 May 2020 11:06:23 -0600
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.
Diffstat:
3 files changed, 32 insertions(+), 7 deletions(-)
diff --git 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
@@ -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
@@ -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])
