This page tells you how to get started with the Doc``Book 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 Doc``Book schema definition. If you are not using Emacs, you can safely ignore or delete it.

== Editing the document ==

For editing Doc``Book 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 Doc``Book document, a validating editor shows you a list of only those elements that the Doc``Book schema says are valid at that point in the document (instead of showing you a list of all 375+ elements in Doc``Book).

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 Doc``Book 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 Doc``Book.


== Validating the document ==

It is very important for the toolchain that your documents validate against the Doc``Book 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 Doc``Book 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 Doc``Book are

 * [http://docbook.org/tdg5/ DocBook 5.0: The Definitive Guide]. Consult this guide when you have a question concerning Doc``Book'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 Doc``Book document into HTML or PDF.

The official Doc``Book hompage is http://docbook.org/.


=== FAQ ===

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

=== Mailing Lists ===

There are two public Doc``Book 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 Doc``Book questions. These include questions about the DTD or schemas, questions about the syntax or semantics of elements, and general Doc``Book 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 Doc``Book 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 Doc``Book users, including several members of the Technical Committee regularly hang out on the IRC channel “#docbook” on freenode.

=== Wiki ===

There is a Doc``Book wiki at http://wiki.docbook.org/.