1 Date: Wed, 6 Apr 2005 16:44:35 -0700 2 From: "Edward Cherlin" <cherlin@PACBELL.NET> 3 Subject: [Jforum] Documentation (was Re: [Jforum] J for Beginner)s 4 To: JFORUM@PEACH.EASE.LSOFT.COM 5 6 On Wednesday 06 April 2005 10:24, Roy A. Crabtree wrote: 7 8 > > DOCUMENTATION 9 > > 10 > > The online documentation is admirable for regular users but 11 > > unsuited to beginners. I feel special documentation is 12 > > needed for beginners in which simple (and necessarily 13 > > incomplete) descriptions and examples are given; these could 14 > > be linked to the more complete descriptions if the beginner 15 > > wants to go further. 16 17 Agreed. The beginner also needs to be guided through a sequence 18 of ideas and language facilities in an order that limits the 19 amount of new information to be absorbed at any one moment. 20 21 > > The main document I feel is the Vocabulary. This is almost 22 > > completely daunting for beginners. For experienced users 23 > > the laconic descriptions and examples are very appropriate, 24 > > but for others .... 25 26 Perhaps Garry Helzer's An Encyclopedia of APL can serve as a 27 model. 28 29 > > Certainly, the information is 30 > > somewhere in the primers, but ploughing through them is hard 31 > > work for beginners and often the description is once again 32 > > pitched at the somewhat experienced user level. 33 34 Not just the experienced user, but the somewhat sophisticated 35 mathematician. 36 37 > > A related 38 > > facility I have suggested in the Forum some time ago would 39 > > be an a f.2 that would return a simple explanation of a 40 > > which could be from the Beginner's Vocabulary in case of a 41 > > primitive function, but which could be much else beyond. 42 43 I would suggest a more conventional form of context-sensitive 44 help. 45 46 > > Another document I feel would be very useful for beginners 47 > > would be a simple guide to the utility scripts that come 48 > > with the interpreter. There may be one somewhere (where, 49 > > please?) but when I looked for it a few years ago I had to 50 > > give up. 51 52 It would be useful to define a standard comment format in the 53 manner of Python or Javadoc for automatic processing. 54 55 > > Work on the online documentation has been discussed on the 56 > > Forum recently, but I feel work aimed at beginners should be 57 > > given priority. The renaming of example functions could be 58 > > considered in this light. 59 60 If there were a GPL'ed version of J or some other form of Free 61 license, I would write some of this material myself. I would 62 then be able to use J in projects in Asia and Africa that depend 63 on Free Software, and make it part of a curriculum at computer 64 schools I am working with in several countries. Without access 65 to source code (beyond the outstanding 1992 "An Implementation 66 of J", available as far as I know only in print) for porting to 67 other architectures I cannot recommend J to these potential 68 users. 69 70 If we could work out a license for that much access to source 71 code, without permitting changes to the language, Debian would, 72 as far as I know, be willing to put a package into the non-free 73 section of its distribution. We might also be able to get Red 74 Hat, Mandrake, and other distributions to take on a Red Hat 75 package under the same restrictions. We would also need 76 permission to translate some of the existing documentation to 77 other languages. 78 79 -- 80 Edward Cherlin 81 Generalist & activist--Linux, languages, literacy and more 82 "A knot! Oh, do let me help to undo it!" 83 --Alice in Wonderland 84 http://cherlin.blogspot.com 85 86 -------------------------------------------------------------------------- 87 For information about the J Forum see http://www.jsoftware.com/j_forum.htm 88 89 +.--------------------+. 90 91 Date: Tue, 5 Apr 2005 11:51:45 -0400 92 From: "Miller, Raul D" <rdmiller@USATODAY.COM> 93 Subject: Re: [Jforum] J for Beginners 94 To: JFORUM@PEACH.EASE.LSOFT.COM 95 96 neville holmes wrote: 97 [quite a bit of material which he obviously has thought about for quite 98 some time] 99 100 I'm going to try giving my perspective on the three big topics you've 101 introduced. I'm going to just give some of these issues cursory 102 coverage, but maybe my different perspective will be useful. 103 104 > INTERPRETER CONTROL 105 106 Once you start dealing with J's ties to the rest of the system, this 107 becomes a much cruder issue. Just messing around with wd and locales, 108 while debugging, can be enough to cause J to crash. 109 110 Personally, I try to have everything important saved in files, and I 111 rather routinely find myself restarting J. 112 113 This isn't ideal, but without some way of isolating the problems I'm 114 reluctant to try to report any of this as a bug in J. It could just as 115 easily be a bug in some underlying library. 116 117 When I compare J to other environments, it's still pretty good. (For 118 example, I'm going to have to repair/reinstall Visual Studio.Net today 119 because it's been having much worse problems. Since I did this just a 120 few months ago, so I'm not sure if that will work. 121 122 > DOCUMENTATION 123 124 I agree that the documentation can be improved. 125 126 However, one of the more important thing for writing good documentation 127 is having a good understanding of your audience. That's about as 128 important as having a good understanding of the material. 129 130 Anyways, if you see a specific need, you could (in principle at least) 131 write a draft of the appendix you're looking for yourself. If there's 132 aspects you don't feel comfortable addressing, you could include short 133 notes about what it is you're trying to describe and ask for help in 134 fleshing it out. 135 136 Basically, this is to some degree a "the things you think are worth 137 putting effort into are the things that get done" issue. 138 139 > Another document I feel would be very useful for beginners 140 > would be a simple guide to the utility scripts that come with 141 > the interpreter. There may be one somewhere (where, please?) 142 > but when I looked for it a few years ago I had to give up. 143 144 What I find very useful here is find and grep. Every major platform has 145 find and grep (under windows, you get them with cygwin). I very 146 frequently find myself doing: 147 148 cd /c/j<tab> 149 find */ -type f -name '*.i*' | xargs grep -il keyword_or_pattern 150 151 This changes the problem from knowing all the scripts to knowing 152 something specific about what you're looking for. 153 154 I sometimes also search the documentation (-name '*.h*'), but usually 155 looking for examples of what I'm trying to do works better. 156 157 My impression is that there's a lot of stuff that comes with J, some of 158 which is used regularly by many, some of which is used rarely or by only 159 a few. The less used stuff is less well organized and more likely to be 160 buggy. 161 162 There's also documentation which more or less exactly fits what you're 163 asking for. Look in system/extras/help/user/ for files with 164 script_*.htm names. This stuff is actually linked into the J help 165 index, but coming at the stuff from a different perspective sometimes 166 helps you spot stuff that you might have been overlooking. Like the 167 scripts themselves, some of this documentation is used more than others, 168 and the most used stuff tends to be in the best shape. 169 170 > TACIT FACILITIES 171 ... 172 > The problem is this. Teaching tacit definition of functions is quite 173 > straightforward, and the students have few problems, either with 174 > primitive operations or with trains. But when it comes to defining 175 > their own operations tacitly, all hell breaks loose. 176 177 There are a number of concepts important for teaching tacit programming, 178 and it's a fairly abstract topic. 179 180 What I find useful here is grounding my efforts in concrete experience. 181 182 Using 13: is very useful for ideas. Using linear display (or sometimes 183 tree and parenthesis or even atomic) can be useful. Working to make 184 sure I've a clear understanding of the arrays I'm working with, and the 185 math I'm trying to express, is invaluable. 186 187 On a grander scale, I like to draw an analogy between writing code and 188 breathing. Generating code is like inhaling, cleaning up code is like 189 exhaling. You need to do both. 190 191 Or, if that's too silly, a more precise analogy has to do with algebra: 192 intermediate results can be quite complicated. You don't jump straight 193 to the final simplified form of an equation. Instead, you work from 194 what you know and express the idea multiple times, before finally coming 195 on something relatively simple. 196 197 Another useful analogy, sometimes, is the "proof" analogy, where you go 198 about constructing a program much in the way you'd construct a proof 199 (start with what you know, and build on that). 200 201 But all of these are just analogies. 202 203 I think the biggest thing that helps is making "working code" a higher 204 priority than any particular mode for expressing the code. 205 206 > It seems to me that 207 > a =: + u. |@- 208 > would be much much simpler than 209 > a =: 1 : '+ u. |@-' 210 > and much much easier for me to explain to my students. 211 212 An argument could be made that whenever script tokens (x. n. if. ...) 213 appear outside a string that there's some implicit context which is 214 always invoked. Perhaps something like 13: or perhaps something like 215 STSC's error handler: 216 217 let the user specify a function which is always run on lines where the 218 parser indicates a syntax error. If the user handler runs successfully, 219 use that result as the result of executing the line in question. 220 221 Of course there's a caution here: what you generate in this fashion is 222 not standard J. So you'll need to repackage stuff that relies on this 223 before it can be effectively communicated to a wider audience. But this 224 is hardly a new problem. 225 226 -- 227 Raul 228 229 +.--------------------+. 230 231 Date: Tue, 5 Apr 2005 15:17:32 +1000 232 From: "neville holmes" <holmeswn@YAHOO.COM.AU> 233 Subject: [Jforum] J for Beginners 234 To: JFORUM@PEACH.EASE.LSOFT.COM 235 236 Some little time ago someone commented in this forum on 237 the need for J to attract new users. For some years I have been 238 running an Honours subject "Computation and Functional 239 Programming" in which I use and impart, as far as I can, pure 240 tacit J. I don't believe I have actually converted anyone to serious 241 use of J, though most students are impressed with what can be 242 done and admiring of how it is done. 243 244 Possibly this shortcoming is because I'm not myself a serious 245 user of J, and am ignorant of (and so don't teach) how J can 246 generate stand-alone applications, and how it can be linked to 247 other applications such as spreadsheets and databases, though 248 my students often seem able to work out how to use windows and 249 OpenGL. Possibly a problem is my insistence on pure tacit J. 250 251 However, there are three issues mentioned recently in the Forum 252 that I feel make it harder for me in working with beginners. Not 253 necessarily in order of importance, they relate to interpreter control, 254 documentation, and tacit facilities. Please ask questions if the 255 explanations that follow are unclear. 256 257 INTERPRETER CONTROL 258 259 The interpreter too often hangs uninterruptably, except by the 260 three-fingered salute. The latest example brought to my attention 261 is <\~&2@#:"0 which hangs when presented with i.5x for 262 example, but not for i.5 (under Linux). This seems to be a bug 263 under J503a (in Windows the interpreter aborts), but the difficulty 264 for beginners is not that there are bugs, but that all too often they 265 key something in and the system hangs or aborts rather than 266 backs out gracefully, or allows interruption and restart. This is what 267 they tell me. 268 269 I have them do some exact arithmetic, and often (they tell me, and 270 it has happened to me) the hour glass comes up, presumably 271 because the computation is a long one, and it doesn't allow 272 interruption. 273 274 There was a discussion about this problem earlier on the Forum, 275 but I am highlighting here that it is a particularly important issue 276 for beginners. 277 278 279 DOCUMENTATION 280 281 The online documentation is admirable for regular users but 282 unsuited to beginners. I feel special documentation is needed 283 for beginners in which simple (and necessarily incomplete) 284 descriptions and examples are given; these could be linked 285 to the more complete descriptions if the beginner wants to 286 go further. 287 288 The main document I feel is the Vocabulary. This is almost 289 completely daunting for beginners. For experienced users 290 the laconic descriptions and examples are very appropriate, 291 but for others .... Certainly, the information is somewhere in the 292 primers, but ploughing through them is hard work for beginners 293 and often the description is once again pitched at the somewhat 294 experienced user level. A related facility I have suggested in 295 the Forum some time ago would be an a f.2 that would return 296 a simple explanation of a which could be from the Beginner's 297 Vocabulary in case of a primitive function, but which could be 298 much else beyond. 299 300 Another document I feel would be very useful for beginners 301 would be a simple guide to the utility scripts that come with 302 the interpreter. There may be one somewhere (where, please?) 303 but when I looked for it a few years ago I had to give up. 304 305 Work on the online documentation has been discussed on the 306 Forum recently, but I feel work aimed at beginners should be 307 given priority. The renaming of example functions could be 308 considered in this light. 309 310 311 TACIT FACILITIES 312 313 This problem is specific to my teaching only of tacit J, which is 314 not only because that's what I like but because teaching explicit 315 J to Honours students would not be considered justifiable. When 316 questioned, I justify my teaching as giving students experience 317 with something quite different, in particular from ML and Scheme 318 which they are fed as functional programming in undergraduate 319 units. 320 321 The problem is this. Teaching tacit definition of functions is quite 322 straightforward, and the students have few problems, either with 323 primitive operations or with trains. But when it comes to defining 324 their own operations tacitly, all hell breaks loose. It is very 325 difficult 326 to do. Some can be done, but they're not at all simple or easy to 327 understand, and there's no general way. What I end up doing 328 (most reluctantly) is allowing them to use 1 : 'xxxx' and the like. 329 330 It seems to me that 331 a =: + u. |@- 332 would be much much simpler than 333 a =: 1 : '+ u. |@-' 334 and much much easier for me to explain to my students. 335 The method of definition should be quite plain from this simple 336 example, and quite intricate adverbs and conjunctions could be 337 easily and consistently defined. 338 339 When I suggested this earlier in the Forum it was criticised as 340 not being tacit. My thought on this is that, though the operands 341 are indeed explicit in such expressions, the arguments are still 342 tacit. An extension such as this would, it seems to me, be 343 compatible with present J except maybe in the peculiar capability 344 of giving values to pronouns such as u. and v. in the open. 345 346 My experience in teaching tacit J tells me that an extension (or is 347 it more a implification?) such as this would make learning much 348 easier for beginners like those in my classes. 349 350 351 Neville Holmes, P.O.Box 404, Mowbray 7248, Tasmania 352 Normal e-mail: email@example.com
Attached FilesTo refer to attachments on a page, use attachment:filename, as shown below in the list of files. Do NOT use the URL of the [get] link, since this is subject to change and can break easily.
- [get | view] (2007-02-20 06:36:44, 14.9 KB) [[attachment:JforBeginners-Criticisms.txt]]
- [get | view] (2007-02-20 06:37:59, 207.4 KB) [[attachment:briefJrefc_Burke.pdf]]
- [get | view] (2007-02-20 06:37:33, 87.3 KB) [[attachment:brief_ref03.pdf]]
- [get | view] (2007-02-20 06:38:52, 0.6 KB) [[attachment:nakedTruthRating.txt]]
- [get | view] (2007-02-20 06:38:31, 9.7 KB) [[attachment:rmseAdjustmentsSuggs.txt]]
You are not allowed to attach a file to this page.