I believe that the Accessible Dictionary should try to solve two problems. The two problems are:
1) Create a reference document. A reference document is intended to be accessed randomly. A newbie or other user typically will access this reference document to find out about a specific symbol or concept. They do not want to read a full linear tutorial on J. They just want to go to the particular section in the document on the symbol or concept that they want to understand, However, they will expect that any unfamiliar concepts that are encountered during the explanation of that specific symbol or concept will also be explained, right in the text (or through a hyperlink). So when they are through reading, they will have a thorough understanding of that symbol or concept. They probably will still have a long way to go to learn all of J at that point, but at least they should know most of what there is about that one topic. 2) The second problem is the fact the the document needs to be a tutorial. Not a linear tutorial like "J for C Programmers" or "Learning J", but a tutorial that is inteneded for random access. Each topic should not be thought of as a "definition" as that implies a formal approach, which this random-access tutorial should most certainly not be. Each topic needs to be a stand-alone document, thoroughly covering the concept it purports to explain. Any unusual words or phrases used in the explanation should be hyperlinked to the appropriate explanation of that word or phrase. So the most descriptive name for this thing we propose to build, will be a "reference-tutorial" - a reference to point out the random access concept, and a tutorial to point out its illustrative and expository style, with descriptions, explanations, examples, puzzles, etc. (As opposed to a "definition" such as provided by the current Vocabulary) So that is my proposal for the name - the "J Reference-Tutorial". I believe that best describes what the intention of the document is. Skip Cave Oleg Kobchenko wrote: > "J Manual" has the following problems: > > - there is already a User Manual, which rightfully describes the system > omitting the language > > - the scope of Dictionary is "language reference" in exo-lingo, > not the system as a whole. So that could be one candidate. > > - Looking at Python, as an example of simplicity and adoption, > they have a less formal but rather complete introduction, > called "Tutorial". Its goals are more substantial than Primer. > > > So a good approach in bringing J to the massed, it not to try to > reinvent the Training Wheels, but clime on the shoulders of those > giants and shamelessly imitate, or even better, steal. > > > _____ > * exo- is a prefix for "external systems" outside of J. > > > > >> From: Dan Bron <j...@bron.us> >> >> Oleg wrote: >> >>> Both simplicity of language and clarity of narration may require >>> constant attention. >>> >> Agreed [1]. >> >> >>> I would think, Simple English Wikipedia >>> http://simple.wikipedia.org/wiki/Main_Page >>> >> I'm not sure we need to swing the pendulum that far in the other direction, >> nor assume our audience is as unfamiliar with English as it is with J. I >> personally picture a J newbie as intelligent but ignorant (of J), and I >> would pursue my writing under those assumptions. >> >> >>> The name "Wordbook" may be appropriate. >>> It is a synonym for "dictionary", yet conveys >>> simplicity, smaller scope, less intimidation. >>> >> Here is an example: if I were new to J, and someone directed me to "look >> that up in the wordbook", I might feel condescended to. I would not feel >> condescended to if I were directed to the "dictionary" or the "vocabulary" >> (which is more precisely what "wordbook" connotes to me, in contrast to >> "dictionary"), though I would have a separate set of questions regarding >> those names. >> >> Reflecting on that (the set of questions I would ask), it occurs to me that >> the word we're seeking is right under our nose: The J Manual. "Look that >> up in the manual" seems just about right. Unfortunately for me, I take >> great interest in J-as-a-language, and value how the current DoJ presents it >> as such, but I don't feel the "language analogy" presentation is appropriate >> to a "manual" (as opposed to a dictionary). >> >> So now we're at the fuzzy border between form and content [2], and we must >> consider how to cross it. We actually get a lot of complaints regarding the >> presentation of J as a (human) language; is this the time to abandon (or >> tune down, or twist) that analogy? The question again hinges on our >> intended audience. Pragmatically speaking, most newcomers to our language >> will come from other (though perhaps exotic) programming languages, not as >> the tabula rasa the current DoJ targets. So shall we target that pragmatic >> audience, and write our manual as other manuals are written [3]? >> >> Or does that lose the value of a differentiated language in the first place? >> Would abandoning the human-language analogy be to lose one of our tools of >> thought? I don't know (and I would be personally sorry to lose the >> analogy), but I thought I'd raise the question. >> >> Especially in light of Don Guinn's comments: >> >> >>> A section in help called "HowTo". This would be a >>> list of words and phrases used in other languages like FORTRAN, C, >>> etc. >>> >> I agree this is a worthwhile pursuit, but it is different from a >> "dictionary" (in the monolingual sense), because there will be no one-to-one >> correspondence between J and these other languages. We could call it >> "HowTo", or use another term such as "the J-FORTRAN dictionary" or perhaps >> just beef up our current (and aptly named) "phrase book". The NYCJUG has >> such a project under consideration (taking VB's index and reproducing it for >> the J market). >> >> For concepts that DO map one-to-one from English or other computer languages >> onto J primitives, I like this idea: >> >> >>> { Index, Subscript Similar to subscripting in other programming >>> >> languages >> >>> # Copy Pick items based on a mask >>> /. Key Group items based on a key >>> {. Take Take beginning items >>> }. Drop Drop beginning items >>> >> and would lobby to include it as another "tab" along the lines I sketched at >> the bottom of [4]. >> >> -Dan >> >> [1] But again, I would've been happy with an internal name for the project, >> a name for "us", not a name for "them". And so simplicity would be >> less >> of an obstacle. >> >> [2] "Content is just fancy form." -- Douglas Hofstadter >> >> [3] And how are other manuals written. In particular, I find Dyalog's >> manual pretty accessible, but then I came to it knowing J, so I was already >> "booted up", as it were. Does K manual receive much criticism or praise? >> What about other "weird languages"? >> >> [4] http://www.jsoftware.com/pipermail/programming/2010-January/017993.html >> >> >> >> ---------------------------------------------------------------------- >> For information about J forums see http://www.jsoftware.com/forums.htm >> > > > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > > > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
