User:Ian Clark/Discussion
This page is for documenting discussion on the Wiki vocabulary project that arose out of this forum thread.
Page names for Vocabulary entries
Current Dictionary of J (DoJ) page names don't appear to be very descriptive although (as for most things in J) there is a system to them. It would be simplest and clearest if the actual symbols could be used for the page names, unfortunately there are a number of symbols that won't display correctly in URLs on the wiki.
Option 1
Dan suggested using names for the base symbols followed by the inflection symbols as required e.g.
Symbol Option1 Option2 CurrentDoJPageName $ dollar ShapeOfShape d210 $. dollar. Sparse d211 $: dollar: SelfReference d212 & ampersand BondCompose d630n &. ampersand. UnderDual d631 &.: ampersand.: UnderDual d631c L. L. LevelOf dlcapdot p.. p.. PolyDerivPolyIntegral dpdotdot
The question is whether we can agree on a set of names to use for the base symbols that is clearer/easier to use/more expressive than the current dictionary page names. Note that the main place these names will be displayed is at the top of the wiki page in the position that "Discussion" appears for the page you are now reading.
- For this reason, I do not think we have to worry excessively about selecting a poor scheme. -- Dan Bron <<DateTime(2010-01-26T19:59:20-0300)>>
Here are some suggestions for discussion. Please add alternative suggestions if desired. The first column represents the current page names. The 2nd column are names from Wikipedia<<FootNote(used the page names linked to from each of the symbols on WikiPedia:Ascii)>>. The third column is from the The Red Book<<FootNote(JForum:programming/2010-February/018210)>>. The fourth column are some of the HTML entities defined for the ASCII character set, however there doesn't seem to be complete coverage.
Symbol Current Wikipedia Postscript W3 Others
= equals equalssign equal
< lessthan lessthansign less lt
> greaterthan greaterthansign greater gt
_ underscore underscore underscore uscore
+ plus plussign plus
* star asterisk asterisk
- minus hyphenminus hyphen minus
% percent percentsign percent
^ caret caret asciicircum hat
$ dollar dollarsign dollar
~ tilde tilde asciitilde
| verticalbar verticalbar bar vbar
. dot fullstop period stop
: colon colon colon
, comma comma comma
; semicolon semicolon semicolon scolon
# hash numbersign numbersign pound
! exclamationmark exclamationmark exclam emark
/ slash slash slash fslash/forwardslash
\ backslash backslash backslash bslash
[ leftbracket bracket bracketleft lsqbr/leftsquarebracket
] rightbracket bracket bracketright rsqbr/rightsquarebracket
{ leftbrace bracket braceleft lclbr/leftcurlybracket
} rightbrace bracket braceright rclbr/rightcurlybracket
" doublequote quotationmark quotedbl quot quote/dquot
` backtick graveaccent grave tick/btick
@ at at at commercialat/asperand
& ampersand ampersand ampersand amp
? questionmark questionmark question qmark
* I generally prefer the shorter names (star, tick, amp) but as noted above, this will only affect URLs and the title at the very top of the page, so we do not need to optimize for brevity (it's not like anyone's going to be typing these things in). So it would be ok to use full glyph names.
- That way, no one can complain that e.g. they don't know what a qmark or a vbar is. One problem with that approach is it lends itself to CamelCase, which we very specifically want to avoid in this context (because using CamelCase names will lead to spaces in the page title, so we'd have, e.g. "Vertical Bar:"). For similar reasons, we can't use underscores in page titles.
- So that leaves us with, e.g. "verticalbar:", which we hope is readable even without visual parsing hints (or we come full circle back to "bar:" etc). -- Dan Bron <<DateTime(2010-01-26T19:59:20-0300)>>
I agree that it is better to use the longer clearer names. Interestingly re CamelCase I did some investigations and although I see spaces in the links to page names on the RecentChanges page, I don't seem to get them anywhere else (whether or not I've ticked the option to "Add spaces to displayed wiki names" in my Settings|Preferences. Probably better to go with the all lowercase versions though. -- Ric Sherlock <<DateTime(2010-01-27T13:37:23+1300)>>
- I have written a script to generate a complete set of page names based on the "PostScript" column above. See: Vocabulary/FormalPageNames. -- Ian Clark <<DateTime(2010-02-09T11:21:07Z)>>
Here are some names for other symbols used as punctuation in J, but which probably won't need their own page.
( leftparenthesis/leftparen ) rightparenthesis/rightparen ' singlequote/squote/squot
Option 2
One approach for page names would be to use the alphanumeric text of that vocabulary entry as the page name. In other words:
- I find the running together of the monadic and dyadic names distracting/confusing. For example my brain keeps trying to make sense of "Decrement Less". -- Ric Sherlock <<DateTime(2010-01-27T13:47:10+1300)>>
Consensus
Is there anyone opposed to the adoption of #Option1, or who feels strongly that we should use one of the other alternatives?
If not, I will clear up the test pages I created and rename the links on the Vocabulary page accordingly. Then we can start working on content for the pages! -- Ric Sherlock <<DateTime(2010-02-02T12:22:22+1300)>>
I have taken no response as implicit approval ;-) and made the above changes. -- Ric Sherlock <<DateTime(2010-02-03T16:54:26+1300)>>
Parts of Speech
Regarding parts of speech, I would like to separate nouns from "other". Specifically, I would like one color / legend item for nouns, and another for punctuation. The nouns are _ _. a. a: and the punctuation is =. =: NB.. For this reason, I would also prefer to change the word "primitive" to "word" (because punctuation are "words" in the J sense, but not primitives <<FootNote(Or maybe all single glyphs or inflected words are primitive, but a primitive can be punctuation (=. =: ' () if. for_xyz. NB., sometimes :, CR,LF etc) or a immutable name (+ a. 7: etc), as opposed to a user-defined name (myVerb GLOBAL_NOUN this_there_ member__obj etc). The main difference is that immutable names can be the referent of a user-defined name (as can other user-defined names), but punctuation cannot. That is, punctuation has no nameclass (but it does have a tokenclass or maybe wordclass). But the DoJ uses the English word "name" in many different places, so I suggest we stick with the word "word" until we sort this out. Let me mull on this.)>>). I would also like to see the table presented in ascending order of the part-of-speech hierarchy: nouns, verbs, adverbs, conjunctions, punctuation (to server as a reminder -- we will spell this out in detail somewhere).
Regarding the color scheme, I would like to see a sharper contrast in colors, though this of course will result more jarring presentation of the page (as opposed to the currently smooth and comforting, but hard to distinguish, pastel scheme). I might make verbs the brightest and easiest to distinguish (because verbs have primacy in the language), adverbs a related color but softer (because they tend to hide in the background), conjunctions a different, but still subtle color (maybe subtler even than adverbs), nouns again bright but contrasting with verbs, and punctuation hueless (because as gray is not a color, punctuation are not primitives, and also punctuation hides the most in a J sentence). Note this sharp-vs-subtle scale also mirrors the part-of-speech hierarchy and the way a sentence is read <<FootNote(Another option is to color the table the same way the J Windows Session Manager (jwdw) presents these words by default. The problem with that is that jwdw's default color scheme doesn't distinguish parts of speech specifically. Though we could change that...)>>.
I tried to effect these changes myself, but got lost in the complexity of editing the legend table. To that point, I would also like to normalize the color scheme using CSS, so the table is less daunting and easier to edit (and so we can change the color scheme more easily). -- Dan Bron <<DateTime(2010-01-26T12:00:40-0300)>>
Using classes instead of directly using background colors seems simple enough (http://moinmo.in/HelpOnTables), however, I do not know how to incorporate a stylesheet specific to this project. Raul Miller <<DateTime(2010-01-26T22:38:01Z)>>
The legend table has been simplified so it is easier to edit while we work out which components it should contain. AFAIK it is possible in MoinMoin to:
- use classes and a stylesheet that would be visible by all users by default, but would only be editable by the Server Admin.
- use classes and a user-editable stylesheet (hosted somewhere?) but by default it would not be visible to all users.
For just experiementing with different colours, it is probably easiest to copy the wiki source into an text editor, do a search & replace, copy it back and Preview the page (or use something like the It's All Text addon for Firefox to edit directly in your text editor). -- Ric Sherlock <<DateTime(2010-02-02T12:22:22+1300)>>
Skip Cave
Regarding the color scheme...The colors are pretty, but just like the original vocabulary, they require considerable previous knowledge of J to be even marginally useful. As I have argued previously, this reference-tutorial should be heavily biased towards the true first-time novice. Any attempt to include cryptic colors, words, or concepts without copious explanations, will cause more problems than good. This is particularly true for the page that may become the primary gateway for novices to approach the language.
The colors themselves may not be terribly off-putting, as the newbie may just ignore them. However, when the newbie looks up the color key and finds "verb" and "adverb", they will start wondering if they have stumbled into a beginning English class, rather than a programming language. The opening page of their explorations might not be the right place to lay the whole "J uses English parts-of-speech terminology instead of programing terms" paradigm on them.
if we do want to keep the colors, we will need hyperlinks from the key words "verb", "adverb", etc.to an explanation that will hopefully calm their shock and mitigate their skepticism at this new terminology for concepts that they feel they already have more familiar terms for (or at least so they think). That text could be a challenge to craft. Or, we could just use more familiar programming terms such as functions, variables, constants, etc. to minimize the initial weirdness barrier, and introduce those terms later. Of course, "later" is a difficult concept for a random-access tutorial. .
I believe that this initial experience will be a critical issue to get right for the training-wheels vocabulary. If there is too much weirdness on the introduction, the newbie won't keep going. The whole point of the reference-tutorial is to lower the slope of the learning curve for the toe-dipping novice who wants to just check out J to see what all the fuss is about.The fewer new concepts you have to introduce to gain understanding of a particular primitive or concept, the better. It could be argued that the whole parts-of-speech naming paradigm is one of the significant causes of the steep learning curve of J.
SkipCave <<DateTime(2010-02-03T18:55:20)>>
Monadic and Dyadic
Each vocabulary description page provides two different descriptions for the same symbol, without any explanation as to what that is all about. The astute newbie might figure out from the examples what is going on, but I wouldn't make that the only way to learn why there are two definitions for the same symbol. There should be at least some brief explanatory text with each description saying "this requires a right-argument-only" or "this requires both left-and-right-arguments", so that a novice could easily grasp why their are two entries. I realize that the table at the left of each description defines whether the definition is monadic or dyadic, but the terms monadic and dyadic are not widely understood. The terms monadic and dyadic could be used if they were preceded with the brief explanations as above, and then with hyperlinked to detailed explanations.
Something like:
Ceiling - this requires only a right argument (Monadic)
It would be best if we could come up with a few words that describe monadic and dyadic concepts which could be placed right at the point of encounter on each vocabulary page. That would have the best chance of getting the point across to the novice reader. We could also put the words monadic and dyadic at the end of the brief description, so that they would learn the appropriate descriptive word, with hyperlinks to the more detailed description. In that way, the newbie gets the basic concept of monadic/dyadic in a few words, then they see what J-ers call it (monadic or dyadic), and then they can hyperlink through that word to a more detailed discussion of the whole concept if they like. SkipCave <<DateTime(2010-02-03T19:10:20)>>
assumptions about our audience
(I prefer to cite/link references I make, but I don't have the energy to do that right now. Will later, if I get time).
Recent discussions on the Forums have revolved around our audience and what level of context to provide in Vocabulary pages. Some have suggested making "no" assumptions, some have suggested targetting middle schoolers who have interest in the humanities but none in computer programming or mathematics, I raised the idea of abandoning the "natural language" metaphor, etc. I would like to come to a decision on this matter, because we cannot make progress otherwise.
We can each describe our stances and make our cases in subsections, as follows.
Dan Bron
I advocate retaining our current "natural language" metaphor, for several reasons:
1. We need some core assumptions. We simply cannot assume "nothing" about our audience, and even if we could, we would be abandoning the concept of a "reference". If we do not have a framework Vocab entries can rely upon, we will end up reprising all of J in every Vocabulary entry.
1. I think we should be pragmatic about where our audience is going to come from "in real life". 1. We already have a "purist" Dictionary; what we need is a practical Dictionary. 1. It is not going to be 11 year-olds with no interest in computers, and even if we could lock some of those in a room with nothing but bread, water, and J, they would not become part of our consituency or community. It is not possible to talk about the humanities in J without reframing them in an analytical way (that is, as programs or as mathematics).
1. Using J to teach middle-school mathematics is a noble idea and was one of Ken's hopes and aims. But so far, it has born no fruit. And I think we cannot satisfy both of these constituencies (children and adults) simultaneously. I also think adults are more likely to do self-directed evaluations and education, whereas children are more likely to have guidance over early hurdles (and experienced teachers who can design curricula and supplementary [to the Dictionary] class materials)
1. Realistically, our audience is going to be programmers or at least the kinds of people who could become programmers (this includes anyone who can think analytically, including mathematicians).
1. I think it is more important to focus on the dedicated newbie than on the dilettante from RosettaCode who just clicked on a primitive and wants to know all about it without "learning a lot of other stuff". It is impossible to fully understand a J primitive without "learning a lot of other stuff". Besides, the dedicated newbie is going to be spending a lot more time in our Dictionary than the dilettante (by definition of "dilettante"). 1. That said, we should have clear pointers to all that other stuff. Hyperlink everything.
1. Since we need a core metaphor, I suggest we stick with "J as a natural language": 1. Retains backwards compatibility with existing materials and points of view (so J veterans can continue to communicate with newbies). 1. Is a nice balance between "need for analytical thought" and "doesn't need to know math or programming before engaging with J". 1. Was designed by a genius (or geniuses).
-- Dan Bron <<DateTime(2010-02-08T22:44:25-0300)>>
Skip Cave
I agree that the target audience should not be 11-year-olds or dilettantes. However, there will still be experienced programmers who wants to understand J who will be immediately put off by J's propensity to invent words for concepts for which they feel they already have perfectly good words. If there is a word or phrase that is not in common usage in the programming world, there should be hyperlinked explanations. This isn't for the 11-year-old. This is for the experienced programmer who doesn't know what the heck we are talking about.
- This is a good point; we may be putting off exactly programmers with our terminology. And we need to alleviate this hackle-raising immediately (at the source?).
- Perhaps we can use parenthetical statements to this effect? "... a noun (data arranged in a [rectilinear] array) ... ", "... a verb (function) ...".
- But this gets unwieldy, fast. Instead of trying to clarify these words every place they're used, I think we should just hyperlink them and describe them in multiple different ways (accessible to different kinds of people with different backgrounds and different expectations) in their own definitions.
- J is sufficiently different from "mainstream" languages that a programmer coming from that world has some "unlearning" to do. For example, in C, + is an "operator", but it is certainly not in J; and C doesn't really have an equivalent to what we call "operators" (e.g. /). So using new terminology may avoid improper expectations or associations, and smooth the transition; it also serves to alert the reader that he's entering new territory and should pay attention.
- And using the natural language metaphor allows us to do all this while staying fairly familiar: whether in C or in J, no one can dispute that + is a verb ("add", "sum").
- Entirely avoiding the natural language metaphor will leave the reader out at sea if he trys to use other resources (e.g. the official DoJ, the primer, J4C, the Forums...). We should introduce it early (but to your point, make it non-scary immediately).
-- Dan Bron <<DateTime(2010-02-09T17:23:26-0300)>>
I think that there are more improvements we can make to the vocabulary page templates to foster the aforementioned understanding, though I don't think that should hold up authoring more content. At the worst, we can hand-edit the pages with the final template design when we get it the way we want it.
I have modified the Vocabulary/greaterthan. (Ceiling/Max ) vocabulary description page with my idea of graphical help symbols. I had the following rationale for this modification:
1) The Monadic and Dyadic specification should be right where those definitions start, instead of in a "blue box" in the corner. It makes the meaning much clearer IMHO. What the reader needs to know should always be in-line in the text, so they run right into it (or stumble right over it, as the case may be) as they read.
- Specific to "Monadic" and "Dyadic", if we assume our core audience is programmers, I think we could assist the transition with relatively minor hints, as in
== + == === monad (unary) === === dyad (binary) ===
-- Dan Bron <<DateTime(2010-02-09T17:32:48-0300)>>
I'm not sure I understand exactly what you're proposing Dan. Perhaps an example page using the idea would clarify? In my case I'm sure the terms unary & binary would not have helped!! :-)
-- Ric Sherlock <<DateTime(2010-02-10T17:08:25+1300)>>
2) The exclamation point graphic points up a "this is important to know" concept. such as valence. We will need a key note, likely on the first page, that explains to the novice that the exclaim graphic indicates an important concept that they should explore before going too much further.
- I think hyperlinks on unfamiliar words ("valence?!", "dyadic?!") adequately serve this purpose, and that exclamation icons should be reserved for rare but important notes (e.g. 1!:55, 2!:55), otherwise the icon loses its value (starts to get ignored). I say this because maybe the
Dyad will be helpful when a reader lands on a J Voc page for the very first time, but then incrementally loses value for every subsequent J Voc page . - That is, these (intentionally) visually intrusive marks may provide value to the dilletant, but may frustrate a non-dilletant who already found out what a "dyad" is, and wants to know what's really important.
- I feel that a hyperlink on a unknown word (with perhaps some brief parenthetical remark) is a sufficient and universally acknowledged indicator that it's important pre-requisite topic. This is how Wikipedia works, for example.
-- Dan Bron <<DateTime(2010-02-09T17:23:26-0300)>>
Dan's points and those that Ian makes in his recent forum post jive with the feeling I've got on this. The red exclamation mark is "scary" (and probably intrusive). If we are to use an icon it should preferably be a widely recognized one e.g. {i} . Writing down my vision of our target audience helped clarify in my mind that "pandering" too much to the reader isn't necessary. I'm thinking that hyperlinked words, perhaps with the use of mouse-over text pop-ups, might be the way to go. If we wanted to, we could use a CSS class to specially mark links that have associated pop-ups.
-- Ric Sherlock <<DateTime(2010-02-10T17:08:25+1300)>>
3) I discovered that moin moin graphics can have "alternate text" which pops up when you hover the mouse over the graphic. That's a perfect place to put hints and brief help text for the novice, without intruding on the more experienced users. Try it out on the exclaim graphic on the >. page, and see what you think.
4) The words Monadic and Dyadic are still hyperlinked to the Valence description/tutorial pages, so if the pop-up hint isn't enough, they can take the link to the detailed description/tutorial. This may allow us to shrink the size of the "blue box" in the corner to just specifying Parts of Speech and Rank..
I would really like to have had both the hyperlinked text (Monadic/Dyadic) and the exclaim graphic to have the pop-up text, but I haven't found how to do that as yet. Similarly, I would like the graphic to hyperlink to the valence pages just like the hyperlinked text but again, I haven't discovered the moin moin code for that either.
This syntax should work display text|title=popup text. For example Ceiling|title=Monadic form of >.
-- Ric Sherlock <<DateTime(2010-02-10T17:08:25+1300)>>
Finally, I would also liked to have the whole hyperlinked text and the graphic just to the right of the "Ceiling" and "Larger of (Max)" titles, but moin moin doesn't seem to allow that.
--SkipCave <<DateTime(2010-02-09T11:03:20)>>
Ric Sherlock
Here's my "vision" of the target audience that this project will attempt to reach:
A newcomer to J has been "hooked" enough to try and write some code. They have a specific task in mind and think they know which primitive will help. They look up the primitive in the wiki Vocabulary to see if they are right and if so how to use the primitive. Their background isn't necessarily programming, but they probably have some previous experience with programming languages.
I like the distinction that someone (Dan?) made earlier to the effect that the Vocubulary section of the JoD is a formal reference for the primitives while this project will be a practical reference. It will try to make it easy for someone, who has some self-motivation, to use and understand a J primitive as part of their "learning J journey".
I pretty much agree with the points Dan makes about using the natural language metaphor - there are too many advantages to drop it and that they outweigh the disadvantages.
footnotes
- That is, these (intentionally) visually intrusive marks may provide value to the dilletant, but may frustrate a non-dilletant who already found out what a "dyad" is, and wants to know what's really important.
- I feel that a hyperlink on a unknown word (with perhaps some brief parenthetical remark) is a sufficient and universally acknowledged indicator that it's important pre-requisite topic. This is how Wikipedia works, for example.
-- Dan Bron <<DateTime(2010-02-09T17:23:26-0300)>>
Dan's points and those that Ian makes in his recent forum post jive with the feeling I've got on this. The red exclamation mark is "scary" (and probably intrusive). If we are to use an icon it should preferably be a widely recognized one e.g. {i} . Writing down my vision of our target audience helped clarify in my mind that "pandering" too much to the reader isn't necessary. I'm thinking that hyperlinked words, perhaps with the use of mouse-over text pop-ups, might be the way to go. If we wanted to, we could use a CSS class to specially mark links that have associated pop-ups.
-- Ric Sherlock <<DateTime(2010-02-10T17:08:25+1300)>>
3) I discovered that moin moin graphics can have "alternate text" which pops up when you hover the mouse over the graphic. That's a perfect place to put hints and brief help text for the novice, without intruding on the more experienced users. Try it out on the exclaim graphic on the >. page, and see what you think.
4) The words Monadic and Dyadic are still hyperlinked to the Valence description/tutorial pages, so if the pop-up hint isn't enough, they can take the link to the detailed description/tutorial. This may allow us to shrink the size of the "blue box" in the corner to just specifying Parts of Speech and Rank..
I would really like to have had both the hyperlinked text (Monadic/Dyadic) and the exclaim graphic to have the pop-up text, but I haven't found how to do that as yet. Similarly, I would like the graphic to hyperlink to the valence pages just like the hyperlinked text but again, I haven't discovered the moin moin code for that either.
This syntax should work display text|title=popup text. For example Ceiling|title=Monadic form of >.
-- Ric Sherlock <<DateTime(2010-02-10T17:08:25+1300)>>
Finally, I would also liked to have the whole hyperlinked text and the graphic just to the right of the "Ceiling" and "Larger of (Max)" titles, but moin moin doesn't seem to allow that.
--SkipCave <<DateTime(2010-02-09T11:03:20)>>
Ric Sherlock
Here's my "vision" of the target audience that this project will attempt to reach:
A newcomer to J has been "hooked" enough to try and write some code. They have a specific task in mind and think they know which primitive will help. They look up the primitive in the wiki Vocabulary to see if they are right and if so how to use the primitive. Their background isn't necessarily programming, but they probably have some previous experience with programming languages.
I like the distinction that someone (Dan?) made earlier to the effect that the Vocubulary section of the JoD is a formal reference for the primitives while this project will be a practical reference. It will try to make it easy for someone, who has some self-motivation, to use and understand a J primitive as part of their "learning J journey".
I pretty much agree with the points Dan makes about using the natural language metaphor - there are too many advantages to drop it and that they outweigh the disadvantages.