Hi all,
I think I have said this before, but I will repeat it. In my
experience, a Wiki is only truly successful if there are very clear
rules, styles, and usually someone with a heavy hand to enforce that.
I think that the original author of picolisp may be concerned that he
gives up the documentation, and is left in one or two years with a
mess. This is probably not the case, but I can certainly understand the
concern.
A simple solution would be, just duplicate the documentation in the
Wiki, make it better and better and make sure it is well supported.
Sorry, ad hoc doesn't work, I believe. Python doc, for instance, is
very well and tightly controlled. And the control takes more time and
effort than just maintaining what exists. So I don't expect Alex to jump
in and manage and control a Wiki.
Randall
Tomas Hlavaty wrote:
Hi Konrad,
Well thats two improvements to the documentation.
Perhaps a perfect candidate for the Wiki?
Hmm.
var - Variable: Either a symbol or a cell
(set 'var 'any ..) -> any
Stores new values any in the var arguments. See also setq, val and def.
Even taken in concert these two snippets don't actually explain what
will happen if var is a cell. It may be obvious (if you already know)
that if var is a cell than action will be taken on the car part.
However it does not actually say so. I note that the definition of con
does say so even though its signature has the more specific data type
of Lst.
The best a very careful first time reader could pick up is that the
behavior is not explicitly spelled out. They could then, guess,
experiment or ask.
I would say that there are some functions where additional verbosity
is warranted. the function for assigning values is one such place.
Especially when the acutal behaviour may not be what people with Lisp
experience expect.
While succinctness is good in documentation, it is possible to have
too much of a good thing.
nothing is perfect but rather than arguing with Alex about quality of
his documentation, would not it be easier and more useful to take
action and put it in the picoWiki? I think everybody would appreciate
your knowledge and it would be preserved for newcomers too. It would
at least make it easier for Alex not to spend his lifetime maintaining
his documentation to everybody's tastes and focus on his clients,
writing code and having fun instead;-)
There are many different Lisp dialects so people's expectations could
vary depending on their background. A wiki page for people comming
from Common Lisp background, for example, would be great!
Cheers,
Tomas
--
UNSUBSCRIBE: mailto:[EMAIL PROTECTED]
