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.
