[Openmcl-devel] Interest in documentation reorganizationl?

[Gary Byers]

On Sat, 29 May 2004, Dan Knapp wrote:

> 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
>

>From my point of view, this sounds like a great idea (especially if someone
else if volunteering ...).

One thing that might (or might not) make things a little easier: all
of the documentation source (in fact, all of the website content) is
in DocBook XML format and is maintained in CVS; a cron job runs on the
web server every hour or so, checking the XML sources out of CVS and
rebuilding the HTML files from them.  (The HTML documentation in the
release archives is just copied off of the web server.)

In theory, this means that updating the documentation is a simple
matter of using powerful XML-aware editing tools, checking things
into CVS, and letting the website/documentation archive more-or-less
maintain itself.  In practice, it's not always quite that simple,
but it's probably a bit easier to maintain this way than editing
raw HTML in Emacs used to be ...

The website content can be checked out via anonymous CVS:

shell> cvs -d :pserver:cvs at clozure.com:/usr/local/publiccvs get website

(if it's necessary to do a "cvs login" first, the password is "cvs".)

If  anyone wants write access to this stuff, let me know and I'll set
it up.

(I'd also guess that anyone trying to reorganize/improve the documentation
might find useful content in the release notes from time to time; it may
be the case that some things are -only- documented in the release notes.)