Scrollkeeper, the documentation, XML, and the way forward

[Scott Ritchie]

I wanted the Wine documentation to appear on the nice help menus, like
other standard apps.  I learned that the way to do this is to write an
OMF file for each document, which scrollkeeper can then look at to find
the metadata about where the document is and how to index it and such.

The trouble is, Scrollkeeper and the Gnome help menus no longer support
SGML, as XML is the current new and hip thing.  

The Wine documentation is in SGML.  There are quite a few reasons to
move forward.  The Wine documentation is also a bit separate (requiring
its own compiling, for example) from the main code, and this should
change.

This link:
http://scrollkeeper.sourceforge.net/documentation/scrollkeeper_example2_manual/ar01s02.html has some good information about how Wine should look to play well with Scrollkeeper and modern distros.


I propose we attack this in phases, and create the following plan of
attack:

1) Create a new directory for all XML documentation at wine/doc.  This
will also bring us to be more standard.
2) When we convert old SGML documents to XML and move them there, we
write an OMF file for them then and there (I'll do it if you like).  We
also make sure the build process is aware of this stuff and is
installing the xml and omf files in the right place so scrollkeeper can
find them when it runs after build time.
3) We follow the steps at the above link to add scrollkeeper into the
configure scripts after we convert the first document to XML.  I vote
for the Wine User Guide, since I'm working on it.
4) We inform the packagers once scrollkeeper is working in a release, as
there are sometimes little tricks for it (one for rpms is on the page)


So, beyond that, the first step seems pretty simple: convert the sgml
stuff into xml format and put it into the new doc folder.  Can someone
point me to some good tools to do this?

Thanks,
Scott Ritchie