The tags covered in this section are listed below.
Book - Book |
Chapter - Chapter of a Book |
Title - Text of a heading or the title of a block-oriented element |
Para - Paragraph |
Example 3-1. An example of a minimal DocBook Book file
<!DOCTYPE Book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN"> <book lang="en" id="kapp"> <bookinfo> <title>The Kapp Handbook</title> <bookinfo> <chapter id="introduction"> <title>Introduction</title> <para></para> </chapter> </book> |
The above example shows a skeleton of all of the required structural tags. The first tag in any DocBook file is the DTD declaration which indicates which DTD to use to process this document. KDE documentation uses an extension to the standard DocBook 3.1 DTD which adds support for PNG graphics to the graphics-related DocBook tags. Next comes the content model, which is <Book> for all KDE documentation. Note the use of the Lang and ID attributes in the Book tag. The language attribute should always be used to make it easy to determine what language in which the document is written. Human-readable (not numerical) ID attributes for <Book>, <Chapter>, and <Sect> tags are required for two reasons:
Labelling all of the sections of your document allows you to easily cross-reference your document with hyperlinks.
Jade uses the ID's of Chapters to name the output files, so if you do not include ID's for all your Chapters, the file names will be different each time the docs are updated, which wastes space in CVS.
After the <Book> tag comes the meta information for the document which is encapsulated within the <BookInfo> tag. This information will be described in more detail in the Meta Information section. Then come the chapters of your book, which may contain one or more section tags (<Sect1> - <Sect5>). Chapters and sections must contain at least a <Title> and an empty <Para> tag. To make it easier to visualize how the sections relate to one another, refer to the documentation template.
Content in DocBook is contained within a <Para> tag, which is very similar to the <P> tag in HTML and Linuxdoc except that it must always have a closing </Para> tag.