Arc Forumnew | comments | leaders | submitlogin
2 points by akkartik 5090 days ago | link | parent

That is awesome, thanks for the tip.

Now I want to rant about Racket documentation.

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?



2 points by elibarzilay 5090 days ago | link

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.

-----

1 point by akkartik 5090 days ago | link

"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.

-----

3 points by elibarzilay 5090 days ago | link

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...

-----

1 point by akkartik 5090 days ago | link

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.

-----

3 points by elibarzilay 5090 days ago | link

Heh, excellent idea: http://docs.racket-lang.org/guide/

(See also other such documents at http://docs.racket-lang.org/getting-started/)

-----

1 point by akkartik 5089 days ago | link

I've seen that before. Why have I not paid more attention?

Here's the extremely clear guide on extensible equality: http://docs.racket-lang.org/guide/define-struct.html#%28part...

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.

I'm going to focus on core racket now.

-----

2 points by evanrmurphy 5090 days ago | link

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.

-----