You tell me equality is extensible, and now I know that, and I go look at that page and scan it from top to bottom. I do the usual things I do to read stuff online, and I've been pretty successful with my reading, my reading comprehension scores were excellent in standardized tests, I have a phd that was about nothing if not reading opaque publications, and now I'm faced with this page and I still have no idea how to tell that equality is extensible, or how to go about extending it. If you hadn't told me I'd look at that page about booleans and have no reason to expect it to bear the slightest relationship to equality for complex user-defined data structures[1]. Search for 'extensible'. Nope. Oh, 'inspectable structures.' What the sam hill are those? It has to do with prop:equal+hash, which doesn't even look like a single token to my eyes. Is it a function? How do I use it? All this goes through my mind in a flash, and all I feel is stupid.
I keep waiting for the racket reference to gradually become clear, but it's been a year now of poring over it and I don't think it'll ever happen. It's a blind spot, platform nine and three quarters, just around the corner but at ninety degrees from all three dimensions that I can see. I would never ever have noticed that equality is extensible until you told me that was so.
[1] I scan back up and it's right there in the title: "Booleans and equality." See what I mean about feeling stupid? Why should booleans and equality be grouped together? Why should equality be in the section on datatypes and not say structures?
0. Note that the actual link is broken -- it's missing a ")" in the end
(it's there, but it wasn't included in the url for some reason (I
don't know about the local markdown language...))
1. Yes, some of these issues are known, and we're in a constant race
with improving the documentation in various ways. As always, emails
to the mailing list or bug reports -- or better: suggestions and
possibly patches -- all of these are always welcome.
2. In this particular case, I didn't need to guess -- I knew that it was
added, so I just needed to find that reference.
3. But if I were trying to find it, the first place I'd look would be
the documentation for `equal?' -- and it is indeed there, at the end
of the second paragraph.
4. As for how you use this property, the text that I referred to has a
link to "Structure Type Properties", which describes all of that.
5. Re the organization -- booleans and equality are grouped because
they're related... It also appears as the first subsection in the
datatypes chapter, which makes sense there. If you have an idea how
to organize it better, then see #1.
6. Yes, it would be nice to have some section that lists all of the
properties that could be used for structs. The main problem with
doing this is that it's an open system, so anyone can add more
properties, but it won't make sense for the core to list properties
from modules outside of it. This was discussed recently, and I don't
think that anyone had an idea what to do about it.
"if I were trying to find it, the first place I'd look would be the documentation for `equal?' -- and it is indeed there, at the end of the second paragraph."
Part of the problem is that I never tried finding it, because it didn't occur to me that racket would have extensible equal?
A few months ago I was flattened - absolutely flattened - to find out that PLT has optional args and keyword args. (http://arclanguage.org/item?id=12591)
I have no idea why this is. Perhaps the problem is that people expect scheme to be a small language.
Well, the optionals and keyword arguments have been in for a long time now... In fact, the current thing is a second iteration after a first facility that was more CL-like...
In any case, Racket is certainly not a small language...
Yes, as I was ranting I was feeling bad for not having contributed to improve things. I wasn't being rhetorical about feeling stupid and guilty. Lack of understanding is a barrier but no excuse. For me to say "I have a phd, but this I can't read" is akin to saying "I've learned spanish, but chinese is hard." Well, d'uh. Deal.
Perhaps PLT needs a user guide in addition to a reference, a level of redundancy with a kinda orthogonal organization (focusing on complex tasks involving multiple advanced concepts) that'll help people triangulate on understanding, or just use what works for them.
I'm going to withdraw my rant. It's something specific about my stupidity that's causing me these problems. Still investigating.
Ah, I think I see what's been happening. Since I started out with arc I've restricted myself to the mzscheme 'ghetto' and not paid as much attention to the racket language itself. My attitude was "who knows what works in mzscheme and what doesn't." This has been the root cause of my troubles, I think.
Thanks for the link to Guide: Racket. I've also had trouble getting into Racket's documentation, but this looks like a much more accessible starting point than Reference: Racket.
