Organize "Core API -> misc" into categories, similar to the Clojure Cheatsheet

[bluMyst]

Currently the "misc" section of the Core API docs contains 352 functions in alphabetical/ASCII order. This makes it pretty difficult to find what you're looking for, unless you already know what it's called.

Instead I think it would be much better to organize this section into categories similar to the Clojure Cheatsheet, which will help the reader to greatly decrease the number of functions that they need to look through before they're able to find what they're looking for.

If it's not possible to change the specific page that I linked to above, it might be helpful to have a "Janet Core Cheatsheet" somewhere else in the docs, and link to that at the top of the "misc" section.

[sogaiu]

I'm still processing the ideas here [1], but wanted to point out that I've gotten a fair bit of use out of doing a search on the Core API page. Perhaps it's partly because that page has docstrings for all of the core functions, macros, dynamic variables, etc. [2].

I didn't realize how useful that could be until someone else mentioned they had been doing so [3].

---

[1] I find the cheatsheet idea appealing but imagine it could take a fair bit of work to do well.

[2] Special forms don't appear. Examples (which sometimes have comments) are being added slowly though.

[3] Which turned out to be a few years into using Janet...

[bluMyst]

The suggestion for doing a Ctrl-F search on the Core API page sounds like a really good one! Thanks for mentioning it.

You might be right that it would take a lot of work to categorize the Core/misc functions well. I'm still a total beginner with Janet but if I get the energy sometime soon I might try different ways of categorizing everything and see if I run into any issues, and post the results here. Naively I assumed that it would be fairly simple, but it's hard to say without trying it. (Of course I might also end up creating a categorization scheme that is pretty unhelpful for answering certain types of questions, which is another thing to consider.)

[bluMyst]

I've been experimenting with different categorization schemes for a while and here's what I have so far. It's very rough but I think it would at least be very helpful for me, personally, in its current state: https://gist.github.com/bluMyst/cb727cac4e2208ab0606b444eec11811

What do y'all think of it? I don't know Janet very well yet so I may be missing certain things that are obvious to y'all, or making beginner mistakes in how I think about certain forms. There are also a lot of things at the bottom that I didn't feel like I was able to effectively categorize because I either didn't understand what it did, or I didn't understand when/why it might be helpful to someone.

[sogaiu]

I started going through it but it's a fair bit to digest 😅

---

sometimes one form fits well into multiple categories, so I deliberately include it in all of those categories.

I think that makes sense.

---

since this cheat sheet is meant to be used by everyone, it could really benefit from being reviewed by as many different people, who have as many different perspectives about programming, as possible. especially beginners to Janet

Perhaps you know already, but FWIW there is a Zulip instance for Janet where there are Janet-related discussions. It might be that there are some folks there who might be interested in taking a look.

---

# NOTE: if string and buffer are data structures then keyword and symbol are too...
# right?

Yes. FWIW, the table on the Data Structures page is consistent with that way of thinking.

---

convert to primitive:

I can see thinking of scan-number as fitting this description, but I don't feel like it's a great description for the other items listed there. At least, when I use the rest of what's there, I don't think I'm thinking to "convert to primitive". Does that make sense?

I'd be more inclined to put reduce and reduce2 under "transform" somewhere. They can be used to produce primitives but they are not limited to that, e.g.:

(reduce (fn [acc elt] (put acc elt true))
        @{}
        [:ant :bee :cat])
# =>
@{:ant true :bee true :cat true}

sum, product, mean, and geomean seem like they could be separated off.

Not sure though 😅

---

Going to pause for now.

---

One thing I'd like to point out is that there are discrepancies between existing documentation (e.g. docstrings) and actual behavior (surprised?). Some of us are slowly working on clarifying things, though this is sort of an informal extended effort.

This document is a sort of summary of an effort last year where we tried to add examples (to end up on the Core API page). In the process I think we managed to improve some of the docstrings not to mention help with improving our understanding.

As you can see from the paucity of examples on the Core API page though, we are far from finished.

[bluMyst]

hehe - yep sorry that it's so much! I guess this is a pretty big project but I would love to do what I can to see that it gets done. even if it isn't added to the official Janet website I might host it somewhere else because at least I would personally find it really helpful, and I think it'd make Janet a lot more beginner-friendly - especially to folks that aren't used to Lisps and would be intimidated by a long list of forms

---

thanks for telling me about the Zulip instance! once I've tweaked this cheat sheet a bit more I might post there and see if anyone has any more suggestions. although I think I want to use Janet more on my own first so that I have a better understanding of the language - I think I was too quick to jump into trying to improve the docs because I sitll haven't even written a decent-length program in it

---

and hmm you're right that "convert to primitive" isn't a very good name and might not even be a good way to categorize things. I've been roughly thinking of certain categories in terms of what types they take as input, and what types they give as output. so I thought it might be helpful to have a category for "takes a data structure and returns a primitive"

if I were to follow the Clojure cheat sheet's example I might have a category called "using a data structure" with subcategories called things like "extract item" and maybe "calculate number". although I think "using a data structure" is a pretty vague name and doesn't communicate that everything in that category returns a primitive

also, you're right that the reduce functions can be used to make any type - not just primitives. maybe it would be best if I put them in a category for "data structure to primitive" as well as a category for "data structure to data structure", or I might even have a third category for "data structure to any type"

---

it's very good to know that the docstrings aren't quite fully accurate yet! I hope that's something that I can help with in the future - as well as adding more examples (I think examples are extremely helpful)

---

also, thank you for spending your time and energy to look at what I've come up with so far! I love what I've seen of Janet so far but I've definitely noticed some places in the documentation that I think could be improved and I'm hoping that I can spare the time and energy to improve them. I'm very passionate about good documentation and I already have a lot of ideas for things that could be tweaked

[taoeffect]

I was just asking about this on Zulip, and someone pointed me to this issue.

It would be so helpful indeed if the functions were organized into sections based on categories.

For example, I'd like to know what all of the predicates are in Janet, but it's really hard to figure this out right now because there is no "Predicates" section in the docs.

newLISP did this really well, its docs were organized into two frames (I'd link to them but the site is down). The lefthand frame contained essentially a categorized list of functions ("Predicates" header, followed by predicates function names, "Strings" header, followed by string manipulation functions, etc.). When you clicked on a function in the left frame, the right frame would jump down to the docs for that specific function. The righthand frame was just all of the function API docs, also organized by category.

The two frames worked well together because the left frame was an overview you could see that contained no docs, just categories and functions, and the righthand frame contained all the docs (in the same order).

[veqqq]

Tangentially, half a screen above the linked section, (hopefully) all the useful predicates are listed: https://janetdocs.org/tutorials/learn-to-program#what-can-we-improve For all of them (with good names): (filter |(string/has-suffix? "?" $) (keys (getproto (curenv)))) gives you

@[function? even? neg? symbol? odd? dictionary? bytes? struct? truthy? idempotent? indexed? one? every? fiber/can-resume? buffer? int? cfunction? keyword? bundle/installed? lengthable? tuple? nan? has-key? nil? has-value? pos? true? abstract? false? string/has-prefix? nat? string? table? number? array? fiber? empty? any? zero? boolean? string/has-suffix?]

[taoeffect]

That's cool, thank you!

[sogaiu]

May be what was described in the comment above is like this?

I think it's still possible to get a sense of what the docs were like via the wayback machine.

FWIW, the screenshot above was taken while visiting here.

[taoeffect]

@sogaiu Indeed! The newLISP docs are definitely inspirational in that regard, very helpful for not only getting a quick, organized overview of everything available in the language, but also for jumping quickly from function to function and seeing both examples and type information (although the type information could also be improved).