Writing documentation is a great way to start contributing to KDE. While the KDE documentation team gladly accepts contributions in plain text, the format used for writing the applications manuals is called docbook. Docbook is a format based on tags, which describe the format and specifications of the document.
If you want to learn about docbook, or don't know how to start, the KDE Documentation Primer was created to guide new writers, and offers information such as what to write about, English usage guidelines, how to get the documentation sources, a docbook introduction, a docbook reference guide and more.
Quanta is widely recognized as the most advanced free software web development environment. But a lot of people do not know that Quanta is a friendly editor for all XML documents (and therefore for docbook).
Quanta offers features like syntax highlighting, tag autocompletion, autoclosing and code folding. But lately, the developers have been adding features specific for docbook, and ironing out the last remaining bugs. Here we try to show you why it is a good idea to use Quanta as your docbook editor.
|Quanta's main window|
Below you can find more information about some other interesting features available for docbook editing: the tag editor sidebar, the entities autocompletion, the documentation sidebar and the docbook toolbar (complete with table and list wizards, ui elements, admonitions, KDE tools and other standard tags, and present in versions starting from Quanta 3.4).
The docbook toolbar offer easy access to the most common docbook tags and to Kommander dialogs. Just hover the mouse over a toolbar button to know what tag it adds, or what action it performs.
If you open a KDE docbook document, the KDE docbook toolbar should be loaded automatically. If you are starting from scratch, choose the DTD->Change the DTD... menu item, and select one of the KDE docbook DTEPs to load the toolbars.
|Quanta's docbook toolbar|
A few Kommander dialogs were created specifically to support KDE documentation writers.
|Note:||Depending on the version of Quanta, the checkXML and meinproc scripts may present bugs. Starting from the KDE 3.4.2 release, these bugs should not appear anymore. If you experience problems using an older release, (in special if Konqueror is not starting up when using the meinproc script or there is always no output when using the checkXML script), you can get and install the updated docbook scripts from kde-files.org to solve these issues.|
|Quanta's docbook table wizard|
The tag or attribute editor is located on the right sidebar, and it shows the available attributes for the tag which is currently being edited. The tag editor helps you to edit the attributes for the current tag: just click on the Value cell of any attribute to edit it.
|Quanta's attribute editor sidebar|
Another useful feature is the documentation sidebar, which allows you to download and use documentation packages offline reference. The KDE Documentation Primer is available offline, using Quanta's documentation sidebar. Just grab and install the documentation package, at kde-files.org. The documentation sidebar is on the right side of the main window.
|Quanta's documentation sidebar, showing the KDE Documentation Primer|
Entities are variables that expand to some other text when the docbook is processed. They are in the form &entity-name;, and used for licenses, application names (for instance &quanta; is replaced by <application>Quanta</application>), etc...
Quanta offers autocompletion for entities. However, this feature is hardly useful without the KDE entities definitions. To generate the entities list for KDE, follow the procedure below:
|Important:||The entities autocompletion feature suffered from known bugs up to the 3.4.1 release. However, these bugs should be fixed now, starting from Quanta 3.4.2.|
Procedure:Generating and installing the
Open Quanta. Choose the DTD->Load & Convert DTD menu item.
Now, we have to select the right dtd file to convert.
On the dialog, select the KDE installation folder (usually
/opt/kde3. The dtd file we want is named
Select it and press OK. A new Document Type Editing
Package (DTEP) for kdex will be created.
If you don't know which is the KDE installation folder, enter
on a terminal application. The output of this command is the KDE installation folder. To find out which is the KDE configuration folder (
Now that you have converted the dtd, you can use it directly,
by choosing the DTD->Change the DTD... and selecting the
kdex dtd. But the best solution is to install the
entities.tag file for use with the KDE
docbook dtds, so that you can use both the KDE docbook toolbars and entities
entities.tag file from the
kdex dtep folder to the
folder. These folders are under
KDEHOME is the folder that contains your
KDE settings and application data (usually
You can copy the
|Quanta's entities auto-completion feature|
Quanta is part of the kdewebdev module, which is released as part of KDE. Binary packages are available for the majority of the distributions. Quanta can be easily extended to support custom scripts, toolbars and documentation sidebars. For more information, check the application handbook.
This document was created by Carlos Leonhard Woelz, and is licensed under the GNU Free Documentation License.