[Openmcl-devel] Interest in documentation reorganizationl?
dankna at accela.net
Sat May 29 07:26:50 PDT 2004
Hi there! I'm coming to OpenMCL/Darwin after using CMUCL/Linux for a
year or two, and so far I've been really happy with what I've seen.
The FFI is well-designed, and the Cocoa binding, though a work in
progress, is the right approach. I'm sure you all knew that, but hey.
While I don't expect to have time to assist with any large changes to
the system, I'm happy to volunteer for any small things that people
might need done. There's one thing in particular which I think the
project is sorely in need of - reorganized documentation.
As things stand, FFI functions are described in three or four different
html files; while it's clear why they were organized that way, it is
not easy for a user to find out what facilities exist, or what they are
called. The minor utility functions could just as well go in any of
those files; none really fits better than the others.
The rest of it is not that bad; but there's no clear overview of what
documentation exists, nor any recommended reading order. I eventually
had to resort to looking at the filenames to find a couple things.
I envision a document structure similar to the CLHS. The introduction
of concepts would be separated from the detailed descriptions of
function semantics. Everything would be heavily hyperlinked to nearby
nodes. There would be a symbol index and a table of contents.
What do other people think? If it sounds like a good idea, I'll try to
put something together over the next week or so.
-- Dan Knapp
More information about the Openmcl-devel