2008/10/13 Tomas Hlavaty <[EMAIL PROTECTED]>:
> 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.

Yes I intend to. I'd like to give something a little more substantial
on structure manipulation. There is a few things I have in mind.

> 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;-)

Documentation is part of the reason why picolisp is a great project.
There are too many Open source projects where the code is the
documentation.

As such improvements to the documentation are just as important as
improvements to the code. As  I said earlier this seems a point which
is sufficently important to be in the core documentation.

The one nice thing about having core documetnation, which is local to
my system is that I can access it when I'm offline, which is most of
the time.

I get the impression that some people stay online constantly. Here in
Australia however internet connections are comparable expensive (we
don't have true unlimited usage plans, it is all metered by download
amount). So my laptop stays offline unless I really, really, need
somthing that isn't on my system.

regs

Konrad.


>
> 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]
>
-- 
UNSUBSCRIBE: mailto:[EMAIL PROTECTED]

Reply via email to