[racket-dev] Redirecting documentation links

At Fri, 6 May 2011 11:51:08 -0400, Sam Tobin-Hochstadt wrote:
> On Fri, May 6, 2011 at 11:42 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> > At Fri, 6 May 2011 10:13:33 -0400, Sam Tobin-Hochstadt wrote:
> >> Is it possible to tell Scribble to use the documentation for one
> >> binding for another binding?  For example, Typed Racket has a binding
> >> for `for' which is semantically the same as `for' from `racket/base',
> >> but wraps a trivial type annotation around it.
> >
> > I don't yet buy this "it's the same, except different" suggestion. If
> > the `for' from `racket/base' doesn't work with Typed Racket, then
> > shouldn't the docs admit that the `for's are different?
> 
> Here's another example: `with-handlers' in Typed Racket is similar,
> however, there's no user-level explanation of what's different about
> it, other than "works with Typed Racket".  The difference is that the
> version in `typed/racket' adds on some syntax properties to some of
> the sub-forms, and then expands to the plain `with-handlers' from
> `racket/base'.  However, these syntax properties are not available to
> users, and their behavior is just an implementation detail.
> 
> Thus, the documentation for `with-handlers' in Typed Racket could be like this:
> 
> @defidform[with-handlers]{is like @racket[with-handlers] from Racket,
> but works in Typed Racket.}.
> 
> In this case, the user has an extra click to figure out what they want to know.
> 
> Or, I could replicate the grammar, or maybe the whole documentation
> for `with-handlers' in the TR docs, but that will surely lead to drift
> or other kinds of confusion.
> 
> For `for', the situation is a little better, because the difference is
> explicable at the user level, but it's still not great.

The explanation and indirection looks right to me.

There's a tension between documentation that explains everything that
should be explained and documentation that succinctly and clearly
explains what most people need most of the time. Our
guide-versus-reference organization tries to manage that tension, and I
think it's sensible for `racket/base' and `typed/racket' to share a
guide-level description of `for'. At the same time, we don't yet have a
good way for a user to pick between guide-level or reference-level
information; I think it would solve the immediate problem and much more.