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

[Juan Jose Garcia-Ripoll]

On Thu, Mar 25, 2010 at 2:54 PM, Matthew Mondor <mm_lists at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/ecl-devel/attachments/20100325/834eed5b/attachment.html>