|
9674
|
1 Tools required for building the documentation
|
|
|
2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
3
|
|
|
4 * DocBook 4.1.2 or later
|
|
|
5 * The DocBook XML DTD (also known as DocBk XML)
|
|
|
6 * DocBook XSL stylesheets -- version 1.50.0 or later is recommended.
|
|
|
7
|
|
|
8 I am not quite sure which tools work, but I used the following
|
|
|
9 ones successfully, so they are required:
|
|
|
10
|
|
|
11 * xmllint (part of libxml2) is used for validation.
|
|
|
12 * xsltproc (part of libxslt1) is used for transforming XML files into HTML
|
|
|
13 files. Version 1.0.18 or later is recommended.
|
|
|
14
|
|
10025
|
15 Also it's possible to use the Saxon XSLT Processor. Russian translator
|
|
|
16 used it (version 6.4.4) for a while. To enable it change USE_SAXON to 1 in
|
|
|
17 the Makefile.
|
|
|
18
|
|
9674
|
19
|
|
|
20 Building the documentation
|
|
|
21 ~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
22
|
|
|
23 1) Before trying to build the documentation, run
|
|
|
24
|
|
|
25 make test
|
|
|
26
|
|
|
27 to see if everything is set up properly. If something goes wrong,
|
|
|
28 check the Configuration section of the toplevel Makefile and adjust
|
|
|
29 the variables.
|
|
|
30
|
|
|
31
|
|
|
32 2) Now simply run
|
|
|
33
|
|
|
34 make all
|
|
|
35
|
|
|
36 to build the documentation.
|
|
|
37
|
|
|
38
|
|
|
39 A few words about SGML catalog files
|
|
|
40 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
41
|
|
|
42 As far as I know, the document type declaration in XML files requires
|
|
|
43 both a public and a system identifier. For example:
|
|
|
44
|
|
|
45 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
|
46 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd">
|
|
|
47
|
|
|
48 where
|
|
|
49
|
|
|
50 "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
|
51
|
|
|
52 is the public, and
|
|
|
53
|
|
|
54 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"
|
|
|
55
|
|
|
56 is the system identifier.
|
|
|
57
|
|
|
58 The problem is that the system identifier is most probably system-dependent.
|
|
|
59 To avoid the need to manually fix the system identifiers before building the
|
|
|
60 documentation, I've decided to use SGML catalogs. If you have your catalogs
|
|
9953
|
61 set up correctly, xmllint and xsltproc will use them to find the DTDs
|
|
9674
|
62 based on the public identifiers.
|
|
|
63
|
|
|
64 Note that this works only if public identifiers override system identifiers
|
|
|
65 (i.e. the catalog file must contain 'OVERRIDE YES'). (I had no problem with
|
|
|
66 these on my system, since the Debian people took care of everything. ;-))
|
|
|
67
|
|
|
68
|
|
|
69 --
|
|
|
70 Andras Mohari
|
