The K Desktop Environment

Installation guide to KDE documentation tools


What can I do with the KDE documentation tools?

At the present time, one of the few things you can do with DocBook files is to convert them to some other format, like HTML. Then those HTML files can be viewed in khelpcenter.

This is not too bad a restriction: DocBook is a very good format for documentation, because it allows to focus on the contents of your documents instead of their presentation, and therefore diplaying online the contents of a DocBook file is not really what it is made for.

Maybe someday it will be possible to browse directly the DocBook files contents, for example with a new KDE help center. But let's stop speaking about the future ;-).

How do I process DocBook files?

If you just want the documentation to be compiled correctly in KDE packages:

Then normally all KDE packages should build correctly at this point. The ordinary sequence of instructions

	./configure && make && make install

should provide the desired results for every KDE package (kdebase, kdenetwork, kde-i18n, etc).

If you are a doc writer or translator and want to test your work:

type:

	docbook2html -c <catalog> -d <stylesheet>#html <filename>.docbook
		to convert to HTML
	docbook2ps -c <catalog> -d <stylesheet>#print <filename>.docbook
		to convert to PostScript
	docbook2pdf -c <catalog> -d <stylesheet>#print <filename>.docbook
		to convert to PDF
	docbook2rtf -c <catalog> -d <stylesheet>#print <filename>.docbook
		to convert to RTF

For example, you can try to convert the KDE template file for DocBook documents:

	docbook2html \
		-c /usr/share/apps/ksgmltools/catalog \
		-d /usr/share/apps/ksgmltools/stylesheets/kde.dsl#html \
		template.docbook

This should produce a new directory named HTML/ that contains the resulting HTML files. If you get bored with typing -c parameter, you can add a pointer

	CATALOG /usr/share/apps/ksgmltools/catalog

to the file /etc/sgml/sgml-docbook-3.1.cat. This is not done automatically because it would require root privileges.

Another tool is used for translations: sgmldiff.pl. It verifies if the DocBook markup has not been altered by the translation process. For example, you can type:

	perl sgmldiff \
		 kdebase/doc/konsole/index.docbook \
		 kde-i18n/it/docs/kdebase/konsole/index.docbook

sgmldiff has a number of options to refine problems detection. Type

	sgmldiff --help

to have more information on this.

The next step

Now you should have everything necessary to build existing KDE documentation, or to write and translate KDE documentation.

Have a lot of fun with DocBook!

You can return to the main page.


Last updated on 25 October 2000
Maintained by Eric Bischoff.