The most famous and the most used system for user-oriented documentation creation and maintaining is DocBook. This open tool build upon open technologies provides a system for writing structured documents using SGML or XML. It is particularly well-suited to books and papers about computer hardware and software, though it is by no means limited to them. DocBook is an SGML document type definition (DTD). Many well-known companies, such as TcX (the developers of database system MySQL) or TrollTech (the developers of graphical library QT2) use their own tools for their product documentation. Not pointing out other factors, the result of using own documentation system could be fairly hard and complicated improvement and extensibility of the documentation by different contributors. This is the reason why the use of open technologies in process of creating documentation is highly desirable and productive. DocBook document is written using the so-called markup languages, such as SGML and XML. DocBook exists in both of these versions. Very much like in the HTML documents, individual parts or elements are marked by special tags. While in a HTML document the tags define the design of the document (change of color, font, etc.), in DocBook there is no tag that manipulates directly with design. The document is structured logically, which means that the parts of the same meaning are tagged (filenames, variables, products, persons, etc.). The resultant design can be specified using the DSSSL (Document Style Semantics and Specification Language), but is not essential for the common user. The differences between the XML and SGML versions of DocBook are minimal. Apart from different header of the document and different implementation of perhaps two tags are both versions identical. The main difference is in the processing of the document. The SGML version uses Jade Wrapper (jw) while the XML version uses tools based on the libxml2 library. In our examples, we will use the SGML version. The basic document looks like this: 2002-12-16 with this subtitle Text of the first chapter. ]]> DocBook document (book) is divided into chapters (chapter), sections in the chapters (sect1) and subsections (sect2). Subsections can have their own subsections (sect3, sect4). Chapters can be grouped with the part tag. Similarly, more books can be grouped into one compact unit using the set tag. > Text. Text. Text. Text. ... ]]> As it has already been mentioned, a DocBook document has its logical structure according to the meaning. Tags are used to mark expressions or words of the same type. Therefore things like filenames, variable names, constant names, function names, commands, products are tagged accordingly, as well as e-mail addresses or links to web pages. It is also possible to create lists, tables, insert pictures, and so on. /etc/passwd stdio.h $selected_user BUFFER_SIZE proctable_init() grep jade DocBook platon@pobox.sk Platon SDG ]]> You can see how simple SGML tags can be shortened by using the </> tag on the last example. One of the main advantages of DocBook documentation is the big number of possible output document formats. The most common are HTML, RTF, PDF, PS, TeX, pure text or manual pages. The generation is done by the jade program (we expect to generate myfile.html file from myfile.sgml file). $ jade -d /usr/lib/sgml/stylesheets/dbtohtml.dsl -t sgml myfile.sgml > myfile.html It is not necessary to use the jade parser directly. Some shell scripts for generating particular types of output files already exist. Those include db2html, db2pdf, docbook2tex, or docbook2txt. That means that to generate the HTML documentation you just need to use the following command. $ db2html myfile.sgml The design of the generated HTML document can be simply changed by using CSS (Cascading Style Sheets).