Tree [cbb09f] default tip /

File Date Author Commit
bin 2014-06-25 Thomas Schraitle Thomas Schraitle [cbb09f] Implemented copyexamples
build 2012-06-10 Thomas Schraitle Thomas Schraitle [4bf96a] Remove from hg
en 2014-06-25 Thomas Schraitle Thomas Schraitle [8abb0e] Support glossterm permalinks
frameworks 2014-04-18 Thomas Schraitle Thomas Schraitle [a408df] Used book.titlepage.recto.mode to add "Version"...
images 2012-01-29 Thomas Schraitle Thomas Schraitle [608636] Added link to frameworks/db-xslt/images/callouts
test 2012-01-02 Thomas Schraitle Thomas Schraitle [f625c5] Added file for Norman
web 2014-05-02 Thomas Schraitle Thomas Schraitle [528ee9] Automatically merge
.hgignore 2014-04-26 Thomas Schraitle Thomas Schraitle [0bb50f] Added build-20?????? in the ignore list (create...
.hgsigs 2011-09-19 Toms Toms [8512f1] Added signature for changeset ea4b2cbb00c6
.hgtags 2014-04-18 Thomas Schraitle Thomas Schraitle [a45d28] Moved tag v0.7 to changeset 7a0e453848cd (from ... 2011-11-13 Thomas Schraitle Thomas Schraitle [810f1f] Needed for catalog support
Changelog 2014-04-18 Thomas Schraitle Thomas Schraitle [354789] Updated for v0.7
DocBook-Cookbook.xpr 2014-04-18 Thomas Schraitle Thomas Schraitle [fa2dd9] Update oXygen configuration file
IDEAS.txt 2011-12-18 Thomas Schraitle Thomas Schraitle [789a17] Added another idea
README.rst 2013-07-21 Thomas Schraitle Thomas Schraitle [d9df09] Removed linebreak
USEFUL_LINKS.rst 2012-05-27 Thomas Schraitle Thomas Schraitle [d2411d] Renamed USEFUL_LINKS.txt -> USEFUL_LINKS.rst
cc-by-nc-sa-3.0-de.txt 2010-12-25 Thomas Schraitle Thomas Schraitle [1199b9] The CC HTML snippet

Read Me

Welcome to "The DoCookBook"

Author:Thomas Schraitle <tom_schr AT web DOT de>
Description:Short overview of this project


The book is licensed as Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany License (CC by-nc-sa 3.0 DE) See


The DoCookBook project aims to create an open source book about DocBook and the DocBook XSL stylesheets written in a cookbook-style manner and released under a Creative Commons license.


This book is written in a "cookbook" style. The book contains "topics" which are divided into a problem, the corresponding solution, some discussions, and optional related information. It is very easy just to go to the table of contents and see if there is something useful that fits to your problem. Solutions are usually written in a procedural style which contains several steps.

Target Group

It is assumed you have a decent knowledge about XML and DocBook. It doesn't hurt if you know CSS and XSLT. As such, it is aimed more for DocBook developers than writers.

Structure of the Book and Organization

The main file is "en/xml/DocBook-Cookbook.xml". It contains xi:include elements which refers to chapters, appendices and other second level elements.

# Struture of Book with Main Chapters
+-- 5.1/        # (1)
+-- common/     # (2)
+-- db/         # (3)
+-- epub/       # (4)
+-- fo/         # (5)
+-- html/       # (6)
+--- structure/ # (7)
(1) Contains the DocBook Schema and possible customizations
(2) Contains topics to common customizations
(3) Contains topics to DocBook's markup
(4) Planned: will contain customizations to EPUB output format
(5) Contains topics to FO customizations
(6) Contains topics to HTML, XHTML, and other customizations based on HTML
(7) Contains topics how to manipulate DocBook's structure

Some topics contain directories which stores XSLT, XML, or other example files. In some cases these are incorporated into the XML source, sometimes they are just lying around for testing purposes.

Each topic is a self-contained matter of a specific problem and its solution with discussion. Use the skeleton file "en/xml/topic.empty.xml" as a starting point. It contains the basic structure and you just need to add the flesh of your topic.


Do you miss anything? Have you discovered an error? Have an idea about how to improve the book? Great! If you want to contribute to the book, you can do it in different ways:

  • Write me a mail to <tom_schr (AT)> and send me your comments
  • Extend the tickets (Ideas for New Topics) at
  • Clone my repository on Sourcforge and send me patches

Here is a procedure about how to clone the repository:

  1. Download Mercurial from and install it on your system.

2. Clone my Sourceforge repository with the Mercurial command hg:

$ hg clone doccookbook-code

3. If you want to create a new topic, decide in which chapter it could belong (markup, common customizations, structure, fo, html, or any other). For example, if you want an addition to DocBook´s structure chapter, use the existing template and copy it (where 'FOO' is an abstract term; replace it with something meaningful):

$ hg copy en/xml/topic.empty.xml en/xml/structure/topic.FOO.xml

4. Open the XML file which contains a chapter element. In our example, it would be en/xml/dbc-structure.xml. Scroll to the <xi:include> elements and insert the following code:

<xi:include href="structure/"/>
  1. Open the XML file en/xml/structure/ and write your topic.

6. When you are finished, create a diff:

$ hg diff > foo.patch
  1. Send the diff to me.

Find more information about Mercurial at

How to build the book

Currently, building the book works but it's not as nice as I would like to see it.

  • Building chunked HTML: use ./bin/dbsaxon
  • Building single HTML: use bin/dbsaxon9

At the moment, it is a mixture of XSLT 1.0 and XSLT 2.0 stylesheets. To avoid maintaing two different CSS files (one for the XSLT 1.0 output, the other for 2.0), the HTML files coming from XSLT 1.0 are "cleaned up". This cleanup step makes the structure compatible to the XSLT 2.0 output.

How you can help

  • Find typos, grammar problems, inconsistencies, or plain errors
  • Send me patches
  • Write your own topic