JforBeginnersCriticisms

From J Wiki
Jump to navigation Jump to search

The following is a compilation of an e-mail thread from the J Forum wherein various people criticize some shortcomings of the current material designed to introduce people to J.

It is presented here with the hope that it will provide a road-map for overcoming the objections insofar as they are valid. We start with a well-considered reply to some objections raised in earlier in the thread.

Date:	Wed, 6 Apr 2005 16:44:35 -0700
From:	"Edward Cherlin" <cherlin@PACBELL.NET>
Subject:	[Jforum] Documentation (was Re: [Jforum] J for Beginner)s
To:	JFORUM@PEACH.EASE.LSOFT.COM

On Wednesday 06 April 2005 10:24, Roy A. Crabtree wrote:

> > DOCUMENTATION
> >
> > The online documentation is admirable for regular users but
> > unsuited to beginners.  I feel special documentation is
> > needed for beginners in which simple (and necessarily
> > incomplete) descriptions and examples are given; these could
> > be linked to the more complete descriptions if the beginner
> > wants to go further.

Agreed. The beginner also needs to be guided through a sequence
of ideas and language facilities in an order that limits the
amount of new information to be absorbed at any one moment.

> > The main document I feel is the Vocabulary.  This is almost
> > completely daunting for beginners.  For experienced users
> > the laconic descriptions and examples are very appropriate,
> > but for others ....

Perhaps Garry Helzer's An Encyclopedia of APL can serve as a
model.

> > Certainly, the information is
> > somewhere in the primers, but ploughing through them is hard
> > work for beginners and often the description is once again
> > pitched at the somewhat experienced user level.

Not just the experienced user, but the somewhat sophisticated
mathematician.

> > A related
> > facility I have suggested in the Forum some time ago would
> > be an  a f.2  that would return a simple explanation of  a
> > which could be from the Beginner's Vocabulary in case of a
> > primitive function, but which could be much else beyond.

I would suggest a more conventional form of context-sensitive
help.

> > Another document I feel would be very useful for beginners
> > would be a simple guide to the utility scripts that come
> > with the interpreter.  There may be one somewhere (where,
> > please?) but when I looked for it a few years ago I had to
> > give up.

It would be useful to define a standard comment format in the
manner of Python or Javadoc for automatic processing.

> > Work on the online documentation has been discussed on the
> > Forum recently, but I feel work aimed at beginners should be
> > given priority.  The renaming of example functions could be
> > considered in this light.

If there were a GPL'ed version of J or some other form of Free
license, I would write some of this material myself. I would
then be able to use J in projects in Asia and Africa that depend
on Free Software, and make it part of a curriculum at computer
schools I am working with in several countries. Without access
to source code (beyond the outstanding 1992 "An Implementation
of J", available as far as I know only in print) for porting to
other architectures I cannot recommend J to these potential
users.

If we could work out a license for that much access to source
code, without permitting changes to the language, Debian would,
as far as I know, be willing to put a package into the non-free
section of its distribution. We might also be able to get Red
Hat, Mandrake, and other distributions to take on a Red Hat
package under the same restrictions. We would also need
permission to translate some of the existing documentation to
other languages.

--
Edward Cherlin
Generalist & activist--Linux, languages, literacy and more
"A knot! Oh, do let me help to undo it!"
--Alice in Wonderland
http://cherlin.blogspot.com

--------------------------------------------------------------------------
For information about the J Forum see http://www.jsoftware.com/j_forum.htm

The discussion then addresses some broader issues raised in the context of introducing new people to J, particularly in the context of a classroom. We again start in the midst of a discussion by looking at a reply to an extensive critique presented earlier.

Date:	Tue, 5 Apr 2005 11:51:45 -0400
From:	"Miller, Raul D" <rdmiller@USATODAY.COM>
Subject:	Re: [Jforum] J for Beginners
To:	JFORUM@PEACH.EASE.LSOFT.COM

neville holmes wrote:
[quite a bit of material which he obviously has thought about for quite
some time]

I'm going to try giving my perspective on the three big topics you've
introduced.  I'm going to just give some of these issues cursory
coverage, but maybe my different perspective will be useful.

> INTERPRETER CONTROL

Once you start dealing with J's ties to the rest of the system, this
becomes a much cruder issue.  Just messing around with wd and locales,
while debugging, can be enough to cause J to crash.

Personally, I try to have everything important saved in files, and I
rather routinely find myself restarting J.

This isn't ideal, but without some way of isolating the problems I'm
reluctant to try to report any of this as a bug in J.  It could just as
easily be a bug in some underlying library.

When I compare J to other environments, it's still pretty good.  (For
example, I'm going to have to repair/reinstall Visual Studio.Net today
because it's been having much worse problems.  Since I did this just a
few months ago, so I'm not sure if that will work.

> DOCUMENTATION

I agree that the documentation can be improved.

However, one of the more important thing for writing good documentation
is having a good understanding of your audience.  That's about as
important as having a good understanding of the material.

Anyways, if you see a specific need, you could (in principle at least)
write a draft of the appendix you're looking for yourself.  If there's
aspects you don't feel comfortable addressing, you could include short
notes about what it is you're trying to describe and ask for help in
fleshing it out.

Basically, this is to some degree a "the things you think are worth
putting effort into are the things that get done" issue.

> Another document I feel would be very useful for beginners
> would be a simple guide to the utility scripts that come with
> the interpreter.  There may be one somewhere (where, please?)
> but when I looked for it a few years ago I had to give up.

What I find very useful here is find and grep.  Every major platform has
find and grep (under windows, you get them with cygwin).  I very
frequently find myself doing:

cd /c/j<tab>
find */ -type f -name '*.i*' | xargs grep -il keyword_or_pattern

This changes the problem from knowing all the scripts to knowing
something specific about what you're looking for.

I sometimes also search the documentation (-name '*.h*'), but usually
looking for examples of what I'm trying to do works better.

My impression is that there's a lot of stuff that comes with J, some of
which is used regularly by many, some of which is used rarely or by only
a few.  The less used stuff is less well organized and more likely to be
buggy.

There's also documentation which more or less exactly fits what you're
asking for.  Look in system/extras/help/user/ for files with
script_*.htm names.  This stuff is actually linked into the J help
index, but coming at the stuff from a different perspective sometimes
helps you spot stuff that you might have been overlooking.  Like the
scripts themselves, some of this documentation is used more than others,
and the most used stuff tends to be in the best shape.

> TACIT FACILITIES
...
> The problem is this.  Teaching tacit definition of functions is quite
> straightforward, and the students have few problems, either with
> primitive operations or with trains.  But when it comes to defining
> their own operations tacitly, all hell breaks loose.

There are a number of concepts important for teaching tacit programming,
and it's a fairly abstract topic.

What I find useful here is grounding my efforts in concrete experience.

Using 13 : is very useful for ideas.  Using linear display (or sometimes
tree and parenthesis or even atomic) can be useful.  Working to make
sure I've a clear understanding of the arrays I'm working with, and the
math I'm trying to express, is invaluable.

On a grander scale, I like to draw an analogy between writing code and
breathing.  Generating code is like inhaling, cleaning up code is like
exhaling.  You need to do both.

Or, if that's too silly, a more precise analogy has to do with algebra:
intermediate results can be quite complicated.  You don't jump straight
to the final simplified form of an equation.  Instead, you work from
what you know and express the idea multiple times, before finally coming
on something relatively simple.

Another useful analogy, sometimes, is the "proof" analogy, where you go
about constructing a program much in the way you'd construct a proof
(start with what you know, and build on that).

But all of these are just analogies.

I think the biggest thing that helps is making "working code" a higher
priority than any particular mode for expressing the code.

> It seems to me that
>    a =: + u. |@-
> would be much much simpler than
>     a =:  1 :  '+ u. |@-'
> and much much easier for me to explain to my students.

An argument could be made that whenever script tokens (x. n. if. ...)
appear outside a string that there's some implicit context which is
always invoked.  Perhaps something like 13 : or perhaps something like
STSC's error handler:

let the user specify a function which is always run on lines where the
parser indicates a syntax error.  If the user handler runs successfully,
use that result as the result of executing the line in question.

Of course there's a caution here: what you generate in this fashion is
not standard J.  So you'll need to repackage stuff that relies on this
before it can be effectively communicated to a wider audience.  But this
is hardly a new problem.

--
Raul

The full critique referred to above is presented here for completeness.

Date:	Tue, 5 Apr 2005 15:17:32 +1000
From:	"neville holmes" <holmeswn@YAHOO.COM.AU>
Subject:	[Jforum] J for Beginners
To:	JFORUM@PEACH.EASE.LSOFT.COM

Some little time ago someone commented in this forum on
the need for J to attract new users.  For some years I have been
running an Honours subject "Computation and Functional
Programming" in which I use and impart, as far as I can, pure
tacit J.  I don't believe I have actually converted anyone to serious
use of J, though most students are impressed with what can be
done and admiring of how it is done.

Possibly this shortcoming is because I'm not myself a serious
user of J, and am ignorant of (and so don't teach) how J can
generate stand-alone applications, and how it can be linked to
other applications such as spreadsheets and databases, though
my students often seem able to work out how to use windows and
OpenGL.  Possibly a problem is my insistence on pure tacit J.

However, there are three issues mentioned recently in the Forum
that I feel make it harder for me in working with beginners.  Not
necessarily in order of importance, they relate to interpreter control,
documentation, and tacit facilities.  Please ask questions if the
explanations that follow are unclear.

INTERPRETER CONTROL

The interpreter too often hangs uninterruptably, except by the
three-fingered salute.  The latest example brought to my attention
is    <\~&2@#:"0   which hangs when presented with i.5x  for
example, but not for i.5 (under Linux).  This seems to be a bug
under J503a (in Windows the interpreter aborts), but the difficulty
for beginners is not that there are bugs, but that all too often they
key something in and the system hangs or aborts rather than
backs out gracefully, or allows interruption and restart.  This is what
they tell me.

I have them do some exact arithmetic, and often (they tell me, and
it has happened to me) the hour glass comes up, presumably
because the computation is a long one, and it doesn't allow
interruption.

There was a discussion about this problem earlier on the Forum,
but I am highlighting here that it is a particularly important issue
for beginners.


DOCUMENTATION

The online documentation is admirable for regular users but
unsuited to beginners.  I feel special documentation is needed
for beginners in which simple (and necessarily incomplete)
descriptions and examples are given; these could be linked
to the more complete descriptions if the beginner wants to
go further.

The main document I feel is the Vocabulary.  This is almost
completely daunting for beginners.  For experienced users
the laconic descriptions and examples are very appropriate,
but for others ....   Certainly, the information is somewhere in the
primers, but ploughing through them is hard work for beginners
and often the description is once again pitched at the somewhat
experienced user level.  A related facility I have suggested in
the Forum some time ago would be an  a f.2  that would return
a simple explanation of  a  which could be from the Beginner's
Vocabulary in case of a primitive function, but which could be
much else beyond.

Another document I feel would be very useful for beginners
would be a simple guide to the utility scripts that come with
the interpreter.  There may be one somewhere (where, please?)
but when I looked for it a few years ago I had to give up.

Work on the online documentation has been discussed on the
Forum recently, but I feel work aimed at beginners should be
given priority.  The renaming of example functions could be
considered in this light.


TACIT FACILITIES

This problem is specific to my teaching only of tacit J, which is
not only because that's what I like but because teaching explicit
J to Honours students would not be considered justifiable.  When
questioned, I justify my teaching as giving students experience
with something quite different, in particular from ML and Scheme
which they are fed as functional programming in undergraduate
units.

The problem is this.  Teaching tacit definition of functions is quite
straightforward, and the students have few problems, either with
primitive operations or with trains.  But when it comes to defining
their own operations tacitly, all hell breaks loose.  It is very
difficult
to do.  Some can be done, but they're not at all simple or easy to
understand, and there's no general way.  What I end up doing
(most reluctantly) is allowing them to use  1 : 'xxxx'  and the like.

It seems to me that
   a =: + u. |@-
would be much much simpler than
    a =:  1 :  '+ u. |@-'
and much much easier for me to explain to my students.
The method of definition should be quite plain from this simple
example, and quite intricate adverbs and conjunctions could be
easily and consistently defined.

When I suggested this earlier in the Forum it was criticised as
not being tacit.  My thought on this is that, though the operands
are indeed explicit in such expressions, the arguments are still
tacit.  An extension such as this would, it seems to me, be
compatible with present J except maybe in the peculiar capability
of giving values to pronouns such as u. and v. in the open.

My experience in teaching tacit J tells me that an extension (or is
it more a implification?) such as this would make learning much
easier for beginners like those in my classes.


Neville Holmes, P.O.Box 404, Mowbray 7248, Tasmania
Normal e-mail: neville.holmes@utas.edu.au