While reviewing the newLISP manual, I have noticed a function argument "natural order" puzzle for confusing newbies and frustrating oldies ;)
Given:
Find a string in text :
Okay. But
Shouldn't
The reason I ask is that I prototype my regex's using
Also, when building the string to be searched in place
"this" gets lost in the
Remains understandable...
And while I am "on a roll" (ranting :)
While this form just looks cleaner and clearer to me.
--xytroxon
Quote
..more important, I think, is that pseudo-code self-explanatory formulas
were included into the manual as well as in the short help one-liners.
This (verbs, nouns, verb phrase) is how brain operates naturally, and writing documentation "formally", i.e. requiring the poor sod of user to:
(a) learn the special lingo to speak ABOUT the target language
(b) read the stuff in the lingo, which speaks "about" but not to the point
(c) do the internal translation into exactly this kind of pseudo-code:
"Aha! so this is "match this in-this-(buffer)-string".
Now he "understood"! Eureka!!
This problem, or a slightly more general problem of right "entry" is the major problem in presenting any information.
It's like they gave you a task to find all telepnones in a certain area by reading an alphabetic telepnone book. Of course, the information is there, but to get the needed prefix you'd have to scan THE WHOLE of it.
These 2 defects literally kill good programming ideas. Both are present in the formal decumentation that "follows (government) standards", try to find a practical description of LISP!
The Internet Age made people without formulating it as a principle spontaneously re-write explanations in a much more practical way.
"Cookbooks", documentation and "intro" texts for the modern scripting languages are of incomparably better quality than those of the previous age (requiring to learn the birdy talk of descriptions "about" and back-translating into concrete examples).
However even now the principle is not implemented fully because people lack explicit understanding of the above.
We can with little effort make all NewLisp operator definitions self=-explanatory.
I did this for an earlier version of the manual, but it will need redoing now.
P.S. Interesting that the same realization happened in linguistics, too. A pioneering project in Birmingham University (they were one of the first to use computers to analyze actual usage pattern of English in the 1980s, by the way).
Their word definitions being definitions at the same time describe the actual collocation and usage patterns as well.
Great thoughts and comments from Xytroxon and Unixtechie!
Normally I try to make the sequence of parameters the way you would talk in a natural language:
starts <text> with <this>? => (starts-with text this)
or
find <this> in <text> => (find this text)
But one cannot go by just one principle when designing an API or the syntax of a specific function. There are several principles according to which you can build an intuitive API. All of these have to be balanced against each other:
(1) closeness to natural language
(2) easy/short to type and memorize
(3) consistency inside a family of functions
(4) redability of composite expressions
(5) fits into programming languages culture
... etc. add your own ;-)
Regarding documentation style: The reference documentation tries to balance between a formal (government) and more casual approach. Probably a lot can be improved here. Its a never ending task.
In Cormullion's "Introduction to newLISP" we find the casual, entertaining approach, very suitable for an introduction to a complex technical topic. For my taste it came out pretty perfect and should go into print. Its among the top downloads on newlisp.org.
Quote from: "Lutz"
Cool! The next version is in Technicolor - well the code listings are.