Fwd: Re: DocBook

[Bernd Gehrmann]

Ralf, you have already done some modificationns 
in KDevelop for DocBook, so this may also be 
interesting for you :-) 

Bernd.

----------  Forwarded message  ----------
Subject: Re: DocBook
Date: Wed, 13 Oct 1999 22:14:34 -0400
From: Eric Bischoff <ebisch at cybercable.tm.fr>


(Frederik, there is a note for you in this reply).

Le Wed, 13 Oct 1999, vous avez écrit :
> Hi Eric,
> 
> I'm currently trying to understand all the issues involved
> with the DocBook transition, especially wrt KDevelop. IIRC,
> you told me that there are problems with having DocBook
> and LinuxDoc stuff installed. What are these problems?

There are a lot of conflicts with Linux distributions, broken files, there's a
bug in KFM, etc... Many errors have their origin outside kdesdk and I always
filed a report to the competent packager, so many problems may be solved in the
next weeks. There are also workarounds for the meantime.

Nothing is very serious, but docbook isn't yet an "out-of-the-box" product. But
I would really love it to be very standard and easy to install.

> Are these resolved by 'conflicts' tags in packages (at
> least on Linux)?

Sounds interesting. What is it, exactly, a 'conflict tag' ?

> KDevelop 1 (based on KDE 1) supports the 
> generation of HTML documentation via sgml2html. If there
> are any problems, we should at least mention them in the
> README or the documentation.

sgml2html has been left over when we changed from LinuxDoc to DocBook.

This is why KDevelop should not rely anymore on SGML-tools by Cees de Groot.

Moreover, sgml-tools package conflicts (nothing very serious, though) with the
Cygnus distribution (at least on a RPM-like system).

> For KDevelop 2 (based on KDE 2) we will want to support
> db2html and the other helper programs for DocBook (I think
> Ralf Nolden has already done some work on it).

Great decision !

I have been speaking with him, and showed him that it was quite easy to parse
jade error output.

> So I have
> looked a bit in the Cygnus distribution and the kdesdk
> package. First of all, you should move your web page on 
> DocBook on developer.kde.org or at least put a link there.

It was supposed to move to a machine dedicated to documentation and
internationalization (presumably Mimas).

> I was a bit surprised to find a section on Documentation
> tools on developer.kde.org without any mention of the
> KDE-specific customizations.

If it is the paper I sent to Richard Morre, it is said that ithe tools are
customized for KDE. Just check.

All this stuff is very new. The conversion to DocBook should be accomplished
first, and then I will be happy to dedicate myself again to more organizational
stuff.

Anyway, you're right, there should be more communication with developpers. I'm
aware about that.

> The next thing, the INSTALL
> file in ksgmltools looks quite rpm-specific (which is 
> understandable if you guys all have rpm-based systems ;-)

This is a ** BIG ** and serious problem. Guys like you are developpers and
therefore are flexible enough to make the other kind of packages work with the
source distribution. But maybe all the translators here are not that used to
such difficulties.

I have at home a RPM-like system (LinuxPPC), but it isn't an Intel platform. So
I had to recompile and adapt everything from the source distribution. So there
are hints for such a case in the INSTALL file, but of course the main part of
the file is dedicated to RPMs on an Intel box, which is the most common case
among translators.

Maybe I should split this file in three parts to cover every case separately :
- RPMs on Intel
- DEBs on Intel
- source distribution

Unfortunately, I haven't had the occasion to try the tools on a debian-like
system. And it would take some time to reorganize that INSTALL file.

> Anyway, as far as I can tell the wrapper scripts db2*
> are in the 'cygnus-stylesheets' package on potato (i. e.
> the unstable branch of Debian, which will become Debian 2.2).
> The rest will probably be pulled in by dependencies.

Oh, you're on debian. I would be very glad if you could write at least a word
(and maybe more ;-) ) on the way to install it on a debian-like system.

> Speaking of ksgmltools, I think it would be a good idea
> to urge the package people (primarily those of kde.tdyc.com)
> to make the stuff available in a more convenient way.

Stephan Kulow should do that. My Makefile may be real amateur work.

> Unfortunately, I don't quite understand the Makefile.
> What is the following good for:
> 
>         cp patches/db2ps $(CYGNUS_BIN)
>         ln -s $(CYGNUS_DSL)/nwalsh-modular/html $(NWALSH_DSL)/html
>         ln -s $(CYGNUS_DSL)/nwalsh-modular/print $(NWALSH_DSL)/print

Workarounds ;-) I guess I'm the very first guy to try to use alternate (KDE)
stylesheets with the Cygnus distribution.

The problems have been filed to Mark Galassi and when solved those lines could
disappear.

(By the way - Frederik, if you're reading that : could we suppress in the
meantime these last two lines by using formal public identifiers in kde.dsl to
make aware of the real place of Norman Walsh's stylesheets ? It should be the
entity "docbook.dsl" that has to be redefined)

> This looks like a hack in a package different from ksgmltools,
> which would violate the principles of packages. 

Yes it is. Any better idea ?

> Ah, and a last thing: if I understand the documentation correctly,
> it is necessary to use an absolute path to the kde stylesheet
> on the command line when producing KDE documentation. This is
> a bit ugly when one wants to support this via e. g. KDevelop.
> For example, on FreeBSD, the absolute path is certainly different,
> namely under /usr/local or so. What about adding some convenience
> scripts like kdb2html which hide these portability issues?

You could use environment variables to do that. correctly from KDevelop.

I did not want to add too much new stuff like scripts. But it isn't a bad
idea anyway.
  
> So far. Anyway, many thanks for your (plural) great work on
> the DocBook transition and the crash course! It's important,
> but apparently not respected as much as other tasks in the
> public.

After so much hard criticism, this is really a relief ;-).

More seriously, you can consider yourself as authorized to tailor the docbook
team stuff to your own needs (but just tell me what you did ;-) so that I
can learn). I have no time right now to implement your suggestions (I would
have, but there are some other priorities : having a reply to give for every
installation problem, getting the documentation translated to docbook), but I
have nothing against you doing it by yourself. You could also join the DocBook
team if you feel like doing that.

And thanks a lot for all you comments and suggestions.

Eric
--
 __________________________________________________
                                           \^o~_.
     .~.                           ______  /( __ )
     /V\         Toys story         \__  \/  (  V
   //   \\                            \__| (__=v
  /(     )\                        |\___/     )
    ^^-^^                           \_____(  )
     Tux                    Konqui         \__=v
 __________________________________________________
 Eric Bischoff   -   mailto:ebisch at cybercable.tm.fr