This page tells you how to get started with the DocBook authoring system by starting form a very simple template.

Getting the template

Create a new directory, change into this directory, copy and unpack the template file (which can also get from [attachment:DocBookProjectTemplate.tgz this attachment]):

$ mkdir MyDoc
$ cd MyDoc/
$ cp ~ziegler/Documents/DocBookProjectTemplate.tgz .
$ tar xzf DocBookProjectTemplate.tgz
$ rm -f DocBookProjectTemplate.tgz

At this point, the directory contains 3 files:

$ ls
Book.xml  Makefile  schemas.xml

The file schemas.xml tells Emacs where it can find the DocBook schema definition. If you are not using Emacs, you can safely ignore or delete it.

Editing the document

For editing DocBook documents, you should always use a validating editor.

Validating editors (sometimes also called schema-aware, DTD-aware, or context sensitive editors) are applications that interactively validate documents against a certain schema or DTD as you edit them. Because they understand the schema or DTD rules, they can make editing documents much easier. For example, if you want to insert a new element at a certain point in a DocBook document, a validating editor shows you a list of only those elements that the DocBook schema says are valid at that point in the document (instead of showing you a list of all 375+ elements in DocBook).

You can find a list of validating editors [http://wiki.docbook.org/topic/DocBookAuthoringTools here].

Open the file Book.xml in the editor of your choice and study it. It is quite self-explanatory (which is the sense of having verbose markup).

If you want to know at which point you can insert which element, look at the DocBook Element Reference section in the [http://docbook.org/tdg5/en/html/docbook.html DocBook Definite Guide]. (Or let your validating editor guide you.) The "TDG" (The Definite Guide) is the most important documentation on DocBook.

Validating the document

It is very important for the toolchain that your documents validate against the DocBook schema.

To validate the file Book.xml, enter the following command:

$ make validate
java -Xss512K -jar /KM/home-0/ziegler/opt/relames-20060319/relames.jar \
              /KM/home-0/ziegler/DocBook/docbook-5.0CR5/rng/docbook.rng Book.xml
relmes verifier   Copyright(C) Sun Microsystems, Inc. 2001
parsing    /KM/home-0/ziegler/DocBook/docbook-5.0CR5/rng/docbook.rng
validating Book.xml
valid

Creating HTML from your document

As you can see from the previous output, the document is valid. Now you can invoke an XSLT processor to create an HTML version of your document by using the DocBook XSLT stylesheets.

$ make html
xsltproc -stringparam base.dir result/html/ \
                 /KM/home-0/ziegler/DocBook/docbook-xsl-1.73.2/html/chunk.xsl Book.xml
[...]
Writing result/html/index.html for book

This creates a directory called result where the resulting HTML pages are written to. In your browser, open the file result/html/index.html.

Useful links

The most important documents on DocBook are

• [http://docbook.org/tdg5/ DocBook 5.0: The Definitive Guide]. Consult this guide when you have a question concerning DocBook's grammar and element semantics.

• [http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide]. Consult this guide when you have a question concerning the transformation of your DocBook document into HTML or PDF.

The official DocBook hompage is http://docbook.org/.

FAQ

Dave Pawson maintains the [http://www.dpawson.co.uk/docbook/ DocBook FAQ].

Mailing Lists

There are two public DocBook discussion lists to which you can subscribe.

Use the subscription manager to subscribe or unsubscribe from these lists:

• <docbook@lists.oasis-open.org>: For general DocBook questions. These include questions about the DTD or schemas, questions about the syntax or semantics of elements, and general DocBook markup questions. Please don’t post questions about the stylesheets, formatting or processing issues, or other application-specific questions to this list. This list is archived [http://lists.oasis-open.org/archives/docbook/ here] and [http://sources.redhat.com/ml/docbook/ here].

• <docbook-apps@lists.oasis-open.org>: For stylesheet and application-related DocBook questions. This is the place to ask questions about formatting or processing issues, stylesheets, and other applications. This list is archived [http://lists.oasis-open.org/archives/docbook-apps/ here] and [http://sources.redhat.com/ml/docbook-apps/ here].

IRC

Many DocBook users, including several members of the Technical Committee regularly hang out on the IRC channel “#docbook” on freenode.

Wiki

There is a DocBook wiki at http://wiki.docbook.org/.