[racket-dev] Racket documentation

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!