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).  | 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: 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. 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. | 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. | |
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: 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 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: 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. | |
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." | 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 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. | 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: Some tags have multiple property names and some have none. | 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 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.
Table 15.1. DocBook Meta-Information Tags | Tag | Contents of Tagged Region |
|---|
| BookInfo | Information about the book (author, date written, and so on) | | AuthorGroup | Information about all authors | | Author | A single author | | KeyWordSet | A set of keywords relevant to the document's contents | | Keyword | A single keyword | | Date | The date the document was created or revised | | ReleaseInfo | The version of the document | | Abstract | An abstract for this document |
Table 15.2. DocBook Document Structure Tags | Tag | Contents of Tagged Region |
|---|
| Book Id="id" Lang= "language" | A book of documentation identified by id, written in the language language | | Chapter | One chapter of the book | | Title | The title of a chapter, section, and so on | | Sect1, Sect2..Sect5 | A section, subsection, and so on of a chapter | | Para | A 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 | Tag | Contents of Tagged Region |
|---|
| Emphasis | Emphasized Text | | ItemizedList | An unnumbered list | | ListItem | An element in a list | | KeyCombo | A combination of input actions (for example, Ctrl+Q) | | KeyCap | Something printed on a keyboard key (for example, Ctrl) | | Application | The 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/. | |
| |
