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
