[racket] getting symbol documentation URL quickly within Emacs
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.