Quanta as a Docbook Editor

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 Features

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.

A screenshot of Quanta's main window
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).

Docbook Toolbar

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.

A screenshot of Quanta's docbook toolbar
Quanta's docbook toolbar

A few Kommander dialogs were created specifically to support KDE documentation writers.

Note: Depending on the version of Quanta, the The checkXML dialog iconcheckXML and The meinproc dialog iconmeinproc 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.
A screenshot of Quanta's docbook table wizard
Quanta's docbook table wizard

Tag Editor

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.

A screenshot of Quanta's attribute editor sidebar
Quanta's attribute editor sidebar

Documentation 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.

A screenshot of Quanta's
documentation sidebar
Quanta's documentation sidebar, showing the KDE Documentation Primer

Entities Autocompletion

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 entities.tag file

  1. Open Quanta. Choose the DTD->Load & Convert DTD menu item.

  2. Now, we have to select the right dtd file to convert. On the dialog, select the KDE installation folder (usually /usr or /opt/kde3. The dtd file we want is named kdex.dtd under share/apps/ksgmltools2/customization/dtd/. Select it and press OK. A new Document Type Editing Package (DTEP) for kdex will be created.

    Tip: If you don't know which is the KDE installation folder, enter
    $kde-config --prefix
    on a terminal application. The output of this command is the KDE installation folder. To find out which is the KDE configuration folder (KDEHOME, needed later) enter the command below:
    $kde-config --localprefix
  3. 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 autocompletion.

    Copy the entities.tag file from the kdex dtep folder to the kde-docbook-4.1.2 dtep folder. These folders are under KDEHOME/share/apps/quanta/dtep, where KDEHOME is the folder that contains your KDE settings and application data (usually ~/.kde).

    Tip: You can copy the entities.tag file to the right location by entering the following command in a console application:
    $cp `kde-config --localprefix`/share/apps/quanta/dtep/kdex/entities.tag \
    `kde-config --localprefix`/share/apps/quanta/dtep/kde-docbook-4.1.2/entities.tag
  4. Restart Quanta.

A screenshot of Quanta's entities auto-completion feature
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.