DocBook has hundreds of elements to choose from. We try to use the smallest subset of them as we can, but it's still a pretty long list. The reference pages of DocBook - The Definitive Guide (TDG) by Normal Walsh discuss each element and its permissible parents, children, and attributes. I strongly recommend downloading a copy of this book and bookmarking it in your favorite browser if you plan to edit our documentation very often. For quick reference, I've listed the 130 or so tags of the elements we commonly use in the Frequently Used DocBook Tags appendix of this manual, along with short descriptions. I've tried to arrange some of them within their categories hierarchically, but it is futile to try to show every possible permutation. They are well documented and listed alphabetically (with all the other DocBook tags) in DocBook TDG.

The tags are arranged in the appendix like this:

Most elements have attributes, which can be modified for various purposes. Attributes are specified in the start-tag of an element, and their syntax typically looks like this:

<elementname attributename="attributevalue">

For example, a cols attribute that specifies 2 columns for the Tgroup element of a table would look like this:

<tgroup cols="2">

The attribute we use most frequently is id, which lets us identify elements of the document so that they can be linked to. For example, the start tag for the copy function reference entry in the Gamma manual looks like this:

<refentry id="re-copy">

To avoid duplication of id attributes, our documents follow a convention where the first two letters (four for Cascade Compatible drivers in the bookset) of the id attribute identify the book or part of a book, followed by a dash, followed by the exact name of the chapter or section, all written in lower case. (This is because XML attributes must be all lower case.) The codes we use are as follows:

Guides and Complete Manuals

Indices, References, Examples, Commands, etc.

When a document is processed into HTML chunks, any element that would start a new page, such as a chapter, sect1, appendix, etc. is named according to its id attribute. If there is no id attribute, the processor assigns that element a unique name, consisting of a letter followed by one or more integers. Whenever the document is edited and content is added or deleted, this name can change. Since our Cogent Documentation bookset eventually gets published on the web, people are bookmarking and/or linking to it, so these pages should maintain constant names. Thus, every part, chapter, sect1, reference, appendix, and any other element that starts a new page should have an id assigned to it. The only exceptions to this are indices and copyright pages, which, because of processing reasons, should not or cannot have assigned ids.