[racket-dev] Redirecting documentation links

+1

On Friday, May 6, 2011, Matthew Flatt <mflatt at cs.utah.edu> wrote:
> 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.
>
>
> _________________________________________________
>   For list-related administrative tasks:
>   http://lists.racket-lang.org/listinfo/dev