[Openmcl-devel] Interest in documentation reorganization?
gb at clozure.com
Mon May 31 09:49:22 EDT 2004
On Mon, 31 May 2004, Dan Knapp wrote:
> Okay, I restored the link to the html copy of the internals docs,
> According to the DocBook docs, the tool for rescuing DocBook SGML is
> sgmlnorm, part of the SP and Jade tools, available at
> - does that sound familiar?
I remembered that the name of program I used was short and matched
a common acronym that was familiar from some other context. It took
a while, but I eventually reaslized that the program in question is
I was able to do a LyX->SGML->XML translation, and the result is at:
Sadly, the translation tools don't know how to bring the content up
to date; it still roughly corresponds to how things were 3 or 4 years
> I certainly think it's better to have the internals documentation than
> not to
> have it, albiet with a note about its age. Whether to update it
> depends on
> how much time it would take you, I suppose. Most Lisps do provide this
> information in some form, although it would probably only be useful to
> someone doing development on OpenMCL itself.
I wonder if anyone has (a) read the old internals docs and (b) found
the current kernel sources or low-level implementation arcana easier to
understand as a result of having done so.
My guess is that it might be something like the documentation that
accompanies the Linux kernel (which is obviously a much larger and
much more complicated system): the documentation doesn't change as
fast as the software does and it's often heavily oriented towards x86
users, but reading a description of how things used to be on a
different platform often makes the current sources easier to
> Some of the information in it, I note, has already been superseded by
> other documents, which is good. What's left is not a huge document and
> mainly text, with just a few tables, so even a manual conversion
> take an inordinate amount of time.
In at least a few cases that I can think of (threads, for instance)
the user-level and implementation-level documentation should ideally
be very different.
> -- Dan Knapp
> Openmcl-devel mailing list
> Openmcl-devel at clozure.com
More information about the Openmcl-devel