[Openmcl-devel] OpenMCL documentation

[mikel evins]

> Gary Byers gb at clozure.com
> Wed Jan 7 18:30:39 MST 2004
>
> 	• 	Previous message: [Openmcl-devel] Re: persistence of xref info in 
> fasl files.
> 	• 	Next message: [Openmcl-devel] typo in who-binds
> 	• 	Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
>
> On Sun, 4 Jan 2004, Oliver Markovic wrote:
> >
> > Speaking of documentation, I'd like to write a page or two about the
> > XREF API,
> > since I don't think it should change that much (apart from the
> > implementation).
> > The HTML pages seem to be generated from Docbook sources, which I 
> can't
> > find anywhere. Are they downloadable somewhere?
> >
> > --
> >    Oliver Markovic
>
> I mentioned in an earlier reply that the existing documentation was
> written with LyX, which is able to produce DocBook SGML, and that I
> had found it hard enough to set up a DocBook SGML
> toolchain/environment under OS/X that I'd been doing it exclusively
> under Linux.
>
> I was able to convert the intermediate SGML stuff into DocBook XML,
> and am starting to think that this might be the way to go.  It may not
> be as simple in practice as it's supposed to be in theory, but DocBook
> XML seems to be pretty well supported on OS/X, LinuxPPC, and other
> platforms, and there are a greater number of options for editing and
> translating and whatever else.  Those options include WYSIWYG editors
> that allow one to remain (mostly) ignorant of the gory details, and
> that's one of the things that I found nice about LyX.
>
> Like any reasonable person, I pride myself on knowing as little about
> this stuff as I can get away with.  If we're primarily just interested
> in being able to (a) produce a page or two of (mostly HTML) output now
> and then, (b) having that be relatively consistent-looking and (c)
> being able maintain things without too much hassle, using DocBook XML
> seems like a good approach.
>
> 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