On Fri, May 6, 2011 at 11:42 AM, Matthew Flatt <mfl...@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
sa...@ccs.neu.edu
_________________________________________________
For list-related administrative tasks:
http://lists.racket-lang.org/listinfo/dev
