15.2. Documenting Applications

For creating application documentation, the KDE project uses the DocBook Document Type Definition (DTD), a specific instance of the Standard Generalized Markup Language (SGML). DocBook was created by the Organization for the Advancement of Structured Information Standards (OASIS), a nonprofit group, to be a standard suitable for writing technical documentation. The DocBook DTD specifies how to mark up text files so that they can be processed into good-looking technical documentation. The KDE team has created a custom DocBook style sheet (which redefines the layout of the document a bit) that can be used to turn your document into standard KDE documentation.

Your documentation should be included with your application distribution (see Chapter 16, "Packaging and Distributing Code" for more information) and installed in $KDEDIR/share/doc/HTML/lang/appname, where lang is a two-letter language code (for example, en is the code for English) and appname is the (all lower-case) name of your application (for example, ksimpleapp). When the user chooses the entry Contents from your application's Help menu, this documentation will be loaded (in particular, the file $KDEDIR/share/doc/HTML/lang/appname/index.html will be loaded by the application KHelpCenter).

Note

Prior to version 2.0, the KDE project used the LinuxDoc DTD for its documentation. You may find documentation in this format, but you should write all your new documentation using DocBook.

If you have ever written HTML, you should be fairly comfortable with DocBook. Like HTML, DocBook documents contain mark-up tags that indicate what the various parts of the document are. It is up to a formatting program to turn this document into presentable material. The structure of a DocBook (indeed, any SGML document) is free format, which means that extra spaces (or other whitespace characters) between words or tags are ignored. The space serves only to separate different elements of the document, such as to separate one word from another. All formatting is done by the formatting program.

Consider the following document snippet:


   1 
   2  <title>Technical Documentation</title>
   3  <sect1 id=Intro>
   4   <para>
   5     Welcome to a technical subject. Have no fear, this documentation will
   6 make it clear…or, at the least, it will be available in PostScript,
   7 PDF, and HTML!
   8   </para>
   9  </sect1>

Technical Documentation is the document's title, as you might have guessed. The string <title> is an opening tag; it marks the beginning of a section containing the title. The string </title> is a closing tag and marks the end of that section. All the information in a DocBook document falls between some type of opening and closing tags.

In the section "Writing DocBook Documentation for KDE," I discuss some of the tags that are available and examine a sample document.

15.2.1. Obtaining and Installing KDE DocBook Tools

You can retrieve everything you to need start working with DocBook from the KDE FTP site (ftp://ftp.kde.org) or one of its mirrors. In the directory pub/kde/devel/docbook/, you will find the following DocBook packages:

  • sgml-common

  • jade

  • docbook

  • stylesheets

  • psgml

  • jadetex

The first four are required to use DocBook. psgml is an add-on for Emacs that makes creating DocBook documents easier. jadetex is needed if you intend to create LaTeX versions of your document and process them (into PostScript, for example). The KDE customizations are included in the kdelib package.

The DocBook packages are available in RPM, SRPM, and .tgz formats. You should choose the one that you prefer and that is appropriate for your system.

If you choose RPM format, you can install the packages with the command rpm -ivh packagename. Install the packages in the order given in the preceding list.

Note

You will need to uninstall any older versions of these packages.

If you choose SRPM or .tgz format, you should follow the usual compiling and installation procedures.

15.2.2. Processing DocBook Documentation

DocBook files are processed with the utility called jade. Access to jade is given through the front end scripts jw.

You can use jw to convert your DocBook file to HTML, Rich Text Format (RTF), TeX, Postscript, or other formats. You use this script to process your DocBook file in this way:


   1 
   2 jw -o HTML -c /usr/share/sgml/docbook/sgml-dtd-3.1/catalog -c \$KDEDIR/share/apps/ksgmltools/catalog -d \$KDEDIR/share/apps/ksgmltools/stylesheets/kde.dsl#HTML docBookFileName

where docBookFileName is the name of the source file (for example, ksimpleapp.docbook, a file that is discussed in the next section). Executing this command produces a directory called HTML, which contains the HTML files produced from docBookFileName. These files will be formatted in a standard KDE style.

The file kde.dsl, in describing the formatting of the resulting HTML file, requests that an image called logotp3.png be displayed. To give your newly-created HTML files access to this graphic, type


   1 
   2 mkdir HTML/commoncp $KDEDIR/share/doc/HTML/default/common/logotp3.png HTML/common

A convenient script called makehtml that executes these three commands (jw, mkdir, and cp) is included on the Web site. It is used this way:


   1 
   2 makehtml outputDirectory docBookFileName

The first parameter, outputDirectory, is the name of a subdirectory to be created to hold the ouput files. To reproduce the commands above, use HTML as the outputDirectory.

15.2.3. Writing DocBook Documentation for KDE

The best way to start learning DocBook is to look at an example. The basic structure and tags are simple. Listing 15.2 shows a simple DocBook file called ksimpleapp.docbook, which documents KSimpleApp, the application created in Chapter 2, "A Simple KDE Application."

Note

Since DocBook documents (see Listing 15.2) are plain text, you may use any text editor to create them.


Example 15.2. ksimpleapp.docbook: DocBook Documentation for KSimpleApp

   1 
   2   1: <!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN">
   3   2:
   4   3: <Book Id=KSimpleApp Lang=en>
   5   4:
   6   5: <BookInfo>
   7   6:
   8   7: <Title>KSimpleApp Documentation</Title>
   9   8:
  10   9: <AuthorGroup>
  11  10: <Author>
  12  11: <Firstname>Joe</Firstname>
  13  12: <Surname>Developer</Surname>
  14  13: </Author>
  15  14: </AuthorGroup>
  16  15:
  17  16: <KeywordSet>
  18  17: <Keyword>KDE</Keyword>
  19  18: <Keyword>ksimpleapp</Keyword>
  20  19: </KeywordSet>
  21  20:
  22  21: <Date>1/1/2000</Date>
  23  22: <ReleaseInfo>1.0.0</ReleaseInfo>
  24  23:
  25  24: 
  26  25: <Abstract>
  27  26:  <Para>
  28  27:    This is a short example of how DocBook is used to document KDE
  29  28: Applications.  The basic DocBook tags are used here, but there are many
  30  29: more!
  31  30:  </Para>
  32  31: </Abstract>
  33  32:
  34  33: </BookInfo>
  35  34:
  36  35: <Chapter Id=introduction>
  37  36:  <Title>Introduction</Title>
  38  37:  <Para>
  39  38:  <Application>KSimpleApp</Application> says "Hello!" and allows
  40  39: the user to reposition text.
  41  40:  </Para>
  42  41:
  43  42: <Sect1 Id=ksimpleapp-revhistory>
  44  43:  <Title>KSimpleApp Revision History</Title>
  45  44:  <Para>
  46  45:   <ItemizedList>
  47  46:    <ListItem><Para>1.1 - Added a combobox to the
  48  47:     toolbar in Exercise 2.1</Para></listitem>
  49  48:    <ListItem><Para>1.0 - First version</Para></listitem>
  50  49:   </ItemizedList>
  51  50:  </Para>
  52  51: </Sect1>
  53  52: </Chapter>
  54  53:
  55  54: <Chapter Id=installation>
  56  55:  <Title>Installation</Title>
  57  56:  <Para>
  58  57:   This Application does <Emphasis>not</Emphasis> want to be installed.
  59  58:  </Para>
  60  59: <Sect1 Id=getting-ksimpleapp>
  61  60: <Title>Obtaining KSimpleApp</Title>
  62  61:  <Para>
  63  62: <Application>KSimpleApp</Application> can be found in Chapter 2 and on
  64  63: the Web site for this book.
  65  64:  </Para>
  66  65: </Sect1>
  67  66: 
  68  67: <Sect1 Id=requirements>
  69  68: <Title>Requirements</Title>
  70  69:  <Para>
  71  70: You will need KDE 2.0 to run this Application.  Please visit
  72  71: <ulink url=http://www.kde.org>
  73  72:   The KDE home page</ulink> to find out about KDE 2.0.
  74  73:  </Para>
  75  74: </Sect1>
  76  75:
  77  76: <Sect1 Id=compilation>
  78  77:  <Title>Compilation and installation</Title>
  79  78:  <Para>
  80  79: Compile <Application>KSimpleApp</Application> with g++.
  81  80:  </Para>
  82  81: </Sect1>
  83  82:
  84  83: <Sect1 Id=configuration>
  85  84:  <Title>Configuration</Title>
  86  85:  <Para>
  87  86: No configuration is needed.
  88  87:  </Para>
  89  88:
  90  89: </Sect1>
  91  90:
  92  91: </Chapter>
  93  92:
  94  93: <Chapter Id=using-kapp>
  95  94:  <Title>Using KSimpleApp</Title>
  96  95:
  97  96:  <Para>
  98  97: <Application>KSimpleApp</Application> is simple to use.
  99  98:  </Para>
 100  99:
 101 100: <Sect1 Id=kapp-features>
 102 101:  <Title>KSimpleApp features</Title>
 103 102: 
 104 103:  <Para>
 105 104:    Well, if there were any, we'd present them here.
 106 105:  </Para>
 107 106:
 108 107: </Sect1>
 109 108: </Chapter>
 110 109:
 111 110: <Chapter Id=commands>
 112 111: <Title>Command Reference</Title>
 113 112:
 114 113: <Para>
 115 114: Type <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
 116 115: to quit or <keycombo><keycap>Ctrl</keycap><keycap>r</keycap></keycombo>
 117 116: to reposition the text.
 118 117:
 119 118: </Para>
 120 119:
 121 120: </Chapter>
 122 121:
 123 122:
 124 123: <Chapter Id=credits>
 125 124:
 126 125:  <Title>Credits and License</Title>
 127 126:  <Para>
 128 127: <Application>KSimpleApp</Application> is Copyright 2000 by Joe Developer
 129 128: <Email>jdevel@kde.org</Email> and
 130 129: was written by Joe Developer and
 131 130: is available under the <ULink Url=common/gpl-license.html>
 132 131:   GNU GPL</Ulink>.
 133 132:  </Para>
 134 133:
 135 134: </Chapter>
 136 135:
 137 136: </Book>

This document starts off with the line


   1 
   2 <!DOCTYPE book PUBLIC  "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN">

which tells the processor, jade, that the document is a book (not an article, another DocBook type not used in KDE application documentation and not discussed here) and that it should use the DTD called -//KDE//DTD DocBook V3.1-Based Variant V1.0//EN. This DTD is an extension of the DocBook V3.1 DTD that adds support for PNG graphics. It is part of the customization of the DocBook installation performed when you installed kdesdk/ksgmltools.

Note

PNG graphics are preferred over GIF for use in KDE documentation because no part of PNG is patented.

All the DocBook tags take the following form:


   1 
   2 <tag propertyname=property>
   3 …
   4 </tag>

Some tags have multiple property names and some have none.

Note

It is important to use the proper case for tags and to use closing tags even when not strictly required by SGML. Doing so will make it easier to port your documentation to the XML (Extended Markup Language) DTD that will eventually become the KDE standard.

To process the document in Listing 15.2, use the command


   1 
   2 makehtml HTML ksimpleapp.docbook

This will generate the HTML documentation in a directory called HTML. Figure 15.2 shows the output as viewed by Konqueror.

The meanings of many of the tags in Listing 15.2 may seem obvious, but Tables 15.1-15.3 are a complete summary of them divided into three categories: meta-information, structure and formatting. These tags should be sufficient to write much of the documentation you will need to write.


Figure 15.2. Screenshot of the HTML output created from ksimpleapp.docbook as viewed by Konqueror.



Table 15.1. DocBook Meta-Information Tags

TagContents of Tagged Region
BookInfoInformation about the book (author, date written, and so on)
AuthorGroupInformation about all authors
AuthorA single author
KeyWordSetA set of keywords relevant to the document's contents
KeywordA single keyword
DateThe date the document was created or revised
ReleaseInfoThe version of the document
AbstractAn abstract for this document


Table 15.2. DocBook Document Structure Tags

TagContents of Tagged Region
Book Id="id" Lang= "language"A book of documentation identified by id, written in the language language
ChapterOne chapter of the book
TitleThe title of a chapter, section, and so on
Sect1, Sect2..Sect5A section, subsection, and so on of a chapter
ParaA single paragraph

The property id is used when processing the document to identify the book. It may, for example, be used to place a mark in an HTML document naming the section id: <A NAME="id">.


Table 15.3. DocBook Formatting Tags

TagContents of Tagged Region
EmphasisEmphasized Text
ItemizedListAn unnumbered list
ListItemAn element in a list
KeyComboA combination of input actions (for example, Ctrl+Q)
KeyCapSomething printed on a keyboard key (for example, Ctrl)
ApplicationThe name of an application
ULink Url="url"An anchor for the URL, url

DocBook has many more tags than those presented. They allow you to create rich, structured documents that can easily be processed by a computer. You can find out more about them from the tutorial at http://i18n.kde.org/doc/crash-course/ or at the official DocBook home page at http://www.oasis-open.org/docbook/.