From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Eric Bischoff Cc: docbook-tools-discuss@sourceware.cygnus.com, kde-docbook@kde.org Subject: Re: Docbook tools Date: Mon, 06 Sep 1999 21:01:00 -0000 Message-id: <76wvu32wve.fsf@odie.lanl.gov> References: <99090522193703.00542@r12m10.cybercable.tm.fr> X-SW-Source: 1999/msg00065.html Dear Eric, Others on this list have already answered some of your points, but let me also mention a couple of things. First some specific answers, and some general comments at the bottom. Eric> I am participating to the KDE project as documentation Eric> coordinator. [...] Eric> We at KDE are in the process of changing our documentation Eric> file format from LinuxDoc-SGML to DocBook-SGML. I am delighted that KDE will also be using DocBook. Eric> In order to make it easy for our many translators and Eric> documentation writers to use DocBook tools such as James Eric> Clark's Jade, the OASIS DocBook DTD and Norman Walsh Eric> Stylesheet, I was planning to package all this stuff all Eric> together - exactly what you have done at Cygnus. Eric> So it is very likely that such an effort should not be Eric> duplicate, and that we should use Cygnus tools here at KDE, Eric> maybe with some extensions and/or parametrization for the Eric> specific needs of the KDE project. That is good thinking. Eric> The DocBook team at KDE has also developped some tools that Eric> could prove of some interest for other users, such as a Eric> crash course to DocBook that people report to be of Eric> quality. Have a look at Eric> http://www.kde.org/documentation/docbook/index.html . This seems to overlap a lot with my tutorial, as others have already mentioned. Nik's FreeBSD DocBook tutorial (which started out with mine) also overlaps. Some day... Eric> I had not the time to examine the details of Cygnus Eric> packaging, this will be done in the next days. But a few Eric> questions I would love to ask have already arisen : Eric> - You have packaged nearly exactly the same tools I was Eric> planning to, with the same version numbers. There is one Eric> main exception, Norman Walsh's stylesheet. I may be wrong, Eric> but it looks like you have packaged version 0.10, whereas Eric> version 1.42 is the current one. Is there a reason for that Eric> ? The version numbering is because I used to ship three alternative DocBook stylesheets, of which Norm's was just one. Nowadays I still ship them, but I doubt they would work without a lot of work, so I should eventually make the version number match Norm's. My 0.10 tracks Norm's version 1.44. Eric> - Why not putting everything in a single tarball / RPM / Eric> SRPM ? There could be a single ./configure / make / make Eric> install sequence. The packages are maintained separately, and they use different approaches to building and installing. Maintaining a proper GNU build/install system for each of them would be hard. The SGMLTools team tries to do this, and in my opinion they have not pulled it off well: people have a terrible time installing SGMLTools from source, although I think the blame is partly in their clever (but maybe too clever) configuration system. I do think this can be done, but it will take some real work: 1. coordinate with *all* the individual maintainers so that when they are ready to put a new version out, we provide them with the automake/autoconf stuff for GNU users. 2. work out exactly how a good automake/autoconf system works for emacs lisp (both emacs and xemacs) and TeX 3. clean up the underlying sgml-common module, and have a clear concept of how the various DTDs and catalog entries accumulate as you do a "make install" for each. I would still maintain them as separate packages, but I would then feel better about releasing tarballs too (not just RPMs). The packages are all very different, and they can work with other goals, so I do not see any reason to combine them. Eric> - It is indeed a very good idea to use RPM packages for Eric> those using RedHat-based systems (I am one, I am using Eric> LinuxPPC for Macintosh ;-) ). What is the reason for putting Eric> both the 3.0 version and the 3.1 version of the DocBook DTD Eric> in the RPM archive? It makes the file bigger. The reason is so that you can process both 3.0 and 3.1 DocBook documents. If you look at the mailing list archives, my most recent large announcement talked about that in a bit more detail. Eric> - Have you encountered the same problems we have encountered Eric> with non-English languages and the TeX backend ? [...] Dave Mason has already answered this point. I will add that CKVJ (or whatever the order was) probably stands for Chinese, Korean, Vietnamese, Japanese. Eric> - I don't know what the hyperref package is and why it may Eric> be part of DocBook tools. Maybe I should try harder to Eric> understand that. Any help ? No *immediate* help, except that jadetex uses it, and it used to not come with a basic TeX distribution. It does now, but I'm not sure about the version numbers. Next time I put out a package, I will see if I can do without the hyperref stuff :-) Eric> I hope that all these questions are interesting this Eric> discussion list, I apologize in advance for not having read Eric> all the archive of this mailing list, I was short in time. The questions are certainly quite intersting. Thanks for participating! Let me now make a couple of suggestions: * I strongly recommend that you use the same RPM distribution of tools that we use (I'm also trying to get the Debian guys to start working from common source). You should participate in the software effort (it's not hard) so that we can come up with a whole collection of customizations for the stylesheets. Ideally there should be the Cygnus customization (which is rather small), the GNOME one, the KDE one, the FreeBSD one, the "linux documentation project" one, and so forth. I would like them all to be easy switches to "db2html" and the other "db2*" scripts. I'll talk about this more some other time, when I outline my ideas for future enhancements. * I would merge the tutorials together. Take a look at mine ( http://nis-www.lanl.gov/~rosalia/docbook-intro.html ) and let me know if we can merge some of your beef with mine, and then maybe make a KDE-specific appendix. * I am delighted about the possibility of KDE/GNOME cooperation in documentation issues. We should talk about some aspects of this, like directory layout, help-topics locations, common Makefile.am documentaiton target rules, and maybe equivalent help menus. We'd teach the other parts of the GNOME and KDE teams how well we work together on common standards. And then we can also teach the Russians and the Chinese to live happily together.