+1 On Friday, May 6, 2011, Matthew Flatt <[email protected]> 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 <[email protected]> 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
_________________________________________________ For list-related administrative tasks: http://lists.racket-lang.org/listinfo/dev
