[racket] Additional cached index for documentation?

From: Greg Hendershott (greghendershott at gmail.com)
Date: Mon Mar 17 22:26:25 EDT 2014

Let's say that, given a symbol that may be a documented item -- e.g.
`case` -- I want a list of symbols representing the module(s) for
which it is documented.

I might want this so that I can build hyperlink(s) to the
documentation for the item. Or maybe I'm doing autocomplete and just
want to see if it's documented, at all.

How I currently do this, based on IIRC looking at racket/help source:

(define xref (load-collections-xref))

(define sym-mods
  ;; (symbol? . -> . (listof symbol?))
  (let ([cache #f])
    (lambda (sym)
      (unless cache
        (set! cache (make-hasheq))
        (prn0 "Building Racket documentation cache...")
        (for ([x (in-list (xref-index xref))])
          (match x
            [(entry words content tag (exported-index-desc name from-libs))
             (hash-set! cache name (append (hash-ref cache name '())
                                           (filter symbol? from-libs)))]
            [_ (void)]))
        (prn0 "...~a items" (hash-count cache)))
      (hash-ref cache sym #f))))

And e.g. for `case` this would return '(rnrs/base-6 racket/base racket
mzscheme lang/htdp-advanced plai/mutator lazy r5rs plai/gc2/mutator).

This works but is quite slow building the cache the first time.

I think at least a few of us do this sort of thing. I think DrRacket
does this, racket/help does this, and some third-party tools do it (or
would do it if easier to do). So it would be great to save this cache
on-disk, and a simple function to access it.

I started off thinking oh I should make a package for this. But now
I'm thinking it should be a pull-request.  Why?  Because it seems like
`raco setup` would be the entity that knows when to rebuild the cache.
Perhaps when it rebuilds the collections xref?  I don't clearly
understand the whole doc xref process. Maybe there's a good reason
this doesn't already exist, or it isn't so straightforward. So I
wanted to see if folks who do know it well, have any suggestions or
ideas.

Posted on the users mailing list.