|
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.
checkXML button from the Tools toolbar. It is a front
end to the checkXML
command line utility. The errors in the docbook file will be displayed in the
Messages sidebar, in the bottom part of Quanta's
main window. No output usually means no errors. If you find the list of
errors is too big, do not panic: fix the first one, save the file, and run
checkXML again.
meinproc button (on the Tools
toolbar). It is also a front end to a command line utility, in this case,
meinproc.
The html files are generated in the same folder where the docbook file is.
lists,
tables and
images.| 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 entities.tag file
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
/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
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:
|
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:
|
Restart Quanta.
 |
| 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.