I agree that it should be "relatively" easy to programmatically reformat a simple, consistent template, and I think we would be silly not to take you up on your generous offer Ian. I also agree with both you and Raul that the key thing is to make a start on content.
My opinion is still that it is more sensible for each primitive to have its own page, with multiple sections for each of the different contexts where it is used. That way the beginner doesn't have to identify the context to get to the correct place, and if they've incorrectly identified the context then they are already on the right page for the other contexts. Another place where the single page will have an advantage is for 'context-sensitive' help systems e.g. (Ctrl+F1) that will identify the primitive and take the user to the relevant help page. My suspicion is that while it is relatively easy for a help system to correctly identify the primitive in question, identifying the correct form of the primitive will not be so easy without parsing the sentence (which may or may not be valid). Ian wrote: > If we can all agree to this, then it follows that a good title for the > page explaining dyadic ">." is "x >. y" and not just ">." Here is a proposed adjustment to the format of the section titles to more clearly indicate the appropriate context of each. ">." NB. h1 (in lieu of a title style) "Ceiling (>. y)" NB. h2 "Larger Of (x >. y)" NB. h2 "Fictitious (x m>. y) NB. h2 > From: Ian Clark > > I think we're likely to get into a situation where we've developed a > complex template on the basis of a very few examples which prove to > have been too simple ones to choose, or the wrong choices. We then get > a raft of better idea, or experimental verification (or the opposite), > and it becomes clear we ought to retrofit a new template regenerating > all the pages, which means unpicking the content from the formatting. > > Let me make an offer, in an area in which I can claim some track > record: > > That is, to maintain on behalf of the Team a collection of "content", > in a way which defers decisions on the best page format. Or > typographic tricks, eg to hilite, say, useful / required terms, a-la > the For-Dummies books. > > On http://www.jsoftware.com/jwiki/Vocabulary/ I count some 120 J > primitives, most of which have monadic and dyadic forms. That's at > most 240 primitives, if monadic and dyadic forms are given their own > wiki pages. Plus another 50-100 pages if each comma-bang (=Foreign) is > given its own page. This is not a huge collection to maintain, > especially as most will be quite short. Once decided upon, their > number will be fixed. Or at least new pages will only be needed when a > new J primitive is introduced (most likely another comma-bang). > > I'll have to experiment a bit, but I know roughly what I'm going to > do, and I'm going to use J to do it. Once I have that in hand I'll be > happy to accept as my input the Raw Text of a collection of MoinMoin > pages. > > From all that I've read so far, we could go ahead with Ric's template > as illustrated by: > http://www.jsoftware.com/jwiki/Vocabulary/greaterthan./ > and defer the fancier typographic decisions until we've got a complete > set of content pages. > > This will allow us cooperative working with tools we understand well > enough (J wiki pages). It will yield a fixed set of pages consisting > largely of narrative + examples, easy pages to pour into some future > template. Via some batch generation process, which I will write and > maintain. > > As we compose these content-rich pages, the requirements for the > template will gradually emerge. But no sweat if we don't get it right > first time. So I suggest we just go ahead. Now! > > In the next week I'm going to come up with a list of tasks -- common > novice tasks -- to be supported by the NuVoc. What I mean by "task" is > what a HF engineer means: a step the user (typically a J novice) needs > to perform to achieve her goals (of understanding J better). > > NOTE: Tasks are not functions: functions are computer capabilities > that "support" tasks. It is to be hoped the tasks are useful ones, and > all the commoner ones are comprehensively (and comprehensibly) > supported. But so seldom is the relationship 1-to-1 between task and > function. > > Examples of tasks: > 1. Finding out what ">." (say) stands for > 2. Finding out if (say) ">." has a sister-primitive and what it is, > viz in this case "<." > 3. Finding the J code word for the primitive known as "Ceiling", ditto > "Floor", "Max", "Min", ...etc. > 4. Finding what J primitive(s) correspond(s) to the Visual Basic > function: Int() > 5. Finding what part of speech is ">." > 6. Finding out if there's a handy verb in the z-locale which uses or > delivers: "1!:2" > ...and so on and so on. > > Just one change I'd like to propose to Ric's design, but it will > simplify each page and make a successful all-inclusive template a lot > easier to invent. That is: to give monadic and dyadic cases of *all* > primitives their own separate pages. > > Now what I'm going to say next is sheer heresy... > > I don't know of any useful task the novice wants to perform which > needs both the monadic and dyadic forms of a given primitive to be on > the same page. So let's have them on separate pages. At least to start > with. They can always be stuck together later if I'm wrong: deciding > whether this-way-up or that-way-across can be deferred. > > If we can all agree to this, then it follows that a good title for the > page explaining dyadic ">." is "x >. y" and not just ">." > > It follows from this that all the examples can be couched in terms of > x and y (u, v,...). This will work both inside and outside an explicit > definition. Furthermore (and I'm getting controversial now...) *all* > examples will benefit from being couched like this: > value=. 300 > x=. 3 > y=. i. 6 > value x}y > > and not like this: > > (300) 3 } i. 6 > > or: > > 300 (3) } i. 6 > > which demands the novice to perform too many mental sub-tasks at once, > only one of which matters. > > Once the user has absorbed the "anatomised schema", i.e. the first > example: "value x}y", then confounded forms like "(300) 3 } i. 6" are > easy to infer. And what's lost if they aren't? Moreover the novice > might even see for herself without having it explained in gory detail > just why "300 3 } i. 6" isn't going to work, nor any of the 99 other > ways the novice might try of splitting "300 3". > > NOTE(1): Space is not important on a Wiki page (though it may well be > important on the printed page, in terms of cost and layout). > > NOTE(2): The above example is too simple for the alternatives to > matter much. But think of what's entailed with dyadic ";:" > > NOTE(3): The anatomised schema lends itself to having recurring stock > nouns, such as "i. 2 3" or: > > az=: 26 {. 97 }. a. > a23=: 2 3 $ az > > which the novice will soon come to recognise (and may even write into > her profile). This will aid experiments, there being one less thing to > think about. It saves distracting the novice from the task in hand > into a mental analysis of the sample value currently being used. > > The existing Voc is a bad offender here. Picking an example at random > (from Power)... > > (] ; +/\ ; +/\^:2 ; +/\^:0 1 2 3 _1 _2 _3 _4) 1 2 3 4 5 > > ...easy to appreciate if you know J already. Somewhat less easy if you > don't. > > I'm prepared to be steamrollered over my recommendation for couching > examples. But can we now agree a working "Ric" template so we can all > get started before our motivation goes off the boil? > > I'll just repeat what I offered {...deep breath}: to get some 240 > content-rich wiki pages into a final unified, cross-referenced form. > Provided their existing format is simple. > > Ian > > > > On Fri, Feb 5, 2010 at 8:13 AM, Skip Cave <s...@caveconsulting.com> > wrote: > > PackRat, > > > > I think the red exclamation point is a good idea. I have created two > > graphics, one red exclamation point graphic, and one blue question > mark > > graphic. Here are links to both graphics: > > http://teledon.info/Jvoc/Exclaim1.png > > http://teledon.info/Jvoc/Quest1.png > > > > The exclamation mark graphic should be be used to indicate required > > reading. If the reader doesn't understand the hyperlinked word or > > concept next to the red exclamation point graphic, they should follow > > the associated hyperlink (on both the word and the graphic). The > > hyperlinked text. will explain a concept that is critical to > understand > > before proceeding further in the current text. > > > > The blue question mark graphic should be used to indicate words or > > concepts that provide useful information, but that are not > immediately > > required to understand the current text. However, that information > may > > become required at some other place in the text (at which point it > will > > be marked with a red exclamation point). . > > > > An interesting example of the use of these graphics, is the word > > "Monadic" On the opening Vocabulary page the word "monadic" should > have > > a blue question mark next to the word, as at that point (on the front > > page) it is not critical to understand what "monadic" means. However, > on > > the Ceiling page, the word "monadic" needs a red exclamation point > > beside it, since on that page, it is critical to understand what > monadic > > means in order to help make clear the reason why there are two > different > > explanations under the Ceiling description. > > .. > > .Skip Cave > > . > > PackRat wrote: > >> Skip Cave wrote: > >> > >>> I had another idea - We could even have a couple of different > levels > >>> of "what's this" links. Perhaps a "you need to know this" link in > >>> bold red font for critical concepts, and a "what's this" link in > >>> blue font for the nice-to-know stuff. Or if we really want to keep > >>> the text clutter to a minimum, a red question-mark graphic for > "need > >>> to know" stuff, and a blue question-mark graphic for "nice to know" > >>> stuff. > >>> > >> > >> Perhaps a red exclamation point might be better than a question mark > to > >> emphasize the critical nature of some concept. I agree, too, that > >> these need to be graphics or else a significant change in font size > >> (and perhaps font, too) and not just using the same font and > changing > >> only the color of the character. > >> > >> By the way, the "... for dummies" series and similar series have > >> various kinds of visual markers for the beginner in terms of > important > >> concepts or "for more info..." and the like. Perhaps some of these > >> could be developed into online equivalents... > >> > >> Harvey > >> > >> -------------------------------------------------------------------- > -- > >> 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 ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
