[racket-dev] Redirecting documentation links

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.
-- 
sam th
samth at ccs.neu.edu