1.8. Anatomy of a DocBook Tag

XML, just like it spredecessor SGML, is a generic markup language. It is a meta-language syntax to define a convenient vocabulary for the application domain being dealt with. In science, in particular, software, DocBook offers a large choice of elements that are useful for marking up and producing good and precise documents in computer science, etc.

However, DocBook being an instance of an XML language, it obeys the XML syntax, which introduces elements, attributes, and entities as main components. For example, the XML start tag <chapter id="introduction"> has the element name chapter and the attribute id. The element influences the rendering of the text inside the element, while an element's attributes can further modify the behaviour or meta-information associated with the element. An element is closed with an XML end tag, for instance </chapter">. In the case of the chapter element the element contents, i.e., all text included within the starting and closing tags should be treated as a chapter, while the id attribute labels the chapter so it can be linked to or used as a file name when DocBook is translated to another format.

An element can also be empty, i.e., have no contents. For such an element we use a specific syntax, e.g. for a xref element, <xref linkend="foo" />.

Most DocBook tags contain a common set of attributes. The most often-used such common attributes are lang, which specifies the language of the data inside the element, id labels an element so that it can be referenced by other elements, and role, which allows one to subclass an element, to make it information-wise more specific.

As an XML language instance all DocBook elements must have a start and an end tag, or be empty (please forget your SGML or HTML habits, where end-tags are not always required). You should also make sure to use the proper case for element names, entities, and attribues. Detailed information about all element names and their attributes is in the DocBook reference guide.