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:
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.
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.
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).
Prihlásiť
Registrácia
English
