Which is better/correct style: "… can be written in the syntax '(1 . a) " or "… can be written with the syntax '(1 . a)"?

Or even something else entirely? :wink:

“…can be written as '(1 . a)“—might depend on audience. Do they know/care what the word “syntax” in this context means? (This is on my mind, too, since I’m about to document a data-file syntax for an application that is essentially a handful of pre-fab structs, but users are unlikely to be Racketeers. I’m working on an editor for the data-files, but the app is useable without it, so…)

I like the “written as” suggestion, it’s also shorter.

The text is for the Racket glossary, so the audience is Racketeers and aspiring Racketeers. :slightly_smiling_face:

Yeah, brevity was partly on my mind, too. Strunk and White will forever have a special place in my brain…

I can’t stand their dogmatic tone. :smile: But I’ve read other books on writing. :slightly_smiling_face:

Fair enough. It definitely is a “do it this way” kind of book. But maybe I always assumed they knew rules were meant to be broken, and so read it “more like guidelines, anyway.” (thanks, Barbosa)

I especially like “On writing well” by William Zinsser and “100 ways to improve your writing” by Gary Provost.

thanks for the recs!

I’m not sure if I should write an entry on hash sets in the glossary. In Python, for example, they’re a built-in data type with their own literal syntax. On the other hand, in Racket, hash sets aren’t in racket/base, but racket/set, so it seems they’re kind of secondary. Other data types, like lists and vectors at least have some of their functionality in racket/base.

You’re welcome! :slightly_smiling_face:

I had thought about writing about (hash) sets together with the other container types, but I guess I’ll focus on other entries first. :slightly_smiling_face:

I would not describe things as “secondary” because they aren’t in racket/base

Depends on how you define “secondary” :wink: , but I guess I get your point.

I meant “secondary” relative to lists and vectors. I did not mean that they’re not useful or important in some cases.

I agree that they aren’t as fundamental as those, but sets appear in the list of data types in the reference, for example.

I think @sschwarzer is coming from the perspective of someone who things “I’m new to Racket, and not having sets in “the Racket language” makes them feel less important somehow.” Now, “the Racket language” is hard to pin down, but someone new who hears “use racket/base” this could be somewhat confusing.

Just my 2 cents, though, maybe I’m wrong about their POV

That’s a good point, and I now see I have at least planned entries for almost all the terms under the data types in the reference. So I’ll cover them at some point, but maybe put them in the “intermediate” instead of the “basic” category (see https://docs.racket-lang.org/racket-glossary/index.html#%28part._.Introduction%29 for the categories)?

> but someone new who hears “use racket/base” this could be somewhat confusing. I think I don’t mention racket/base specifically in the glossary so far. The glossary is indeed intended as an overview of the terms, not as a reference, not even something close to it.

I think intermediate seems reasonable

> I think intermediate seems reasonable Ok, we’re on the same page then. :slightly_smiling_face:

I already changed it in my local repo.

I’ve written some of the “intermediate” entries, but I want to focus mostly on the “basic” category for now.