"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
