The DoCookBook

Recipes for DocBook Developers

Thomas Schraitle


Draft Version v0.7

Draft Ahead!

This book is a draft and is still a work in progress. You will find funny typos, mistakes in English grammar (being a native German speaker) annoying inconsistencies, missing topics, and plain errors. Nevertheless, I hope the topics are useful and a source of ideas.

Visit this site from time to time and see how the book grows and how more and more of these irritants vanish. To accelerate this process, send me praise, critisism, patches, donations, or even write a topic. Read Section 6, “Contribute to the Book” to find out more about supporting this project.

Table of Contents

1. Audience
2. DocBook 4 or 5?
3. Further Readings
4. Typographical Conventions
5. Feedback
6. Contribute to the Book
7. A Few Words About Piwik
8. Licensed under Creative Commons
9. Acknowledgments
1. Knowing DocBook’s Structure
1.1. Introduction
1.2. Selecting the Right Top Level Element
1.3. Modularize Your Document with XIncludes
1.4. Writing Glossaries
1.5. Mastering Multiple Indices
1.6. Distinguish Between Section and SectX Elements
1.7. Using Lists
1.8. Incorporating Code Listings
1.9. Incorporating External Files in Code Listings
1.10. Inserting Remarks
1.11. Knowing the Difference of Cross References and Links
1.12. Inserting Cross References
1.13. Choosing Between Link Methods
1.14. Inserting Inline Quotes
2. Common Customizations
2.1. Introduction
2.2. Finding Professional Fonts
2.3. Writing Customization Layers
2.4. Inserting Date and Time
2.5. Accessing Title Contents
2.6. Getting the Documentation Title
2.7. Extracting Information from Your Own Processing Instructions
2.8. Retrieving XPath
2.9. Extending Language Files with Your Own Text
2.10. Extracting Language Information
2.11. Extracting and Formatting Person and Author Information
2.12. Splitting Header Into Label and Title With Modes
2.13. Numbering Figures and the Like Consistently Through your Document
2.14. Converting Lowercase to Uppercase or Vice Versa
2.15. Append Text or Graphics in Cross-References
3. Manipulating DocBook Document Structure
3.1. Introduction
3.2. Pretty-Printing DocBook Documents
3.3. Converting DocBook from Version 4 to Version 5
3.4. Converting DocBook from Version 5 to Version 4
3.5. Splitting DocBook Documents
3.6. Extracting One Element from DocBook Document
3.7. Transforming sectX Elements into section Elements
3.8. Transforming section Elements into sectX Elements
3.9. Transforming bridgehead Elements into section Elements
3.10. Moving Block Elements Outside of Paragraphs
3.11. Adding Index Entries (Semi-)Automatically
3.12. Including Revision Information from Version Control Systems
3.13. Creating an Acronym List
3.14. Splitting DocBook 5 Documents Into Topics
3.15. Assembling Topics
3.16. Creating an Assembly File Manually
4. Print Customizations
4.1. Introduction
4.2. Designing a Title Page
4.3. Styling Title Pages
4.4. Influencing the Leading
4.5. Hyphenating URLs
4.6. Creating Initials and Drop Caps
4.7. Numbering Part, Chapter, Appendix, and other Titles
5. (X)HTML Customizations
5.1. Introduction
5.2. Adding Authors to Table of Contents
5.3. Creating Permalinks
5.4. Creating Simple Navigation in Chapters
5.5. Implementing “Breadcrumbs”
5.6. Moving the Table of Contents (TOC)
5.7. Implementing Syntax Highlighting with Google Code Prettify
A. Namensnennung – Keine kommerzielle Nutzung – Weitergabe unter gleichen Bedingungen 3.0 Deutschland
B. Attribution-NonCommercial-ShareAlike 3.0 Unported

List of Tables

1.1. Common Prefixes and Their Namespaces
1.2. Comparison Between section and sectX Elements
1.3. Comparision Between textdata and xi:include
1.4. Comparison of XML Comments versus Remarks
1.5. Differences Between xref and link
1.6. Available Placeholders for template
1.7. Available Keywords for select
1.8. Internal and External Links Examples
1.9. Different Possibilities for Links
2.1. Modes for Title Elements
2.2. Different Combinations and Their Results on *.markup Modes
2.3. Extracting Language Information
2.4. Overview of Available Templates
3.1. Comparison of Splitting Method
3.2. Parameters to Influence Chunking Process Into Topics
3.3. Parameters to Influence the Assembling Process
4.1. Autolabel Parameters and their Default Values
4.2. Possible Formats for Autolabel Parameters
4.3. Parameter Combinations
5.1. Overview of Different HTML Stylesheets

List of Examples

1.1. A Valid DocBook 5 Book
1.2. Start Tag with Several Namespace Declarations
1.3. A Book with XIncluded Chapters
1.4. Fallback Possibility with xi:fallback
1.5. Included Text in a Programlisting
1.6. Unordered List with Three Entries
1.7. Numbered List with Three Entries
1.8. Definition List with Two Entries
1.9. External File Markuped up with textdata
1.10. External File Markuped up with xi:include
1.11. A Remark Inside a Paragraph
1.12. A Cross Reference
1.13. A Hyperlink
2.1. General Customization Layer
2.2. Structure
2.3. Namespace-aware Output of an XPath
2.4. Template to Number Figures Consistently
2.5. Appending Simple Text to Each Element
2.6. Appending Simple Text for Each Cross-Reference Pointing to a Chapter
2.7. Adding Graphic for HTML
2.8. Adding Graphic for FO
3.1. copy.xsl
3.2. pretty.xsl
3.3. db5to4-core.xsl
3.4. db5to4-info.xsl
3.5. db5to4-withinfo.xsl
3.6. dbsplit.xsl
3.7. chunker.xsl
3.8. Extracting Stylesheet rootid.xsl
3.9. rootid-resolve-xrefs.xsl
3.10. Transforms every sectX Element into a section Element
3.11. Transforms every sectX Element into a section Element
3.12. Error Checking of Section Levels
3.13. Transforms every bridgehead Element into a section Element
3.14. move-blocks-outof-para.xsl
3.15. profile-envar.xml
3.16. profile-tag.xsl
3.17. add-indexterms.xsl
3.18. Output of the Transformation
3.19. Stylesheet to Convert Bazaar's Log File
3.20. Mercurial Log File in XML
3.21. Stylesheet hg2revhistory.xsl to Convert Mercurial XML Log Files into DocBook's revhistory
3.22. make_acronyms.xsl
4.1. hyphenate-url.xsl
4.2. initials-baseline.xsl
4.3. Extending autolabel.format
5.1. Permalink Stylesheet (permalinks.xsl)
5.2. simple-navigation.xsl
5.3. db-simple-navigation.xsl

Project® Code®