[Openmcl-devel] Interest in documentation reorganization?

[Gary Byers]

On Mon, 31 May 2004, Dan Knapp wrote:

> Okay, I restored the link to the html copy of the internals docs,
> thanks.
>
> According to the DocBook docs, the tool for rescuing DocBook SGML is
> sgmlnorm, part of the SP and Jade tools, available at
> http://www.jclark.com/
> - 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
called "osx".

I was able to do a LyX->SGML->XML translation, and the result is at:

http://openmcl.clozure.com/mcldoc/mcldoc.xml

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

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

>
> 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
> is
> mainly text, with just a few tables, so even a manual conversion
> wouldn't
> 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
> http://clozure.com/mailman/listinfo/openmcl-devel
>
>