1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>G.2.Tool Sets</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="docguide.html" title="AppendixG.Documentation">
<link rel="prev" href="docguide.html" title="AppendixG.Documentation">
<link rel="next" href="docguide-build.html" title="G.3.Building The Documentation">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="docguide-toolsets"></a>G.2.Tool Sets</h2></div></div></div>
<p> The following tools are used to process the documentation. Some
may be optional, as noted.
</p>
<div class="variablelist"><dl>
<dt><span class="term"><a href="http://www.oasis-open.org/docbook/sgml/" target="_top">DocBook DTD</a></span></dt>
<dd><p> This is the definition of DocBook itself. We currently use
version 4.2; you cannot use later or earlier versions. Note
that there is also an <acronym class="acronym">XML</acronym> version of DocBook
[mdash ] do not use that.
</p></dd>
<dt><span class="term"><a href="http://www.oasis-open.org/cover/ISOEnts.zip" target="_top">ISO 8879 character entities</a></span></dt>
<dd><p> These are required by DocBook but are distributed separately
because they are maintained by ISO.
</p></dd>
<dt><span class="term"><a href="http://openjade.sourceforge.net" target="_top">OpenJade</a></span></dt>
<dd><p> This is the base package of <acronym class="acronym">SGML</acronym> processing.
It contains an <acronym class="acronym">SGML</acronym> parser, a
<acronym class="acronym">DSSSL</acronym> processor (that is, a program to
convert <acronym class="acronym">SGML</acronym> to other formats using
<acronym class="acronym">DSSSL</acronym> stylesheets), as well as a number of
related tools. <span class="productname">Jade</span> is now being
maintained by the OpenJade group, no longer by James Clark.
</p></dd>
<dt><span class="term"><a href="http://docbook.sourceforge.net/projects/dsssl/index.html" target="_top">DocBook DSSSL Stylesheets</a></span></dt>
<dd><p> These contain the processing instructions for converting the
DocBook sources to other formats, such as
<acronym class="acronym">HTML</acronym>.
</p></dd>
<dt><span class="term"><a href="http://docbook2x.sourceforge.net" target="_top">DocBook2X tools</a></span></dt>
<dd><p> This optional package is used to create man pages. It has a
number of prerequisite packages of its own. Check the web
site.
</p></dd>
<dt><span class="term"><a href="http://jadetex.sourceforge.net" target="_top">JadeTeX</a></span></dt>
<dd>
<p> If you want to, you can also install
<span class="productname">JadeTeX</span> to use
<span class="productname">TeX</span> as a formatting backend for
<span class="productname">Jade</span>.
<span class="application">JadeTeX</span> can create Postscript or
<acronym class="acronym">PDF</acronym> files (the latter with bookmarks).
</p>
<p> However, the output from <span class="application">JadeTeX</span> is
inferior to what you get from the <acronym class="acronym">RTF</acronym>
backend. Particular problem areas are tables and various
artifacts of vertical and horizontal spacing. Also, there is
no opportunity to manually polish the results.
</p>
</dd>
</dl></div>
<p>
</p>
<p> We have documented experience with several installation methods for
the various tools that are needed to process the documentation.
These will be described below. There may be some other packaged
distributions for these tools. Please report package status to the
documentation mailing list, and we will include that information
here.
</p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id900348"></a>G.2.1.<span class="productname">Linux</span> <acronym class="acronym">RPM</acronym> Installation</h3></div></div></div>
<p> Most vendors provide a complete RPM set for DocBook processing in
their distribution. Look for an “<span class="quote">SGML</span>” option while
installing, or the following packages:
<code class="filename">sgml-common</code>, <code class="filename">docbook</code>,
<code class="filename">stylesheets</code>, <code class="filename">openjade</code>
(or <code class="filename">jade</code>). Possibly
<code class="filename">sgml-tools</code> will be needed as well. If your
distributor does not provide these then you should be able to make
use of the packages from some other, reasonably compatible vendor.
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id900413"></a>G.2.2.FreeBSD Installation</h3></div></div></div>
<p> The FreeBSD Documentation Project is itself a heavy user of
DocBook, so it comes as no surprise that there is a full set of
“<span class="quote">ports</span>” of the documentation tools available on
FreeBSD. The following ports need to be installed to build the
documentation on FreeBSD.
</p>
<div class="itemizedlist"><ul type="disc">
<li><p><code class="filename">textproc/sp</code></p></li>
<li><p><code class="filename">textproc/openjade</code></p></li>
<li><p><code class="filename">textproc/iso8879</code></p></li>
<li><p><code class="filename">textproc/dsssl-docbook-modular</code></p></li>
</ul></div>
<p>
Apparently, there is no port for the DocBook V4.2 SGML DTD
available right now. You will need to install it manually.
</p>
<p> A number of things from <code class="filename">/usr/ports/print</code>
(<code class="filename">tex</code>, <code class="filename">jadetex</code>) might
also be of interest.
</p>
<p> It's possible that the ports do not update the main catalog file
in <code class="filename">/usr/local/share/sgml/catalog</code>. Be sure to
have the following line in there:
</p>
<pre class="programlisting">CATALOG "/usr/local/share/sgml/docbook/4.2/docbook.cat"</pre>
<p>
If you do not want to edit the file you can also set the
environment variable <code class="envar">SGML_CATALOG_FILES</code> to a
colon-separated list of catalog files (such as the one above).
</p>
<p> More information about the FreeBSD documentation tools can be
found in the <a href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html" target="_top"> FreeBSD Documentation Project's instructions</a>.
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id900526"></a>G.2.3.Debian Packages</h3></div></div></div>
<p> There is a full set of packages of the documentation tools
available for <span class="productname">Debian GNU/Linux</span>.
To install, simply use:
</p>
<pre class="programlisting">apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets</pre>
<p>
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id900549"></a>G.2.4.Manual Installation from Source</h3></div></div></div>
<p> The manual installation process of the DocBook tools is somewhat
complex, so if you have pre-built packages available, use them.
We describe here only a standard setup, with reasonably standard
installation paths, and no “<span class="quote">fancy</span>” features. For
details, you should study the documentation of the respective
package, and read <acronym class="acronym">SGML</acronym> introductory material.
</p>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="id900570"></a>G.2.4.1.Installing OpenJade</h4></div></div></div>
<div class="procedure"><ol type="1">
<li>
<p> The installation of OpenJade offers a GNU-style
<code class="literal">./configure; make; make install</code> build
process. Details can be found in the OpenJade source
distribution. In a nutshell:
</p>
<pre class="synopsis">./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install</pre>
<p>
Be sure to remember where you put the “<span class="quote">default
catalog</span>”; you will need it below. You can also leave
it off, but then you will have to set the environment variable
<code class="envar">SGML_CATALOG_FILES</code> to point to the file
whenever you use <span class="application">jade</span> later on.
(This method is also an option if OpenJade is already
installed and you want to install the rest of the toolchain
locally.)
</p>
</li>
<li>
<a name="doc-openjade-install"></a><p> Additionally, you should install the files
<code class="filename">dsssl.dtd</code>, <code class="filename">fot.dtd</code>,
<code class="filename">style-sheet.dtd</code>, and
<code class="filename">catalog</code> from the
<code class="filename">dsssl</code> directory somewhere, perhaps into
<code class="filename">/usr/local/share/sgml/dsssl</code>. It's
probably easiest to copy the entire directory:
</p>
<pre class="synopsis">cp -R dsssl /usr/local/share/sgml</pre>
<p>
</p>
</li>
<li>
<p> Finally, create the file
<code class="filename">/usr/local/share/sgml/catalog</code> and add
this line to it:
</p>
<pre class="programlisting">CATALOG "dsssl/catalog"</pre>
<p>
(This is a relative path reference to the file installed in
<a href="docguide-toolsets.html#doc-openjade-install">Step 2</a>. Be sure to adjust it
if you chose your installation layout differently.)
</p>
</li>
</ol></div>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="id900714"></a>G.2.4.2.Installing the <span class="productname">DocBook</span> <acronym class="acronym">DTD</acronym> Kit</h4></div></div></div>
<div class="procedure"><ol type="1">
<li><p> Obtain the <a href="http://www.docbook.org/sgml/4.2/docbook-4.2.zip" target="_top"> DocBook V4.2 distribution</a>.
</p></li>
<li>
<p> Create the directory
<code class="filename">/usr/local/share/sgml/docbook-4.2</code> and change
to it. (The exact location is irrelevant, but this one is
reasonable within the layout we are following here.)
</p>
<pre class="screen"><code class="prompt">$ </code><strong class="userinput"><code>mkdir /usr/local/share/sgml/docbook-4.2</code></strong>
<code class="prompt">$ </code><strong class="userinput"><code>cd /usr/local/share/sgml/docbook-4.2</code></strong></pre>
<p>
</p>
</li>
<li>
<p> Unpack the archive.
</p>
<pre class="screen"><code class="prompt">$ </code><strong class="userinput"><code>unzip -a ...../docbook-4.2.zip</code></strong></pre>
<p>
(The archive will unpack its files into the current directory.)
</p>
</li>
<li>
<p> Edit the file
<code class="filename">/usr/local/share/sgml/catalog</code> (or whatever
you told jade during installation) and put a line like this
into it:
</p>
<pre class="programlisting">CATALOG "docbook-4.2/docbook.cat"</pre>
<p>
</p>
</li>
<li>
<p> Download the <a href="http://www.oasis-open.org/cover/ISOEnts.zip" target="_top"> ISO 8879 character entities archive</a>, unpack it, and put the
files in the same directory you put the DocBook files in.
</p>
<pre class="screen"><code class="prompt">$ </code><strong class="userinput"><code>cd /usr/local/share/sgml/docbook-4.2</code></strong>
<code class="prompt">$ </code><strong class="userinput"><code>unzip ...../ISOEnts.zip</code></strong></pre>
<p>
</p>
</li>
<li>
<p> Run the following command in the directory with the DocBook and ISO files:
</p>
<pre class="programlisting">perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat</pre>
<p>
(This fixes a mixup between the names used in the DocBook
catalog file and the actual names of the ISO character entity
files.)
</p>
</li>
</ol></div>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="id900893"></a>G.2.4.3.Installing the DocBook <acronym class="acronym">DSSSL</acronym> Style Sheets</h4></div></div></div>
<p> To install the style sheets, unzip and untar the distribution and
move it to a suitable place, for example
<code class="filename">/usr/local/share/sgml</code>. (The archive will
automatically create a subdirectory.)
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>gunzip docbook-dsssl-1.<em class="replaceable"><code>xx</code></em>.tar.gz</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<em class="replaceable"><code>xx</code></em>.tar</code></strong></pre>
<p>
</p>
<p> The usual catalog entry in
<code class="filename">/usr/local/share/sgml/catalog</code> can also be
made:
</p>
<pre class="programlisting">CATALOG "docbook-dsssl-1.<em class="replaceable"><code>xx</code></em>/catalog"</pre>
<p>
Because stylesheets change rather often, and it's sometimes
beneficial to try out alternative versions,
<span class="productname">PostgreSQL</span> doesn't use this catalog
entry. See <a href="docguide-toolsets.html#docguide-toolsets-configure" title="G.2.5.Detection by configure">SectionG.2.5, “Detection by <code class="command">configure</code>”</a> for
information about how to select the stylesheets instead.
</p>
</div>
<div class="sect3" lang="en">
<div class="titlepage"><div><div><h4 class="title">
<a name="id900993"></a>G.2.4.4.Installing <span class="productname">JadeTeX</span></h4></div></div></div>
<p> To install and use <span class="productname">JadeTeX</span>, you will
need a working installation of <span class="productname">TeX</span> and
<span class="productname">LaTeX2e</span>, including the supported
<span class="productname">tools</span> and
<span class="productname">graphics</span> packages,
<span class="productname">Babel</span>,
<span class="productname"><acronym class="acronym">AMS</acronym> fonts</span> and
<span class="productname">AMS-LaTeX</span>, the
<span class="productname"><acronym class="acronym">PSNFSS</acronym></span> extension
and companion kit of “<span class="quote">the 35 fonts</span>”, the
<span class="productname">dvips</span> program for generating
<span class="productname">PostScript</span>, the macro packages
<span class="productname">fancyhdr</span>,
<span class="productname">hyperref</span>,
<span class="productname">minitoc</span>,
<span class="productname">url</span> and
<span class="productname">ot2enc</span>. All of these can be found on
your friendly neighborhood <a href="http://www.ctan.org" target="_top"> <acronym class="acronym">CTAN site</acronym></a>.
The installation of the <span class="application">TeX</span> base
system is far beyond the scope of this introduction. Binary
packages should be available for any system that can run
<span class="application">TeX</span>.
</p>
<p> Before you can use <span class="application">JadeTeX</span> with the
<span class="productname">PostgreSQL</span> documentation sources, you
will need to increase the size of
<span class="application">TeX</span>'s internal data structures.
Details on this can be found in the <span class="application">JadeTeX</span>
installation instructions.
</p>
<p> Once that is finished you can install <span class="application">JadeTeX</span>:
</p>
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>gunzip jadetex-<em class="replaceable"><code>xxx</code></em>.tar.gz</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>tar xf jadetex-<em class="replaceable"><code>xxx</code></em>.tar</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>cd jadetex</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>make install</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>mktexlsr</code></strong></pre>
<p>
The last two need to be done as <span class="systemitem">root</span>.
</p>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="docguide-toolsets-configure"></a>G.2.5.Detection by <code class="command">configure</code></h3></div></div></div>
<p> Before you can build the documentation you need to run the
<code class="filename">configure</code> script as you would when building
the <span class="productname">PostgreSQL</span> programs themselves.
Check the output near the end of the run, it should look something
like this:
</p>
<pre class="screen"><code class="computeroutput">checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V4.2... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl</code></pre>
<p>
If neither <code class="filename">onsgmls</code> nor
<code class="filename">nsgmls</code> were found then you will not see the
remaining 4 lines. <code class="filename">nsgmls</code> is part of the Jade
package. If “<span class="quote">DocBook V4.2</span>” was not found then you did
not install the DocBook DTD kit in a place where jade can find it,
or you have not set up the catalog files correctly. See the
installation hints above. The DocBook stylesheets are looked for
in a number of relatively standard places, but if you have them
some other place then you should set the environment variable
<code class="envar">DOCBOOKSTYLE</code> to the location and rerun
<code class="filename">configure</code> afterwards.
</p>
</div>
</div></body>
</html>
|
