This page is for documenting discussion on the Wiki vocabulary project that arose out of this forum thread.

Contents

  1. Page names for Vocabulary entries
    1. Option 1
    2. Option 2
    3. Consensus
  2. Parts of Speech
    1. Skip Cave
  3. Monadic and Dyadic
  4. assumptions about our audience
    1. Dan Bron
    2. Skip Cave
    3. RicSherlock
  5. footnotes

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.

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 Wikipedia1. The third column is from the The Red Book2. 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

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:

=

Self-Classify • Equal

=.

Is (Local)

=:

Is (Global)

<

Box • Less Than

<.

Floor • Lesser Of (Min)

<:

Decrement • Less Or Equal

>

Open • Larger Than

>.

Ceiling • Larger of (Max)

>:

Increment • Larger Or Equal

_

Negative Sign / Infinity

_.

Indeterminate

_:

Infinity

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! -- RicSherlock 2010-02-01 23:22:22

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 3). 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 4.

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). -- DanBron 2010-01-26 15:00:40

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 2010-02-03 18: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 2010-02-03 19: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.
  2. 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.
    2. 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)
    3. 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).

  3. 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.
  4. 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).
    2. Is a nice balance between "need for analytical thought" and "doesn't need to know math or programming before engaging with J".
    3. Was designed by a genius (or geniuses).

-- DanBron 2010-02-09 01:44:25

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.

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.

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.

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.

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 2010-02-09 11:03:20

RicSherlock

Here's my "vision" of the target audience that this project will attempt to reach:

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

  1. used the page names linked to from each of the symbols on Ascii (1)

  2. programming/2010-February/018210 (2)

  3. 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. (3)

  4. 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... (4)

Vocabulary/Discussion (last edited 2010-02-10 04:08:25 by RicSherlock)