J documentation

Some advice on what to read and what not to read if you are a J beginner. This is a very personal perspective.

These days, essentially all documentation is freely available, both online and coming with the system. Most of the documentation or tutorials which J beginners are hunting for usually falls into one of two categories:

1. The "J is easy" camp:

   maintains that J --or at least a subset of J-- can be easily learned and used. Examples:

   • the "Introduction to J" / "Sample Topics" (these days bundled together with the proper "Dictionary of J")
   • J Primer
   • Learning J

   Most of these documents advertise as being a good introduction into the language, preparing you for dealing with the DoJ language reference afterwards.

   The style is often informal, and often the mere presentation of expression/result pairs is deemed sufficient to make you learn how J works. Because "J is easy". More subtle details are often completely ignored.

2. The "learn all the details!" camp

   with (so far) just two documents:

   • Dictionary of J ("DoJ")
   • J for C Programmers ("JfC")

   Both of these two documents are very rigid and get down to the details, but in very different ways.

   The DoJ (Iverson & Hui) is the official language reference document. The DoJ proper is really just the rightmost column of today's bundle linked to as Dic. (In 1990-94, the J interpreter was freely available but all J documents had to be paid for. The "Introduction to J" and "Dictionary of J" could be separately ordered at certain times, the bundling changing over time.)

   The DoJ is known/notorius for its terse, formal style, using many mutual cross-references when defining language parts.

   The JfC is a much easier read than the DoJ. But unlike the "easy" documents above, it doesn't simplify things. Au contraire: it takes great care to point out all implicitly running mechanisms which might otherwise go unnoticed. The patient reader ends up with a systematic, well-founded understanding of the language.

So you want to learn J and need to decide which document to start with. Probably you don't even know yet whether J should be part of your bag of tools at all, and you need an overview rather than "every little detail".

A trivial choice, it appears. Just go with some intro from the "J is easy" camp, not?

Well... perhaps not.

This article is a Cautious Advisory against any expectation that J could be taught or learned in any cursory manner.

The problem with "easy"

Truth is: in J, details matter. Many details. And most are implicitly/invisibly at work.

For example:

   m =. i. 3 5
   m
 0  1  2  3  4
 5  6  7  8  9
10 11 12 13 14
   +/ m
15 18 21 24 27

Yes, it looks simple and obvious.

It isn't.

Many "easy intros" usually don't spend much time on this. They all say

+/m is + inserted between the items of m.

(which is true), but they don't prevent you from turning that into a

The / makes + work across columns.

which would also explain the result above but would be, alas, wrong. But you have no way to recognize that at this point and merrily advance to the next section of your "J is Easy!" booklet.

Soon enough though, your J expressions will refuse to work. For example, you might bang your head against failing attempts to box the column sums above, such as

   <@+/ m
|domain error
|       <@+/m

or <@:+/m, or <@(+/)m, or <@:(+/)m, none of these working out. This is of course frustrating. Eventually, you'll manage to come up with a (much longer than expected) expression which yields those

+--+--+--+--+--+
|15|18|21|24|27|
+--+--+--+--+--+

At this point, you'll have heaped quite a few more extra characters to your J expression. If you are unlucky, you also added one or two new incorrect theories to your growing J model.

My personal experience during my own first three years (1991-1994) of dabbling with J was certainly like that. All those informal docs without further explanations didn't work for me. (And I had bought all of them, and read all the SIGAPL papers on J etc.)

After three years, half of my first-attempt J expressions would still fail. I felt increasingly unsafe using J.

This is how I finally came to a solid grip on the langauge (1994):

Ditching the Easy Intros

On a two-week skiing vacation in the Alps, I had no computer but the (small) "Dictionary of J" booklet with me. In the evenings, I sat down and sloooowly read it, starting at the very beginning and making sure to skip nothing. Very soon, on page 3, I would stumble over details in "Section II" I hadn't even been aware of so far, but which were at the core of many of my mis-understandings. Having these resolved, all other pieces of the big J puzzle started to fall into place, too.

It also defines many language elements in terms of other elements, replacing --for the uninitiated-- one riddle by even more riddles. It is therefore difficult to learn the language from this document.

So this was a very slow reading. Often I spent 30 to 60 minutes on just a single primitive, chasing down those mutual references to other primitives in an entry. In case you've never looked at the DoJ, here is a typical sample entry (Antibase #: (1 0)):

In simple cases r&#: is inverse to r&#. . Thus:

   r=: 24 60 60
   r #: r #. 2 3 4
2 3 4

But if r #. y exceeds (*/r)-1 (the largest integer representable in the
radix r), then the result of r#:y is reduced modulo */r . For example:

   r #: r #. 29 3 4
5 3 4

Let me repeat: expect to spend an hour or so on these two sentences when you start from scratch. You'll have to check anything that is explicitly referenced here (& #. * / -) if new to you. You'll should also consider how this definition works out for negative, scalar, empty, or character left arguments.

It took a few weeks (certainly long beyond that skiing trip) to arrive at the end of the Dictionary. But it was worth every minute.

With practice, the DoJ becomes more and more accessible. The more you became familiar with all those primitives, the less page turning you'll have to do.

Fortunately, things have become easier in 2004:

Highly recommended: JfC

These days, Henry Rich's marvelous "J for C Programmers" exists and is much easier to read. Henry really understands how J works and tells you everything at a gently pace -- and without omitting anything.

You don't have to be a C programmer. Any prior programming experience will be good enough, and I expect that even without any other programming language on your back, you will do fine with this book.

A word of caution

Sometimes I found that authors in the "J is easy!" camp had not fully understood J themselves before they enthusiastically set out to teach others. These authors were certainly well meaning and put lots of efforts into the documentation they provide, but --very sadly for all parties involved: if it's wrong, it's wrong.

I must admit that I am sceptical about the NuVoc community effort. The project's goal is laudable: providing a more accessible version of the DoJ, using more examples, direct links to the relevant J concepts, and to related primitives. However, all too often I find descriptions or wordings I cannot be happy with.

As things I stand (2017), I do not recommend the NuVoc as learning or reference material.

Good Tutorials in Disguise

If you have learned the J foundations but are still a beginner, you can find good examples for elegant J in these two places not really advertising as "learner's books" -- but they are:

1. The "J Phrases" collection.

   It doesn't say so anywhere, many of the J phrases are developed in a tutorial fashion, often teaching variations of expressions or building more complex expressions from simple base parts.

   Most phrases are just two or three primitives bolted together, already yielding something useful.

2. Cliff Reiter's "Fractals, Visualization and J"

   I like this book for its very tasteful application / use of J. The J expressions all have decent size and yet they solve real problems ("computing images"). You won't find those endless one-liners they throw at you on the mailing lists.

Closing summary

Out of the "easy intros", I can recommend Eric Iverson's "J Primer". When Eric wrote this intro, he was well aware that a short, limited overview cannot properly teach everything about J, so he doesn't even try. But what is in there is reliably correct and not misleading. It is a decent intro.

For some initial phase, you will be able to avoid the two rigorous texts, DoJ and JfC, and have fun dabbling around J as good as you can.

You will notice when things too often fail to work out as intended. Then, do not switch to another "easy" intro but bite the bullet.

For most coders advancing on their own, "J for C programmers" will be the easiest text. It will guide you to ultimately deal with the DoJ yourself.

When I give J courses (for paying clients or pro-bono for conferences), I always make it my goal to "DoJ-enable" the attendents. I also routinely refer J newbies on the #jsoftware IRC channel directly to DoJ entries. With a little help, the DoJ sections/entries can be read by beginners, too.