[racket] getting symbol documentation URL quickly within Emacs

From: Matthew Flatt (mflatt at cs.utah.edu)
Date: Sun Jun 26 16:28:54 EDT 2011

At Sat, 25 Jun 2011 04:13:32 -0400, Neil Van Dyke wrote:
> If I'm in Emacs, and I have a symbol for some Racket standard library 
> procedure or syntax, and I want to get the URL (or open the URL in 
> browser) for the documentation for that symbol... what is a good and 
> fast way to do that?
> Ideas I've considered so far:
> [...]
> 1. Use "racket/help".  I don't want to do this, since I'd really 

It would be nice to make `help' faster. Most of the time is loading the
cross-reference files for all installed documents. Since each document
has its own cross-reference file, it might be a lot faster to have some
lighter-weight index from module+name pairs to cross-reference files,
so that only one cross-reference file needs to be loaded for a typical
query. That's definitely a change in guts of `raco setup' (but probably
no change to Scribble).

> 3. Have Emacs find the appropriate "index.html" on the filesystem or on 
> "racket-lang.org", and then send a URL to that with the "q" query 
> parameter for my symbol, letting the JS look up the documentation, and 
> waiting for the JS the first time.  This will at least get me a list of 
> search hits, but won't jump to the documentation for the exact symbol.

It seems like it shouldn't be too hard to tell the search page to jump
to a first hit automatically (i.e., you're feeling lucky) --- a
relatively small matter of Javascript programming, I imagine.

> 4. Have Emacs load the documentation indexes (perhaps in the background 
> when idle, at startup, and when we notice they change) and do the lookup 
> in Emacs.  This is what Quack did for older PLT documentation, and it 
> stopped working when the documentation format changed and I didn't have 
> time to rewrite.  I could also be sensitive about things like which 
> "#lang" we were in (like I could with an external process, if I passed 
> it the  "#lang" information).

Since the installation's cross-reference is in a format that is not
especially friendly to Emacs of Javascript, here are some pointers if
you consider writing a translator:

 * Use `load-collections-xref' from `setup/xref' to load all
   cross-reference information.

 * Use `xref-index' from `scribble/xref' to get a list of index
   entries, where the `desc' field in the result lets you know which
   ones correspond to documentation for a binding. Use
   `xref-tag->path+anchor' to map an entry's tag to a URL.

I imagine that you're run the translator once per installation, but
you'd also want to run after a planet package installation, too.

At Sat, 25 Jun 2011 04:20:18 -0400, Neil Van Dyke wrote:
> Forgot to mention: I could also use quick-reference information of 
> procedure/macro syntax/args in Emacs, for displaying in echo area or 
> tooltip as you're editing a use of the procedure/macro.

Originally, I imagined that the cross-reference information would
include some form of the information that appears in a blue box in the
manual, but I never got around to that. Currently, the information is
only in the rendered documentation.

Posted on the users mailing list.