Great work again. It looks very impressive (aside of very dense, which is a good thing for a reference card). I have gone through it in detail, and learned a few corners of J I did not know yet. I made a list of remarks I had which, I see now, has grown considerably, but please take it as a sign that I really really appreciate all the work you put into this and that I want it to be the best reference card in the world. So here it is (I clearly took Henry's number 3. use-case to heart: completeness):
I agree with all that's said so far. For you're convenience, I'm copying the points I made in my previous email (http://www.jsoftware.com/pipermail/programming/2022-August/061264.html) that are still valid. Perhaps the Glossary could be extended with e.g. parts of speech Scalar monads and dyads ------------------------ I'm all for parallels with mathematics, but the domain for dyadic ! is actually wider than the mathematical combination (), as it is extended to (!y)%(!x)*(!y-x) with ! being Gamma(x-1). This could go in a footnote. Having read the discussion on the example for ?. , I agree both with the fact that 2 4 is misleading, as well as that it is the correct outcome. Why not just delete the example and put ?. having a fixed seed as a footnote to '?' ? Additionally, why does the monadic ?. even have rank _ , opposed to ? having monadic rank 0? Their results seem congruent... I found rnd not clear initially, as it is confusable with "round", why not call it random? Why not sign or signum instead of sgn? % : might be worth mentioning that x%0 is not an error, but defined as the limit case limit y->_ of x%y. Selection & Join and Reshape ----------------------------- # with complex numbers is IMHO not clear from the example, and might deserve a footnote like {.@+. y is amount of fills after each item (or in math notation). Dyadic |: is missing The curly braces in the footnote b are missing for head and tail. I'd reword "Omitted x=1" to "x defaults to 1 when omitted" or "Omitted x defaults to 1". The examples "(i. 2 2), ,8" and "(i. 2 2), 8" have the wrong result. ;: it's not clear from the example what's happening. The example could be made more interesting using 0 3 instead of 3, as it shows that it's not split on punctuation as one might guess from the example. Adverbs -------- m~ is missing (evoke), I'd put it in the Adverbs table, rather than "Miscellaneous". The footnote for / seems slightly wrong, it does not operate on every item (noun rank - 1) of x, but on every operand cell, i.e. it's equivalent to x u"(lu,_) y, as per the good old dictionary https://code.jsoftware.com/wiki/Vocabulary/slash#dyadic (all the way at the bottom, for some reason). Outfix is not clear for the negative argument. Nuvoc expresses it better than me: (x u\. y) applies verb u to successive outfixes of y. Each outfix is y with an infix removed. The infixes depend on x, as described in Infix (\). In the footnote f for ;.+/-3, I'd say u applied to *each* of the shaded areas The example for ;. does not render clear the function of x. I'd use like (1 0,:2 3), showing clearly that the first row represents the top left corner and the second row represents the shape of the result. Cyclic gerund: great you mentioned, well summarised, but it misses key /. . Shape, length and rank / Arg / Booleans ------------------------------------------------------- Rank could have a note pointing the user to the distinction between noun and verb rank (often a source of confusion). I find having some examples of " here, and the actual definition in the "Conjunctions" table a bit odd. I would move all rank related items to the "Shape, Length and Rank" table. The argument table could benefit from left/right columns, or at least aligning x u m u. and y v n v. to align vertically. Booleans: you could mention as footnote: Ranks 0; Boolean operations when applied to 0/1, domain wider, see scalar verbs. Wouldn't it make sense to merge the the x m b. y table p.2 with the "Booleans" table? That way you could just list the m next to the lines of the current Booleans table, and the rotates and shifts could go to a footnote. Miscellaneaous --------------- -: footnote: what does tolerant equality of shape mean? (1 -: ,1 => 0) ~ : I would expect this with the adverbs (as I said above). I find I. a bit of an odd duck when out of the indexing Table, as its main use is converting Boolean indexing to integer indexing. Additionally, it could merit to include as well the general case for I. , i.e. repeating each index in y y times or I. <=> (#i.@#). ". footnote could be more clear and accurate as: "returns 0$0 when result not a noun". ".&'name' does not seem to work for me (actually, I don't understand the result; it appears to be identity, it looks like a bug...). ".@'name' does work. Z: could be mentioned for terminating folds or their iterations. Maybe a candidate for the Misc table: !. Fit. Don't know whether it would fit here, and likely would just be a name and a link... Foreigns --------- 6!:0 does not take x, nor a boxed y, only '' or format string 6!:2 and 7!:2 also take a bare literal. Could be worth mentioning timex and timespacex from the standard library. Exit'' might also be a good one. Debug commands/Indexing ------------------------ I'd mention dbhelp, great for self-help. I don't know how addons are looked upon for the refcard, but if OK, I would find a mention of dissect and trace helpful. As special combinations are listed for indexing, perhaps m&i. merits a mention (along with its inverse?), perhaps as example a.&i. ? Modifier trains ---------------- The modifier train table takes up quite some space (for a feature that's present, but I think not quite generally used), and in my opinion, several cases can be joint, and numbers can be dropped (since they alwazs stay in the same order anyhow), I sent my version http://www.jsoftware.com/pipermail/programming/2022-August/061264.html in case that could be useful. If not, I totally understand a case could be made for having them all listed in full. When trying to understand longer trains, I found looking at the parsing table (https://code.jsoftware.com/wiki/Vocabulary/Parsing#The_Parsing_Table) helpful. No idea whether including it would be overkill. Conjunctions -------------- The dyadic case of x m&v y -> x (m&v @ ] ^: [) y is missing. Also, I think that u@n y should be rendered as u@(n"_) y to render clearly that u@n returns a verb, rather than just applying u to n. I think footnote c should put at v, not u. Putting it at the left side as well would render it more clear. The footnote now says "u is applied to one argument" could be rephrased more clearly as "ul or ur is applied to x or y (x,y could be added to the line in the table as well). Footnote c could be also present for &.: . If moving all " (rank) lines to the rank table (see above), the remaining conjunctions seem mostly related to function composition and iteration, so that table could be called "Function composition & iteration". The gerund case to ^: could use a footnote stating v0 defaults to [ if only 2 verbs are given. Really nitpicking now: converges -> convergence x u^:v^:_ y I would phrase the right column as : apply ... til 0 = x&v y (note the last v instead of u) The last line has capital V's on the left and lowercase v's on the right. I find the footnote f a tad misleading: indeed to be interpreted as if-statement, v should return 0 or 1, but it could be interpreted as ^:v being limited to boolean functions, though e.g. >:^:+: 5 works perfectly fine. Perhaps f could read "when v produces 0 or 1; otherwise x u^:(x v y)". Or perhaps the general case x u^:v y <=> x u^:(x v y) y deserves its own line. Could u^:0 <=> ] be added to footnote e? Complex numbers: The only item that's not executable J code in example column is pi. I think it could be 1p1 for consistency. The same holds for e in Scalar monadic verbs, which could be rendered ^1 or 1x1. Mathematics ------------ I'd add one of the most common use of matrix divide as least squares linear fit: 3 4 (%.1,.])~ 7 9 => 1 2, if not as a table line, maybe as footnote (note ~ used such that x and y refer to independent and dependent variables as usual). I'd put footnote b next to the - , rather than *, because it has to replace the -, not the *. For the third column for the C. examples I think there could be single arrows (or maybe better, one example could be suppressed, as for p. where there is only one line for the two directions). The third C. example could have added after x: "(direct or cycle)" I think the first line p. description should also mention polynomial like "Polynomial coeff <-> roots". I think p: for x=_4 is not correct as _4 p: 7 is not 7, but 5. I think it should read "max prime < y". p.. might be added as well. Explicit definition / Item selection -------------------- There could be a mention of m : n with n being boxed lines (which funnily enough does not seem to work for e.g. 0 : (;:'hello world!'). Footnote g has a spurious "{" . I find the title "Item selection" a bit of a strange title for these verbs, but I don't quite have a better alternative... I'm missing monadic = in this table. Control structures ------------------- Footnote c: "assigned assigned" seems repeated and one seems redundant (unless I'm missing something). I don't find fcase to be particularly clear, as it looks more like "f case." than "fcase.". I'd prefer just "case." with a footnote mentioning that case stops once matched, while fcase continues to the next case. Footnote d does not seem to be matching the location of its reference at the f of fcase, but should likely be placed at the select. T block. Catchd. could use a footnote like: "catch unless debug on". Seems footnotes on the last line have gone wrong. f should go to return.; g should go to break.; h should go to continue. Assert. is missing the B referred to in footnote i. Objects and locatives ---------------------- Second line: I'd say: create object (or instance) of 'mycl'. In my class would mean the object's reference would end up in the mycl locale, which is not the case. I think the 0".> clutters more than making things clear. I most often see objects' reference being kept boxed. That they are allowed unboxed, I didn't know (thanks) but I think should go in a footnote. Maybe it would be best to use obj instead of o on the second line, so it's congruent with the other references to obj. I think other things could be added here (all with footnote stating that locale operated on is either the current, __obj or _loc_): the locales _base_ (Default) and _z_ (always accessible, stdlib location) ; coinsert: add locale to search path codestroy__obj: destroy locale obj (note, don't do codestroy'') coname'': what locale am I currently in? conames ''/0/1 : list existing locales (all,named,numbered) copath 'loc' : get current path for loc (footnote about hierarchical search through path) names '': list defined names (Not strictly object/class/.... tools, but very related): erase name: remove name clear loc : clear all names in loc (note NOT with underscores). Formatting ----------- I don't think to **** in the top example are clear: ": could use a note "ajb: sets width=a, decimals=b; if a or b negative, scientific notation. *'s if number not fitting." 0j_3 ": 1e2 is 1.000e2 for me. The 8!:0 example seems to have the result for 1e4 _1e4 instead of 1e5 _1e5 The 8!:1 example's result should have _2.000 in the lower left; the alignment of the 3.0 comes out left for me... Boxing table missing? -------------------------------- I remember in the previous draft there was a table on boxing. It could list < , >, ; , each, every, {:: , L., L: and S: That's it from my side. I hope my comments are useful (and again, this is what I noted reading the card, if you don't agree for any reason, that is perfectly fine by me). I really enjoyed going through it, and discovering things I forgot or never knew. I'm looking forward to the next iteration. Best regards, Jan-Pieter Op di 9 aug. 2022 om 22:13 schreef Henry Rich <henryhr...@gmail.com>: > > Viktor Grigorov has a draft version of the new J Reference Card. Please > criticize it. > > The source for the card is a LaTeX document, and will be freely > available for editing. > > A PDF version is at > https://drive.google.com/file/d/1bpyfmksD-XEJaJJ972jOy3b2_KWfV0Wi/view?usp=sharing > > Henry Rich > > -- > This email has been checked for viruses by AVG. > https://www.avg.com > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
