Scrollkeeper, the documentation, XML, and the way forward
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_manu... 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
On Sat, Mar 12, 2005 at 04:57:22PM -0800, Scott Ritchie wrote:
1) Create a new directory for all XML documentation at wine/doc. This will also bring us to be more standard.
You better check with Alexandre first, I doubt he'll go for it.
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.
You should coordinate with Brian, he has patches waiting for the winecfg work, it would be a shame if this work creates a big problem for him. -- Dimi.
On Sun, 2005-03-13 at 03:11 -0500, Dimitrie O. Paun wrote:
On Sat, Mar 12, 2005 at 04:57:22PM -0800, Scott Ritchie wrote:
1) Create a new directory for all XML documentation at wine/doc. This will also bring us to be more standard.
You better check with Alexandre first, I doubt he'll go for it.
Well, let's discuss it here then. What's so great about SGML, when scrollkeeper doesn't like it and we can convert it to html/txt with similar tools to the ones we use now?
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.
You should coordinate with Brian, he has patches waiting for the winecfg work, it would be a shame if this work creates a big problem for him.
I'm aware of it. We've discussed it. Although I would urge you guys to get winecfg working so Brian can commit his patches and the documentation can creep out of the stone ages :) Thanks, Scott Ritchie
Scott Ritchie <scott(a)open-vote.org> writes:
Well, let's discuss it here then. What's so great about SGML, when scrollkeeper doesn't like it and we can convert it to html/txt with similar tools to the ones we use now?
There's nothing great about SGML, no argument here; but as far as I can tell XML is the same mess except a bit worse. And I can't say I'm particularly thrilled to have to change all the documentation every couple of years just to follow the so-called standard of the day. -- Alexandre Julliard julliard(a)winehq.org
On Sun, 13 Mar 2005 11:53:01 +0100, Alexandre Julliard wrote:
There's nothing great about SGML, no argument here; but as far as I can tell XML is the same mess except a bit worse. And I can't say I'm particularly thrilled to have to change all the documentation every couple of years just to follow the so-called standard of the day.
As far as I know our documentation almost *is* XML, I think if it weren't for the <!docbook thing at the top it'd be valid. I don't see anything wrong with modifying the way we include stuff slightly to make it valid XML, I doubt it'd be invasive. The DocBook XML toolchain is better in my experience than jade et al anyway. On the other hand I do question the value of ScrollKeeper integration right now. I think there is a plan to replace it with some new freedesktop.org help standard though no real timeframe to do so. thanks -mike
On Sun, Mar 13, 2005 at 11:53:01AM +0100, Alexandre Julliard wrote:
Scott Ritchie <scott(a)open-vote.org> writes: There's nothing great about SGML, no argument here; but as far as I can tell XML is the same mess except a bit worse. And I can't say I'm particularly thrilled to have to change all the documentation every couple of years just to follow the so-called standard of the day.
As Mike pointed out already, I don't think it's a big deal to convert to XML. One benefit would be to get away from the awful DSSSL crap. With XSLT we at least have a chance of modifying it if we need to :) However, I was concerned about the new doc/ directory that Scott had in mind, I'm not sure we need it for this conversion. -- Dimi.
On Sat, 12 Mar 2005 16:57:22 -0800, Scott Ritchie <scott(a)open-vote.org> wrote:
1) Create a new directory for all XML documentation at wine/doc. This will also bring us to be more standard.
The key is that we use Docbook's SGML. Docbook now supports XML and converting the SGML is as easy Mike said: http://infohost.nmt.edu/tcc/help/pubs/docbook42/convert-4-1-section.html So, I'm not sure what would need to change on the tools end to build the docs - probably not much? If you converted to XML, it appears none of the tools would need to change. Of course you still need to support all of the various doc formats - PDF, ps, HTML, etc. There's two reasons I can think of to do this. First, it appears that as of about mid-2002 Docbook in XML became the preferred method. The DSSSL toolchain was deprecated in favor of XSLT. Second, it would be nice if we could dynamically display (or at least build daily) XML from CVS and display it on WineHQ. We've had problems in the past where the docs on the website have been 3 or 4 months out of date compared to CVS. Newman may have fixed this last year, but I'm not really sure what the current process is to get docs up. However, I'm not sure its worth the effort. -Brian
On Sun, Mar 13, 2005 at 09:13:31AM -0700, Brian Vincent wrote:
On Sat, 12 Mar 2005 16:57:22 -0800, Scott Ritchie <scott(a)open-vote.org> wrote:
1) Create a new directory for all XML documentation at wine/doc. This will also bring us to be more standard.
The key is that we use Docbook's SGML. Docbook now supports XML and converting the SGML is as easy Mike said: http://infohost.nmt.edu/tcc/help/pubs/docbook42/convert-4-1-section.html
Except for (2), they should fix emacs's xml-mode instead. No need to further uglify the docs.
nice if we could dynamically display (or at least build daily) XML from CVS and display it on WineHQ. We've had problems in the past where the docs on the website have been 3 or 4 months out of date compared to CVS. Newman may have fixed this last year, but I'm not really sure what the current process is to get docs up.
IIRC Newman regenerate the docs only at Wine releases, so that's why they are so our of synch with CVS. Not sure this is what we want though. AFAIAC, I'd like the docs at WineHQ to track CVS as close as possible. -- Dimi.
On Sat, 12 Mar 2005, Scott Ritchie wrote:
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.
Does this mean that scrollkeeper is a Gnome specific thing? I guess not since I don't see how such a system should be desktop specific. I looked at the scrollkeeper website but I did not see how applications interface with scrollkeeper. Yet they have to if Wine is to appear on the help menus... unless I'm misunderstanding what/where these help menus are (quite possible).
From what I understand the OMF files work just fine with regular HTML files. So why not just instruct the packagers to ship an OMF file that points to the HTML file we already generate?
Last point: if we convert the documentation to DocBook/XML, can we still use po files to translate it to other languages? Scrollkeeper seems to have some provisions for localisation but that only seems to extend to the OMF files (which probably makes sense). -- Francois Gouget fgouget(a)free.fr http://fgouget.free.fr/ In a world without fences who needs Gates?
participants (6)
-
Alexandre Julliard -
Brian Vincent -
Dimitrie O. Paun -
Francois Gouget -
Mike Hearn -
Scott Ritchie