[racket-dev] Racket documentation

I agree with ELi here. 

On Sep 25, 2010, at 1:21 PM, Eli Barzilay wrote:

> An hour ago, Everett Morse wrote:
>> Comments on the below discussion and possible implementation ideas.
>> 
>> User-contributed comments should be annotations to the
>> documentation.  They could then be fetched using JS (Ajax) from the
>> local copy when an internet connection is available,
> 
> You mean from the remote copy, right?
> 
> There some major problems with what you suggest:
> 
> 1. Writing JS code that detects if you're connected to the web is,
>   IME, somewhere between "impossible" to somthing that depends on the
>   browser, on configuration, and a bunch of other things that just
>   make it not worth it.  (This is all going through "file://" urls
>   that are extremely restricted that even the current docs are much
>   less pleasant on IE.)
> 
> 2. Even if you can, you need to face the problem of where the
>   annotations go.  It's not enough to rely on an annotation with a
>   version range spec -- the actual text that it refers to might
>   change in a way that will make it anchor in the wrong place or
>   whatever.  (Even url anchor strings change.)
> 
> 3. And even if you get that resolved, you still have the issue that
>   Neil raised.  That's why I suggested a preference for:
>   * Using the remote docs.racket-lang.org
>   * Using a local copy if it's installed
>   * Using the remote docs if they're accessible, falling back to
>     local docs otherwise
>   with the last one being the default.  There's also a minor privacy
>   thing with that, but if you get a browser on a remote page, that's
>   much better than a local file:// page that goes remotely behind
>   your back.  (And that means that option #1 is probably closer to
>   "impossible".)
> 
> -- 
>          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
>                    http://barzilay.org/                   Maze is Life!
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/dev