[racket-dev] [racket] getting symbol documentation URL quickly within Emacs

We can improve the documentation system. 

This kind of objection has been raised time and again (not the very same objection but dependence on racket or assumptions about running in drracket). We cannot and will never convince all people to use DrRacket or even Emacs. Some lost souls will continue to use vi. (I have used it for 25 years at least once a year and I will admit it, on rare occasions I have edited Scheme/Racket files in it.) 

So, since Eli has invested a tremendous amount of time in the JS part, I am sure he can figure out how to render it for other info systems. 

We may just have to make Emacsers happy first to see how to create an entirely general doc system for interfacing from all kinds of worlds. 

Eli? 

-- Matthias





On Jun 25, 2011, at 4:27 AM, Robby Findler wrote:

> 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
>> 
> 
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/users