Installation guide to 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 ;-).
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.
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.