JbyPointAndClick

J By Point And Click

The Lab for learning J visually

J By Point And Click is a lab for learning J. What's special about it is the visual interface: the term window, edit window, Debug window, Dissect window and the user's browser are all in simultaneous use. The Dissect window is annotated with links to discussion, and the user is expected to click around as needed to become familiar with J.

• The term window has the lab text
• The edit window shows the script being executed
• The debug window shows line-by-line progress through the script
• The dissect window gives the detail on each line before it is executed
• The dissect window is hyperlinked so that the user can click around and bring up explanatory pages in their browser

Each chapter discusses a single program, with line-by-line detail.

J By Point And Click needs material. All users of J are encouraged to submit chapters.

What You Need

• J8.04 or later
  • Make sure you have the latest IDE! Follow the instructions here.

Note that you must go to the Package Manager and make sure the base library and the addon ide/qt is up to date.

• The addons:
  • debug/dissect
  • labs/labs
  • graphics/plot

After you have the addons, go to Help|Labs... to run the lab. Press CTRL-J in any window to advance the lab.

Founding Ideas

• The target user is someone who is bright and would like to learn J, probably with programming experience in scalar languages.
• The main thing is to choose a practical topic. We want the user to see the topic as worthwhile, to think about how they would do it in their favorite language, and then to see the elegance of the J solution. The harder the code is, the farther back it will go into the Lab.
• The user has the responsibility of clicking around and figuring out what is going on in each line.
• The lab writer's job is to make sure that each line of code is commented, and that the dissected version of the line has proper titles and links to explanatory pages.
• The text in the Lab page should be short. Detailed explanations of J should be in NuVoc; if you find NuVoc deficient, improve it or ask someone else to. By improving NuVoc the discussion will benefit all J users.
• Don't write tacit code. It will overwhelm a beginner.
• Don't try to write the smallest possible code. If you want to show how short the J solution can be, add one page at the end of the chapter showing the 'expert version' of the code, but don't try to explain it.
• Put an NB. comment on every line.

Script markup

Look at the lab for examples of script markup. The lab loads and uses jpcfmt.ijs (in ~addons/labs/labs/core) which describes the markup language.

The idea is that you start with a fully commented script, and then add tags which are lines beginning with NB.~

The tags indicate:

• where debug stops should be placed
• titles for the dissect display
• links to be shown in the dissect display
• options to dissect, such as size of noun blocks and level of checking
• which lines should not be automatically dissected

Contributions

J By Point And Click needs contributions from the J community. Please write a chapter and either add it to the lab or send it to Henry Rich for inclusion. Your name may appear on the first section of the chapter, if you like.

Two kinds of chapters are needed:

Examples

An example is a J program to perform a stated task. The chapter should:

• describe the task
• load the annotated and marked-up code to perform the task
• step through the program line by line. There should be one Lab section for each time the debugger stops and shows a Dissect screen. Each line of the program should have explanatory commentary in the script, plus titles and links for the Dissect window for the line.
• The lab should explain only features that the user is unlikely to guess on their own, and should refer to Web resources as much as possible.

Exercises

An exercise is like an example, except that user is encouraged to write the code to perform the task. Each section of the exercise prompts the user to write a bit of code. At the end, a working solution is shown, just as for an example.

Functions the lab can use

jpcfmt.ijs contains the following functions:

Name	Function	Arguments
opendebscript	apply markup and load script, stops, etc.	x is a string giving the name to use for the script. y is the script with markup
debugstep''	run stepover in the debugger
debugstop''	clear the debugger
debugrun''	run the program
debugrunstop''	run the program, then clear the debugger
debugchangestops	enable/disable stops	y is the class(es) from stop markup commands, either a string or a (list of) boxed strings x is 0 to clear stops, 1 to set stops, 2 to toggle stops.

A sentence being debugged displays its final result when debugrun or debugrunstop causes the verb to run to completion. debugstep does not have this effect, because the sentence is running under the Lab Manager and the debugger will continue stepping through the Lab Manager.

Other scripts can be added as needed.