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.
- 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
sectionandsectElementsn - 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
1.1. Introduction
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?