[racket] How to document a package and access its documentation

From: Eli Barzilay (eli at barzilay.org)
Date: Mon Aug 12 15:42:23 EDT 2013

40 minutes ago, Vincent St-Amour wrote:
> If we're going to have different rings at all (which I think we should),
> then we should have a way to present documentation for all rings, not
> just ring 0. Allowing package authors to provide a link to external docs
> (as Asumu was suggesting) sounds like a good solution for non-ring-0
> packages to me.

+17; having docs only for the innermost ring contradicts the goal of
having all packages be equal.

But if authors submit their own links then you can get there quickly,
but you still have a problem: each documentation will have a different
format, which will make it hard to navigate.  One way to deal with
this is for the server to verify somehow that the docs are built with
scribble -- some simple check of some textual signature on the page
(no motivation to cheat, since you're only hurting the popularity of
your package).

But it's even better to just allow people to submit packages with
scribble docs as usual, and build them.  Yes, that means running
arbitrary code -- but it could do the rendering in a sandbox.  (It
would be hard to do with PDF output, since that runs *tex with the
same problem, but HTML rendering is all in racket.)

          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                    http://barzilay.org/                   Maze is Life!

Posted on the users mailing list.