Extending the Documentation with SGML

O Manual de Programação do KDevelop: O Guia do Utilizador para Desenvolvimento de Aplicações C++ para o Ambiente de Trabalho K (KDE) com o ambiente de trabalho KDevelop, Versão 2.1
Prev |  | Next

# Capítulo 9. Extending the Documentation with SGML

Due to the fact that projects often lack a complete set of user documentation, all KDevelop projects contain a pre-build handbook that can be easily adapted; therefore fulfilling another goal of KDE: providing enough online-help to support users that are not familiar with an application. This chapter therefore introduces you on how to extend the provided documentation template and what you have to do to make it available to the user.

# 9.1. Why SGML ?

SGML (Standard Generalized Markup Language) itself is a language with which one can write specifications of a markup language, but not a markup language itself. The specification for that markup language is called a DTD (Document Type Definition) which contains the structure of a document and the valid tags to use. Then, an SGML system provides a set of replacement files that translate the DTD tags into the desired output - and this is the way it works. The most used output is probably HTML to provide online help through web-browsers in a time where Internet standards are available even on single-desktop systems. KDE makes extensive use of HTML documentation by it's KDEHelp application where all KDE applications are listed and give access to their user manuals as well as by a helpmenu where the user can access the online-help directly from within the application.

Now, KDE (and therefore KDevelop) use the SGML-Tools 1.x package (see \|\|), which was formerly known as the LinuxDoc package. It contains a DTD called `LinuxDoc`, and a set of mapping files for various output transformations and the necessary tools that actually do the replacement of `LinuxDoc` tags. The LinuxDoc DTD is based on the Qwertz DTD which itself was written to provide a good mapping (replacement of tags) especially for the LaTeX text system, therefore is very usable to produce a good printed output. The package then got it's name from the usage for writing documentation for the LDP (Linux Documentation Project) and has only changed it's name due to the fact that it is an sgml-system that does not necessarily have a direct connection with the Linux project but can be used on any Unix-System; you can as well write your own DTD and mappings if you ever like to.

In the meantime, another DTD as been made up to fit the same purpose: the "DocBook DTD". DocBook has obviously some advantages over the LinuxDoc DTD mostly in providing better tags and mappings for tables and the inclusion of graphics, but that is possible with LinuxDoc as well. The SGML-Tools therefore switched to provide support for the DocBook DTD in the 2.x version series, which also includes a converter to produce a DocBook sgml from a LinuxDoc master.

The current state of KDE development is that we're still using the LinuxDoc DTD for some reasons:

- writing LinuxDoc documentation is easy

- installing the SGML-Tools 1.x for using LinuxDoc is even much easier

- KDE provides an additional tool called `ksgml2html` which adds the KDE documentation style to the output produced by the SGML-Tools' 1.x `sgml2html` converter to produce HTML output.

I personally have encountered that while writing the KDevelop handbooks using the LinuxDoc DTD is very easy and lasts for the requirements I need for writing the documentation. The learning curve is very high, so you will be a sgml-tools/LinuxDoc DTD guru within days and that will save you a lot of time to work yourself into any formatting system such as TeX for printed output for your documentation or a markup language for HTML output.

One major reason for still using the sgml-tools 1.x is that most distributions ship with the package and all additional tools you need for other output formats. This makes the installation as easy as possible and the writing itself isn't very complicated as you will see. The output formats you can achieve witht the sgml-tools are:

- HTML output, with KDE look'n feel when using `ksgml2html` additionally

- plain text

- GNU info,

- Lyx format

- TeX, DVI, PostScript and PDF format

- Rich Text Format (RTF)

Prev | Home | Next
The "What's This...?" Button |  | What the Documentation already contains