Table of Contents
DocBook DokuWiki is a wiki system specifically developed to support the DocBook syntax. It was written with the needs of the HCSS project in mind, but the application has been kept free of context specific functionality as much as possible. It should be useful for all sorts of projects that require large amounts of documentation.
If you think you can add something useful or see an error feel free to edit this guide.
This Wiki supports two types of content: DocBook and Wikitext. This raises the question which syntax type you should use. The answer depends on what you wish to accomplish. The big difference between a normal Wiki and a DocBook document is that DocBook has a clearly defined structure, while a Wiki is mostly unstructured.
In a DocBook document you must define the structure for a document before writing anything. You need to decide what type of document you will be writing (a book or an article) and the contents of this document must be put in a structure of chapters, sections, paragraphs etc.
In a Wiki you have a much looser structure. You can add headings to a Wiki page to give that page some structure. The big difference with DocBook however is the structure that keeps the pages together. Wiki pages are kept together with links while DocBook pages are kept together by their document structure.
So which one to use? Generally you will want to use DocBook when writing structured documentation, that may also have a purpose outside this Wiki. This includes documents like User Manuals, FAQ's, HowTo's, etcetera. Most of these documents will be exported later on to join the large collection of documents within the HCSS build.
To link all these different documents together, Wikitext can be a good option. As Wikitext is easier to write yet less powerful than DocBook, it is better suited for creating navigational pages with information about the documents they link to. Also, note that Wikitext pages cannot be exported, so they have no use outside this Wiki.
There are a few steps involved in creating a new document. These steps are explained below.
Creating a link
To create a DocBook document you need to create a link to it from a Wiki page (the main page for example). Go to a Wiki page, start editing it by clicking the 'Edit this Page' button, then write down a link as follows:
[[docbook:{document id}|{link text}]]Where {document id} is a unique identifier for the document and {link text} the text for the link. For example:
[[docbook:usermanual|User manual]]
Once you have added the link to the Wiki page, save your changes by clicking the Save button. The link you just created should show up in red, meaning that the link refers to a non-existing document.
Note
The unique document identifier is really unique, among the entire Wiki. Make sure your document ID is as descriptive as possible, to avoid any future name clashes.Creating the document
Click the link you just created. You should get a message that the page doesn't exist and that you may create it. Click on the 'Create this Page' button to create the document. You should get page as shown in Figure 3, “Part of the Docbook document create page”.
Select an empty article or book as a template, then fill in the blanks and click on the Submit button. This should bring you to the empty index page of your newly created document. The next sections will explain how to add structure and content to your document.
Before you can start writing your document you have to add structure elements to your document. This can be done by editing the index page. So with the document's index page open you can just click the 'Edit this Page' button. You should then see a screen somewhat as in Figure 4, “Part of the Docbook document create page”.
You can add new element by selecting the main book(or article) and clicking on
the 'add'
button. This will open up a dialog where you can give the new section a unique
identifier, a title and select the type of the element. You can add more sections
and shift them around using the move left/right/up/down buttons. Once you are
satisfied with the document structure you can click the Save button to save the
changes.
At this point the document is compiled and you are returned to the document's index page, making your changes immediately visible. Note that you can always edit the document structure again at a later time, so you do not have to get the structure perfect the first time.
Once you have created a DocBook document and added some structure elements, you can start to write. Go to the section you want to edit by clicking on its name in the index page, then click the 'Edit this Page' button. When you have done this you should see a text area containing something like this:
<?xml version="1.0"?> <section id="writing_docbook"> <title>Writing docbook</title> </section>
Plain text should be written within a paragraph, by using the <para> and </para> tags. For example:
<?xml version="1.0"?> <section id="writing_docbook"> <title>Writing docbook</title> <para> This is a paragraph. </para> </section>
DocBook has many more possibilities than just displaying text. If you are not familiar with DocBook XML you might want to take a look at DocBook: The Definitive Guide, the in-depth guides offered on this Wiki, or simply by viewing the DocBook XML code from documents written by others on this Wiki.
The first steps in importing a document are the same as the steps required to create a new document (described in the section called “Creating a new DocBook document”). But instead of using the “Create From Template” form, you should use “Import Existing Document”.
When the document consists of only one XML file, this file can be uploaded and imported directly. If on the other hand the document consists of multiple files, the Java-based import utility (see the Subversion repository on Sourceforge) can be used to collect all the parts of the document into a single ZIP archive, which can then be uploaded.