Outdated help pages

the help page for [scratchblocks][ v] of [list] :: list[/scratchblocks]
is outdated.

I'll make a PR if I can get on my computer.

Edit: Which isn't going to be until tomorrow.

Gonna be hard. I think it's okay if the emphasis is still on LENGTH, with the other options explained briefly.

Don't worry; I'll manage. That is, until I make the PR and if you say there's something to improve.

Is this a good example?:

I'm not sure what the MAP adds to the understanding of LENGTH. I'd prefer something like

to make the point that it's only toplevel items that count.

Ok. I'll use that.


You could just delete the post

What's the rank of a list?

Edit: Nevermind. Is this good?:

I think I would put the last three lines in green type, and off to the side say "these three report a string, not a list." And try to explain the domains of the last two:
csv takes a two-dimensional array and gives the equivalent in spreadsheet notation.
json takes a deep key-value list as input and reports the equivalent JSON notation.
(or something like that.)

Oh and for COLUMNS I think it'll be clearer if the list isn't square: ((a b c) (d e f)) ➞ ((a d) (b e) (c f))

And even though I'm sure I started it, let's try to move to real arrows instead of ->.


(I wish I didn't have to make a new text thing every time I want to change a line of text.)

I'll try that.

Edit: Is this good?:

How are you making these? Can't you edit the existing text? A second reason I'm wondering is that the menu items in the white menu look as if they've had their size changed repeatedly. (I am (probably annoyingly) pleased, though, that the readability problem is in the sans-serif text, contrary to what all y'all keep telling me! ~:P)

I should really try to think of all these points in one pass; I apologize.

The line saying "Examples:" can be omitted, which is good since I'm going to make suggestions in a moment that will make the bottom portion of the screen taller.

"It only gives" has "only" modifying the wrong thing; it suggests that the block should do something else too. The minimal change to fix that would be "It gives only," but actually I think the meaning would be just as clear and the text less awkward just to leave "only" out altogether. If you think that's not clear enough, maybe "It gives the number of item of the outermost list, even if some items are themselves lists."

"There are other attributes, too" seems to be saying something obvious, especially after "an attribute" is used in the title, rather than "the length." Instead say "Here are the possible attributes:"

I think the menu items should be typographically distinguished somehow in the text to the right of the menu, especially when the menu item is in the plural, e.g., "LINES joins each..." or "lines joins each..." or something. If you pick something other than capitalization, make "LENGTH OF DIMENSIONS OF" and "FLATTEN" use the same decoration.

Here's where I want to increase the height of the screen: continuing the FLATTEN line onto the right edge of the COLUMNS line is confusing, and "These three return..." is in too busy a context to make it clear what "these three" are. So I'd go with

FLATTEN reports a list of the atoms... g))) is
    (a b c d e f g)
COLUMNS is ...

and similarly split the JSON line in two, so that the "These three" text is far to the right of all three of the lines to which it refers. (Oh, I often mess up about this, but we're trying to be consistent about "report" rather than "return.") Then you could move the "These three" down a line, so it's vertically centered among the three.

I changed the text for FLATTEN because "a list of each item," if you think about it, would just mean to report the input list! (Compare MAP (ID) OVER.) My text isn't perfect either, because you have to know what an atom is. Maybe "a list of the items of items... down to non-lists"?

Actually every instance of "is" in that chunk of text should be "reports" or "means."

I'll read this tomorrow and then do all that.


I took a screenshot, cropped it to the menu, then resized it down so it would fit. (I would do dev mode>right-click>pic... except that doesn't work on Edge.)

It's fine.

Is this better?:

Edit: Should I add the base help file with layers in the PR when I make it?


Why'd Jens add this and remove this?

Ugh, I'm an idiot: LENGTH, add space in "isdescribed"; FLATTEN, "I.e." should be "e.g." and there should be a "g" in the output! The REVERSE example should be something like (a b (c d e) f) to make the point that only the top level is reversed.

Splitting the menu to make the green text clearer is clever, so much so that you could try turning it back to black if you wanted. But it would be great to have a dotted outline of the rest of the menu below the first part and above the second part.

I apologize again for being difficult.

Why did you change the arrows to "turns into"? The problem with that wording is that it suggests that the block mutates its input rather than create a new list.

About Jens's changes to the repo, either he rewrote the changed part or else he rearranged PRs to get rid of a merge operation.


Because I couldn't think of a good wording that kept the arrows.

(I'll edit this when I'm done)

Edit: Here:

Edit 2: Oh I just thought of a wording for it! Let me update the image real quick.

Edit 3: Re-uploaded the image here.

Edit 4: The black-text version of the above:



what? when did he change it?