On Thu, Mar 25, 2010 at 2:54 PM, Matthew Mondor <mm_lists@pulsar-zone.net> wrote:
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.

That would be really good.
 
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 :)

I use Aquamac's nxml mode, which is also standard in recent Emacs as well. It knows the XML template and helps in completing tags, etc. I use docbook because I do not like texinfo and because it is standard and looks good if processed properly. If you choose another editor I would love to know.

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.

As a rule of thumb, functions with an ecl_ prefix have been revisited and can be standardized. All functions in the CL package which carry the cl_ prefix are acknowledged as to-stay :-) I would also avoid documenting the structure internals, and we can create macros for accessing their slots if needed. Functions with the si_ prefix should be avoided, except those that are exported in the EXT package. 

One thing we have to do is to ensure that all ECL specific functions and macros are prefixed, with ECL_ or something like that, but this can be done "in parallel", replacing the appropriate names both in the headers and in the documentation.
 
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...

The Wiki in http://ecls.wikispaces.com/ is working -- at least whenever I tried --. It is right now all I can offer. Mediawiki in Sourceforge is crap  because they cut down all permissions and I would have to allow / disallow people, force them using accounts, etc, so in the end nobody uses it.

But the wiki right now is not an *official* documentation platform in the sense of it becoming the manual.

I have mixed feelings about doing that.
* The manual is already huge and porting it is difficult.
* A Wiki is not a book, and it does not work as an editing platform in any way near latex, docbook or even texinfo. Markup is limited, cross-referencing is just via hyperlinks, etc, etc.
* Wikis tend to grow into large, unstructured sources of information. Enforcing an order is way more difficult there than in an organized "book"
* We do not have a good wiki platform. Wikispaces is working but it is tiny. We can not use Mediawiki in Sourceforge for reasons already explained.

I am willing to listen to new options, though.

Juanjo

--
Instituto de Física Fundamental, CSIC
c/ Serrano, 113b, Madrid 28006 (Spain)
http://tream.dreamhosters.com