Revision 1 as of 2007-02-20 04:29:13
converted to 1.6 markup
|No differences found!|
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: firstname.lastname@example.org