[Openmcl-devel] OpenMCL documentation

[Gary Byers]

On Fri, 16 Jan 2004, mikel evins wrote:
> > Those might be famous last words, of course.  If anyone's thinking of
> > writing any OpenMCL documentation and can do it in DocBook XML, I
> > think that that'd be the "preferred" way to do it; if anyone needs
> > pointers to get started I might know enough to help (and it might even
> > be possible that other people on this list know more than the minimum
> > about XML and available tools and have not yet gone completly mad.)
> >
> >
>
>
> In fact, managing a relatively complicated DocBook XML toolchain from
> my PowerBook is what I'm doing for a living these days. I'd be happy to
> help if the need arises.
>
> --me
>

In the current scheme (as of the last week or so):

 - the DocBook XML sources to everything on the website (including the
   /Doc directory) are maintained in CVS.

 - once an hour (on the hour), a cron job on clozure.com does a
   "cvs update" and rebuilds any HTML files on the (live) website
   that're older than the XML source.  (It's a -little- careful
   not to overwrite the HTML if the translation fails.)

   I suppose that the cron job could also create a tar archive of
   the html documentation and put that in the FTP directory somewhere.

This doesn't help to ensure that the documentation's always correct,
free of typos, or clearly written, but it does seem to simplify some
parts of the process.

It also means that (in this simple scheme) "publishing" the XML means
"getting it into CVS".  Write access to CVS here has to go through
SSH and takes a little time to set up; if anyone wants this, please
let me know.  (The other way to get XML files into CVS is to mail
them to me.)