[Ecls-list] Documentation [was: how to cache a cl_object in C?]

[Matthew Mondor]

On Thu, 25 Mar 2010 20:06:15 +0800
yami <yamisoe at gmail.com> wrote:

> BTW: it is a pain to deal with ECL & C, because no good documentation is
> available.
> Why there is no good doc work here? Especially for integrating ECL and C
> programs, which is a selling-point of ECL.

I think that we all agree that the C APIs and FFI should be better
documented, however this needs work on the part of volunteers to
complete.

I would like to eventually help but am currently unfamiliar with the
format used by the current documentation (docbook, I think). I would
have to look at the tools available for emacs to make editing that XML
format less troublesome (I find XML not very suited to humans, yet
suboptimal for software as well.  But as long as the job can be done, I
guess).  When I have enough free time (possibly in vacations) I might
look at it, but others are also welcome to send patches :)

We'll also probably need occasional help from Juanjo to determine what
is public enough to be documented, and what is subject to change;  also
in cases where there is redundancy or misunderstanding of the purpose
of some functions.

The Mozilla project setup a wiki (mediawiki) for that and I helped
migrate their old SpiderMonkey documentation to it a few years ago and
to update it, but I wonder if such a solution would be practical for
this project?  At least the format should easily be
exportable/importable as needed, most probably, so that it isn't wind
if software has to be changed.  I see a wiki link from the Resources
page at http://ecls.sourceforge.net/, but it sometimes seemed down, and
I seem not to be able to edit (getting a blank page) using that
software.  I'm unsure it should serve as an official documentation
platform...

Thanks,
-- 
Matt