1 | HOW-TO: Compiling Subversion DocBook XML Documents |
---|
2 | =================================================== |
---|
3 | |
---|
4 | The Subversion project uses for some of its documentation DocBook |
---|
5 | Lite, a scaled-down version of the DocBook DTD, used by O'Reilly & |
---|
6 | Associates. |
---|
7 | |
---|
8 | The goal of this document is to give simple instructions to anyone who |
---|
9 | wants to compile Subversion DocBook documents into a useful format, |
---|
10 | like HTML or PDF. It should state *exactly* which tools to use, and |
---|
11 | how to invoke them, in simplest terms. |
---|
12 | |
---|
13 | Table of Contents: |
---|
14 | |
---|
15 | I. PRIMER |
---|
16 | II. COMPILING THE DOCS |
---|
17 | III. HACKING ON THE DOCS |
---|
18 | |
---|
19 | I. PRIMER |
---|
20 | |
---|
21 | DocBook has a tortured, confusing history. Before you do anything, |
---|
22 | take a look at Eric Raymond's excellent "DocBook Demystification HOWTO": |
---|
23 | |
---|
24 | http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/ |
---|
25 | |
---|
26 | It's very short and clears up many things. |
---|
27 | |
---|
28 | |
---|
29 | II. COMPILING THE DOCS |
---|
30 | |
---|
31 | |
---|
32 | 1. Fetch XSL stylesheets for DocBook and place them in tools/xsl |
---|
33 | |
---|
34 | The "DocBook Open Repository" on Sourceforge has a large collection |
---|
35 | of XSL stylesheets that specifically operate on DocBook. Download |
---|
36 | and install the latest 'docbook-xsl' package from this page: |
---|
37 | |
---|
38 | http://sourceforge.net/project/showfiles.php?group_id=21935 |
---|
39 | |
---|
40 | Download the latest version of docbook-xsl, unpack it, then rename |
---|
41 | the unpacked directory to tools/xsl, something like this: |
---|
42 | |
---|
43 | $ cd doc/book/tools |
---|
44 | $ tar zxvf docbook-xsl-X.YY.Z.tar.gz |
---|
45 | $ mv docbook-xsl-X.YY.Z xsl |
---|
46 | |
---|
47 | The default build process expects the stylesheets to be in |
---|
48 | tools/xsl/. |
---|
49 | |
---|
50 | |
---|
51 | 2. Use XSLT to transform the documents. |
---|
52 | |
---|
53 | XSLT applies an .xsl stylesheet to an .xml file, and produces some |
---|
54 | new markup document. |
---|
55 | |
---|
56 | * Get libxslt, a C library for XSLT, from http://xmlsoft.org/XSLT/. |
---|
57 | (If you're having trouble finding a source package to compile, |
---|
58 | try ftp://archive.progeny.com/GNOME/sources/libxslt/1.0/.) |
---|
59 | Install it: |
---|
60 | |
---|
61 | $ tar zxvf libxslt-1.0.22.tar.gz |
---|
62 | $ cd libxslt-1.0.22 |
---|
63 | $ ./configure |
---|
64 | $ ./make |
---|
65 | # make install |
---|
66 | |
---|
67 | (Note: you may discover that you need to install libxml2 first. |
---|
68 | Find it at ftp://archive.progeny.com/GNOME/sources/libxml2/) |
---|
69 | |
---|
70 | If you don't want to compile libxslt, you can just fetch the |
---|
71 | appropriate OS binary package. |
---|
72 | |
---|
73 | * From this directory, do |
---|
74 | |
---|
75 | $ make all-html |
---|
76 | |
---|
77 | This produces an HTML version for the Subversion DocBook docs in |
---|
78 | misc-docs/svn-misc-docs.html. |
---|
79 | |
---|
80 | |
---|
81 | 3. Make a PDF file. |
---|
82 | |
---|
83 | Formatting Objects (FO) is a layout language, kind of like |
---|
84 | postscript, dvi or css. People are quickly standardizing on it. |
---|
85 | |
---|
86 | * Fetch FOP, a java program which converts .fo files into PDF: |
---|
87 | |
---|
88 | http://xml.apache.org/fop/index.html |
---|
89 | |
---|
90 | There are approximately 17577 ways to install FOP. Rather than |
---|
91 | describe them all, we will recommend one way. If you've already |
---|
92 | installed FOP some other way, that's fine, then you can ignore |
---|
93 | the following recipe: |
---|
94 | |
---|
95 | 1. Download the latest version from |
---|
96 | http://www.apache.org/dyn/closer.cgi/xml/fop, for example, |
---|
97 | fop-0.20.5-bin.tar.gz. Just get a binary distribution, |
---|
98 | there's no need for the Java source. |
---|
99 | |
---|
100 | 2. Unpack it into tools/fop/ |
---|
101 | |
---|
102 | $ cd doc/book/tools |
---|
103 | $ tar zxvf fop-0.20.5-bin.tar.gz |
---|
104 | $ mv fop-0.20.5 fop |
---|
105 | |
---|
106 | That should be enough. The Makefile will actually invoke |
---|
107 | tools/bin/run-fop.sh. That script attempts to find FOP already |
---|
108 | installed on your system, but falls back to the FOP unpacked into |
---|
109 | tools/fop/ if there's no other FOP available. |
---|
110 | |
---|
111 | Of course, to run FOP at all, you also need a Java runtime |
---|
112 | environment. Try java.sun.com or www.blackdown.org if you don't |
---|
113 | already have that. |
---|
114 | |
---|
115 | Sometimes building the DocBook documents can use more memory than |
---|
116 | Java is willing to allocate by default, and you may need to increase |
---|
117 | the default heap size. With Sun's JVM, this is accomplished by |
---|
118 | passing the arguments "-Xms100m -Xmx200m" (known to work with |
---|
119 | versions 1.2.x-1.4.x, and likely different for JVMs from other |
---|
120 | vendors). To tell fop.sh about these arguments, pass them via |
---|
121 | the environment variable FOP_OPTS (which is also configurable in |
---|
122 | your ~/.foprc). |
---|
123 | |
---|
124 | $ export FOP_OPTS="-Xms100m -Xmx200m" |
---|
125 | |
---|
126 | * If you want images to be included in the PDF, you'll need to use |
---|
127 | the JIMI image processing library. Grab the latest release from |
---|
128 | http://java.sun.com/products/jimi/, then cp the jar file into the |
---|
129 | same place as the FOP jar files: |
---|
130 | |
---|
131 | $ cd doc/book/tools/ |
---|
132 | $ tar zxvf jimi1_0.tar.Z |
---|
133 | $ cp Jimi/examples/AppletDemo/JimiProClasses.jar fop/lib/ |
---|
134 | |
---|
135 | Poof! You now have PNG support. |
---|
136 | |
---|
137 | * From this directory, do |
---|
138 | |
---|
139 | $ make pdf |
---|
140 | |
---|
141 | This produces PDF for the Subversion DocBook documents in |
---|
142 | misc-docs/svn-misc-docs.pdf. |
---|
143 | |
---|
144 | |
---|
145 | III. HACKING ON THE DOCS |
---|
146 | |
---|
147 | In addition to everything in section II: |
---|
148 | |
---|
149 | |
---|
150 | 1. Get a nice editing environment for SGML/XML. |
---|
151 | |
---|
152 | This isn't strictly required, but it's nice when your editor |
---|
153 | colorizes things, understands the DTD, tells you what tags you can |
---|
154 | insert, etc. |
---|
155 | |
---|
156 | If you use emacs, we recommend the PSGML major-mode. Most free |
---|
157 | operating systems package it, or its home page is here: |
---|
158 | |
---|
159 | http://www.lysator.liu.se/projects/about_psgml.html |
---|
160 | |
---|
161 | If you use vim, you might check out xmledit, at: |
---|
162 | |
---|
163 | http://www.vim.org/scripts/script.php?script_id=301 |
---|
164 | |
---|
165 | |
---|
166 | 2. Get a validating parser. |
---|
167 | |
---|
168 | Actually, if you have what you need to compile the documentation, |
---|
169 | then you almost certainly have an XML validator installed already - |
---|
170 | it is called xmllint, and comes as part of libxml2. |
---|
171 | |
---|
172 | The makefile is preconfigured with a suitable invocation of it, |
---|
173 | so simply run: |
---|
174 | |
---|
175 | $ make valid |
---|
176 | |
---|
177 | |
---|
178 | 3. Read about the DocBook lite tags. |
---|
179 | |
---|
180 | The tools area contains the readme-dblite.html file which describes |
---|
181 | how to write with DocBook Lite. Familiarize yourself with these |
---|
182 | tags before changing the docs. |
---|