[racket] getting symbol documentation URL quickly within Emacs

You can improve the documentation system. :)

Robby

On Sat, Jun 25, 2011 at 4:20 PM, Neil Van Dyke <neil at neilvandyke.org> 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.
>
> So, how the quick-reference gets implemented might influence how getting the
> URL for more documentation gets implemented.
>
> Neil Van Dyke wrote at 06/25/2011 04:13 AM:
>>
>> 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 prefer
>> not to keep a "racket" process open for this purpose, and invoking "racket"
>> each time is uncomfortably slow.  (As the below timings show, the "help"
>> macro is not very fast: on my 2GHz dual-core (with no swap), when the
>> pertinent files *are* cached by Linux, getting the URL takes about 2.6
>> seconds.  When caches are empty except for what is needed to start the
>> "racket" process, getting the URL takes about 15.6 seconds.  Looking up
>> *subsequent* symbols in the same "racket" process takes only around 0.2
>> seconds, however.)
>>
>> 2. Keep a "racket" process open and use some lookup of my own design.  I'm
>> guessing this is the same as "racket/help", and so I have the same
>> objections.
>>
>> 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.
>>
>> 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).
>>
>> Any more ideas/thoughts?  (Other than pressing me on why I'd rather not
>> keep a "racket" process open for this purpose.  Eventually the new Emacs
>> mode, Meow, will probably do that for things like Check Syntax, but I don't
>> want to go there yet if I don't have to.)
>>
>> Note that all these require some notion of *from which Racket install tree
>> or which Racket version on the Web do you want this documentation*, and
>> that's some HCI and coding work that has to be done in any case.
>>
>> ---- BEGIN ----
>> ~  echo 3 | sudo tee /proc/sys/vm/drop_caches
>> 3
>> ~  echo '(display "hello, world!\n")' | racket
>> Welcome to Racket v5.1.1.
>> > hello, world!
>> >
>> ~  time echo "(help begin)" | racket
>> Welcome to Racket v5.1.1.
>> > Loading help index...
>> Sending to web browser...
>>  file: /usr/local/racket-5.1.1/share/racket/doc/reference/begin.html
>>  anchor: (form._((quote._~23~25kernel)._begin))
>> Starting Firefox...
>> >
>>
>> real    0m15.584s
>> user    0m2.472s
>> sys    0m0.180s
>> ~  time echo "(help begin)" | racket
>> Welcome to Racket v5.1.1.
>> > Loading help index...
>> Sending to web browser...
>>  file: /usr/local/racket-5.1.1/share/racket/doc/reference/begin.html
>>  anchor: (form._((quote._~23~25kernel)._begin))
>> Starting Firefox...
>> >
>>
>> real    0m2.622s
>> user    0m2.240s
>> sys    0m0.124s
>> ~ time echo "(begin (help and) (help or))" | racket
>> Welcome to Racket v5.1.1.
>> > Loading help index...
>> Sending to web browser...
>>  file: /usr/local/racket-5.1.1/share/racket/doc/reference/if.html
>>  anchor: (form._((lib._racket/private/letstx-scheme..rkt)._and))
>> Starting Firefox...
>> Sending to web browser...
>>  file: /usr/local/racket-5.1.1/share/racket/doc/reference/if.html
>>  anchor: (form._((lib._racket/private/letstx-scheme..rkt)._or))
>> Starting Firefox...
>> >
>>
>> real    0m2.858s
>> user    0m2.216s
>> sys    0m0.116s
>> ~ ---- END ----
>>
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/users
>