[Openmcl-devel] OpenMCL documentation

[Gary Byers]

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