Next Previous Table of Contents
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.
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
http://www.sgmltools.org), 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:
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:
ksgml2html additionally
When creating a KDevelop project, the subdirectory docs/en already contains the english index.sgml documentation file and
the already produced output HTML files. Those are already included into the project as well as their installation destination is preset
to the KDE HTML directory. The documentation is already adapted to your project name, version number and the programmer's information.
Further, the output covers the index.html file containing the table of contents (which is opened by KDE Help when the user requests
help); an installation introduction and a copyright information with regards to the GPL license.
Therefore, when extending the documentation, you only have to add the information that is specifically to your project. Mind that for
KDE projects you have to run "Make Doc-Handbook" from the "Project" menu again after the project is created. The index.sgml file is
again processed by ksgml2html and the KDE-Style is added to the HTML output. Open the docs/en directory in the RFV
and add the logotp3.gif file to the project by the context-menu; then set the file properties correctly to install the logo file
into the same location the HTML files will go - to $(kde_htmldir)/en/<your_project>/logotp3.gif.
This section has been added because SGML (or to be more precise: the LinuxDoc DTD) still seems to be difficult for beginners that want to write documentation. When looking at some KDE applications, I have seen some that contain an sgml file which is the template - but the author went over to edit the html output instead of the sgml file. This results in problems that translators have - if they want to provide documentation for your application in their native language, they will have to edit each file as well in HTML and this makes it impossible to reuse the documetation for other formats not only in the english version but all internationalized versions as well. You see that this is very short-thinking and a bad situation; personally I think that this results from the author's knowledge of HTML but not of SGML. As most will try to avoid learning a new formatting language, they will use the HTML output as the template that they edit. If you once find out how easy (and useful) SGML with LinuxDoc is, you will know that it's worth to learn a few more tags that built the SGML formatting.
The following sections will therefore introduce you to the most important parts of an LinuxDoc sgml file and how to extend your documentation.
An SGML file, whatever DTD it may use, always has to start with the DTD declaration. This tells the SGML parser about which DTD to use. Therefore, the first tag (a bracketed expression like <yourtag> your contents </yourtag>) is always the DOCTYPE:
<!doctype linuxdoc system>
That tells your sgml formatter that it shall use the LinuxDoc DTD.
Now, when using the LinuxDoc, the next tag is the start tag for the document style type. The LinuxDoc DTD offers a whole set of types that you can select from, dependent on the purpose of your document or it's legth. Available formats are:
<notes> for short explanations<article> for writing articles with abt. 10-20 pages (suggested). This is used by the templates of KDevelop and most KDE
applications.<report> for articles that are longer than an <article> type<book> for writing large books - the KDevelop handbooks have been written using this document type<slides> for slideshows. This is useful for presentations. You will use LaTeX as output format in most cases, of
course.<letter> for normal letters<telefax> for a telefax<manpage> for a manpageMind that these are only describing how the document structure will look like in general - not the actual output. As mentionend, the KDevelop default generated template is using the <article> structure. This is used by most applications except KDevelop itself which uses the <book> format. In the HTML output this doesn't really matter much - but for LaTeX e.g. this makes much difference. The handbooks are really "books" with separate pages for each chapter as the main difference.
What follows is that the end of the sgml file must have an end-tag for the document structure type - for <article> this would be </article>.
Now, after the document structure follows a section that describes all entries usually found on a titlepage. The predefined template
doesn't use this explicitely but only sets the information for <title>, <author> and <date> as this
lasts for most purposes. Especially when using a <book> structure, you probably want to define a complete titlepage. The
following lists the according tags for this, taken from the sgml source of this handbook:
<!doctype linuxdoc system>
<book>
<titlepag>
<title>The KDevelop Programming Handbook
<subtitle>The User Guide to C++ Application Design for the K Desktop Environment (KDE) with the KDevelop IDE, Version 1.2
<author>
<name>Ralf Nolden <htmlurl url="mailto:Ralf.Nolden@post.rwth-aachen.de"
name = "<Ralf.Nolden@post.rwth-aachen.de>">
<inst>The KDevelop Team
<date>Version 1.2 , March 21, 2000
<abstract>
This handbook itself is part of the KDevelop Integrated Development Environment
and is therefore also licensed under the GNU General Public License;
see <ref id="Copyright" name="Copyright"> for more information.
</abstract>
This covers all a normal titlepage usually contains. The <author> tag can also include a <thanks> tag to insert
some thanks to co-authors, lecturers etc. <inst> represents the institute or company for which the author wrote the
documentation; you could also use your team-name here like I did. <abstract> now covers an short description that is placed
on the titlepage as well. This is somewhat annoying on a printed version where this section would be printed on the back of the title
page where the copyright notice etc. are collected; this can be changed for LaTeX output when editing the TeX file.
The LinuxDoc DTD defines a set of tags for various indices as they occur in usual documents. Those are:
The according start-tags don't necessarily require an end-tag; they're inserted just after the titlepage before the actual beginning of the document with the according sections or chapters.
Now, when it comes to indexing keywords for an index that is placed at the end of the document, you are provided four different tags; two which leave the indexed phrase within the page and two for index entries that are not displayed:
These tags are ignored by all backends (the tool that does the mapping of the sgml-tags to their document format) except
sgml2latex, which generates an index file index.idx that can be turned to a TeX-index with makeindex index.idx. The
index itself can be inserted into the TeX output file afterwards with \printindex. I patched my mapping for the LaTeX output to do
this automatically (but still don't know how to include the index into the table of contents...).
Now, after explaining most details of the general structure, we're coming to the actual document contents. Dependent on the document
structure type, has to start with a <sect> tag, when using <book> you have to start with <chapt>
for the chapters.
After the start tag, you can structurize each chapter with <sect1>, <sect2> etc. up to the allowed level of
sub-sections (4).
The chapter start tag is followed by the chapter's title. There, you have the additional choice to use <title> and
</title> for the chapter's title (optional). Now, afte the title of the chapter, you have to add a <p> tag to actually
start with the subsection's contents. Within that, you have almost all means to format your document with list, enumerations,
itemizations and description lists. Further, quotations, code snippets and the like can be inserted by tags; see you sgmltools
documentation guide for a complete list. What you should look for is the "special characters" section. This contains all valid
replacements for characters that are different from the usual alphabet like brackets, slashes and symbols like trademark etc. With the
given tags you can structurize your text contents as you application documentation requires.
Calling help in dialogs is often done by adding a Help-button; then you add a slot that is called when the button gets pressed. Within the slot implementation, call
kapp->invokeHTMLHelp( QString aFilename, QString aTopic );
where aFilename is the the filename to be called within your HTML documentation directory of the application; e.g index-3.html.
aTopic then is the topic that is to be called. The hash prefix is automatically added; just enter the chapter you want to have on
this page, actually this would be a subsection's name.
Next Previous Table of Contents