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

At Mon, 12 Aug 2013 15:42:23 -0400,
Eli Barzilay wrote:
> 
> 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.

I don't think documentation format is really a big problem, as long as
it's human-readable. How to find it in the first place is the big
problem IMO.

> 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).

I don't think that's a good idea.

If someone wants to write their docs in, say, markdown, or as a text
file, then they should be able to link to them too, IMO. Sure, Scribble
docs are best, but text docs are better than no docs.

Again, I see that as a "barrier to entry" thing. IMO, we want to keep it
as low as possible.

> 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.)

What about rendering the docs on the client side (with the right prefix
for links to the main docs)? Isn't that what PLaneT is doing?

Vincent