Chapter 1. Knowing DocBook’s Structure

DocBook has a wide variety of elements covering different semantics: from structural elements like book, chapter, appendix, to block elements like orderedlist, table, figure, to inline elements like filename, quote, or link. All of these elements are well covered in The Definitive Guide. This chapter shows more of the unknown parts and how to avoid pitfalls and improve consistency throughout your documentation.

Table of Contents
1.1. Introduction
1.2. Selecting the Right Top Level Element
1.3. Modularize Your Document with XIncludes
1.4. Mastering Multiple Indices
1.5. Distinguish Between section and sectn Elements
1.6. Using Lists
1.7. Incorporating Code Listings
1.8. Incorporating External Files in Code Listings
1.9. Inserting Remarks
1.10. Knowing the Difference Between Cross-References and Links
1.11. Inserting Cross-References
1.12. Choosing Between Link Methods
1.13. Inserting Inline Quotes
1.14. Markup References to Man Pages

To successfully use DocBook you basically need to know how to “transform” your ideas into DocBook’s structure. Usually, the DocBook elements are mostly self-explanatory: if you want to write a book, use book, for a chapter use chapter, and so on. All you need is covered in the Definitive Guide with examples and the reference of all elements.

However, a reference usually does not cover the finer details. For example, should I use sect1 or section? How do I modularize my documentation? What is the recommendation to use multiple indices?


Project@GitHubIssue#6