4736
Comment: Typo
|
4962
Output of "make html"
|
Deletions are marked like this. | Additions are marked like this. |
Line 33: | Line 33: |
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]. The "TDG" (The Definite Guide) is the most important documentation on Doc``Book. | 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. |
Line 58: | Line 58: |
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 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:
$ 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/.
http://sources.redhat.com/ml/docbook-apps/
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/.