<div class="gmail_quote">On Thu, Mar 25, 2010 at 2:54 PM, Matthew Mondor <span dir="ltr"><<a href="mailto:mm_lists@pulsar-zone.net" target="_blank">mm_lists@pulsar-zone.net</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I think that we all agree that the C APIs and FFI should be better<br>
documented, however this needs work on the part of volunteers to<br>
complete.<br></blockquote><div><br></div><div>That would be really good.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
I would like to eventually help but am currently unfamiliar with the<br>
format used by the current documentation (docbook, I think). I would<br>
have to look at the tools available for emacs to make editing that XML<br>
format less troublesome (I find XML not very suited to humans, yet<br>
suboptimal for software as well. But as long as the job can be done, I<br>
guess). When I have enough free time (possibly in vacations) I might<br>
look at it, but others are also welcome to send patches :)<br></blockquote><div><br></div><div>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.</div>
<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
We'll also probably need occasional help from Juanjo to determine what<br>
is public enough to be documented, and what is subject to change; also<br>
in cases where there is redundancy or misunderstanding of the purpose<br>
of some functions.<br></blockquote><div><br></div><div>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. </div>
<div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The Mozilla project setup a wiki (mediawiki) for that and I helped<br>
migrate their old SpiderMonkey documentation to it a few years ago and<br>
to update it, but I wonder if such a solution would be practical for<br>
this project? At least the format should easily be<br>
exportable/importable as needed, most probably, so that it isn't wind<br>
if software has to be changed. I see a wiki link from the Resources<br>
page at <a href="http://ecls.sourceforge.net/" target="_blank">http://ecls.sourceforge.net/</a>, but it sometimes seemed down, and<br>
I seem not to be able to edit (getting a blank page) using that<br>
software. I'm unsure it should serve as an official documentation<br>
platform...<br></blockquote><div><br></div><div>The Wiki in <a href="http://ecls.wikispaces.com/">http://ecls.wikispaces.com/</a> 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.</div>
<div><br></div><div>But the wiki right now is not an *official* documentation platform in the sense of it becoming the manual.</div><div><br></div><div>I have mixed feelings about doing that.</div><div>* The manual is already huge and porting it is difficult.</div>
<div>* 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.</div><div>* Wikis tend to grow into large, unstructured sources of information. Enforcing an order is way more difficult there than in an organized "book"</div>
<div>* 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.</div><div><br></div><div>I am willing to listen to new options, though.</div>
<div><br></div><div>Juanjo</div><div><br></div></div>-- <br>Instituto de Física Fundamental, CSIC<br>c/ Serrano, 113b, Madrid 28006 (Spain) <br><a href="http://tream.dreamhosters.com" target="_blank">http://tream.dreamhosters.com</a><br>