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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>G.3.Building The Documentation</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-toolsets.html" title="G.2.Tool Sets">
<link rel="next" href="docguide-authoring.html" title="G.4.Documentation Authoring">
<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-build"></a>G.3.Building The Documentation</h2></div></div></div>
<p> Once you have everything set up, change to the directory
<code class="filename">doc/src/sgml</code> and run one of the commands
described in the following subsections to build the
documentation. (Remember to use GNU make.)
</p>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id901379"></a>G.3.1.HTML</h3></div></div></div>
<p> To build the <acronym class="acronym">HTML</acronym> version of the documentation:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>gmake html</code></strong></pre>
<p>
This is also the default target.
</p>
<p> When the HTML documentation is built, the process also generates
the linking information for the index entries. Thus, if you want
your documentation to have a concept index at the end, you need to
build the HTML documentation once, and then build the
documentation again in whatever format you like.
</p>
<p> To allow for easier handling in the final distribution, the files
comprising the HTML documentation are stored in a tar archive that
is unpacked at installation time. To create the
<acronym class="acronym">HTML</acronym> documentation package, use the commands
</p>
<pre class="programlisting">cd doc/src
gmake postgres.tar.gz</pre>
<p>
In the distribution, these archives live in the
<code class="filename">doc</code> directory and are installed by default
with <code class="command">gmake install</code>.
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id901442"></a>G.3.2.Manpages</h3></div></div></div>
<p> We use the <span class="application">docbook2man</span> utility to
convert <span class="productname">DocBook</span>
<code class="sgmltag-element">refentry</code> pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive,
similar to the <acronym class="acronym">HTML</acronym> version. To create the man
page package, use the commands
</p>
<pre class="programlisting">cd doc/src
gmake man.tar.gz</pre>
<p>
which will result in a tar file being generated in the
<code class="filename">doc/src</code> directory.
</p>
<p> To generate quality man pages, it might be necessary to use a
hacked version of the conversion utility or do some manual
postprocessing. All man pages should be manually inspected before
distribution.
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id901494"></a>G.3.3.Print Output via <span class="application">JadeTex</span></h3></div></div></div>
<p> If you want to use <span class="application">JadeTex</span> to produce a
printable rendition of the documentation, you can use one of the
following commands:
</p>
<div class="itemizedlist"><ul type="disc">
<li>
<p> To make a <acronym class="acronym">DVI</acronym> version:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>gmake postgres.dvi</code></strong></pre>
<p>
</p>
</li>
<li>
<p> To generate Postscript from the <acronym class="acronym">DVI</acronym>:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>gmake postgres.ps</code></strong></pre>
<p>
</p>
</li>
<li>
<p> To make a <acronym class="acronym">PDF</acronym>:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>gmake postgres.pdf</code></strong></pre>
<p>
(Of course you can also make a <acronym class="acronym">PDF</acronym> version
from the Postscript, but if you generate <acronym class="acronym">PDF</acronym>
directly, it will have hyperlinks and other enhanced features.)
</p>
</li>
</ul></div>
<p>
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id901598"></a>G.3.4.Print Output via <acronym class="acronym">RTF</acronym></h3></div></div></div>
<p> You can also create a printable version of the <span class="productname">PostgreSQL</span>
documentation by converting it to <acronym class="acronym">RTF</acronym> and
applying minor formatting corrections using an office suite.
Depending on the capabilities of the particular office suite, you
can then convert the documentation to Postscript of
<acronym class="acronym">PDF</acronym>. The procedure below illustrates this
process using <span class="productname">Applixware</span>.
</p>
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Note</h3>
<p> It appears that current versions of the <span class="productname">PostgreSQL</span> documentation
trigger some bug in or exceed the size limit of OpenJade. If the
build process of the <acronym class="acronym">RTF</acronym> version hangs for a
long time and the output file still has size 0, then you may have
hit that problem. (But keep in mind that a normal build takes 5
to 10 minutes, so don't abort too soon.)
</p>
</div>
<div class="procedure">
<a name="id901654"></a><p class="title"><b><span class="productname">Applixware</span> <acronym class="acronym">RTF</acronym> Cleanup</b></p>
<p> <span class="application">OpenJade</span> omits specifying a default
style for body text. In the past, this undiagnosed problem led to
a long process of table of contents generation. However, with
great help from the <span class="productname">Applixware</span> folks
the symptom was diagnosed and a workaround is available.
</p>
<ol type="1">
<li>
<p> Generate the <acronym class="acronym">RTF</acronym> version by typing:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>gmake postgres.rtf</code></strong></pre>
<p>
</p>
</li>
<li>
<p> Repair the RTF file to correctly specify all styles, in
particular the default style. If the document contains
<code class="sgmltag-element">refentry</code> sections, one must also replace
formatting hints which tie a preceding paragraph to the current
paragraph, and instead tie the current paragraph to the
following one. A utility, <code class="command">fixrtf</code>, is
available in <code class="filename">doc/src/sgml</code> to accomplish
these repairs:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>./fixrtf --refentry postgres.rtf</code></strong></pre>
<p>
</p>
<p> The script adds <code class="literal">{\s0 Normal;}</code> as the zeroth
style in the document. According to
<span class="productname">Applixware</span>, the RTF standard would
prohibit adding an implicit zeroth style, though Microsoft Word
happens to handle this case. For repairing
<code class="sgmltag-element">refentry</code> sections, the script replaces
<code class="literal">\keepn</code> tags with <code class="literal">\keep</code>.
</p>
</li>
<li><p> Open a new document in <span class="productname">Applixware Words</span> and
then import the <acronym class="acronym">RTF</acronym> file.
</p></li>
<li>
<p> Generate a new table of contents (ToC) using
<span class="productname">Applixware</span>.
</p>
<ol type="a">
<li><p> Select the existing ToC lines, from the beginning of the first
character on the first line to the last character of the last
line.
</p></li>
<li><p> Build a new ToC using
<span class="guimenu">Tools</span> → <span class="guisubmenu">Book
Building</span> → <span class="guimenuitem">Create Table of
Contents</span>. Select the first three
levels of headers for inclusion in the ToC. This will replace
the existing lines imported in the RTF with a native
<span class="productname">Applixware</span> ToC.
</p></li>
<li>
<p> Adjust the ToC formatting by using
<span class="guimenu">Format</span> → <span class="guimenuitem">Style</span>,
selecting each of the three ToC styles, and adjusting the
indents for <code class="literal">First</code> and
<code class="literal">Left</code>. Use the following values:
</p>
<div class="informaltable"><table border="1">
<colgroup>
<col>
<col>
<col>
</colgroup>
<thead><tr>
<th>Style</th>
<th>First Indent (inches)</th>
<th>Left Indent (inches)</th>
</tr></thead>
<tbody>
<tr>
<td><code class="literal">TOC-Heading 1</code></td>
<td><code class="literal">0.4</code></td>
<td><code class="literal">0.4</code></td>
</tr>
<tr>
<td><code class="literal">TOC-Heading 2</code></td>
<td><code class="literal">0.8</code></td>
<td><code class="literal">0.8</code></td>
</tr>
<tr>
<td><code class="literal">TOC-Heading 3</code></td>
<td><code class="literal">1.2</code></td>
<td><code class="literal">1.2</code></td>
</tr>
</tbody>
</table></div>
<p>
</p>
</li>
</ol>
</li>
<li>
<p> Work through the document to:
</p>
<div class="itemizedlist"><ul type="disc">
<li><p> Adjust page breaks.
</p></li>
<li><p> Adjust table column widths.
</p></li>
</ul></div>
<p>
</p>
</li>
<li><p> Replace the right-justified page numbers in the Examples and
Figures portions of the ToC with correct values. This only takes
a few minutes.
</p></li>
<li><p> Delete the index section from the document if it is empty.
</p></li>
<li>
<p> Regenerate and adjust the table of contents.
</p>
<ol type="a">
<li><p> Select the ToC field.
</p></li>
<li><p> Select <span class="guimenu">Tools</span> → <span class="guisubmenu">Book
Building</span> → <span class="guimenuitem">Create Table of
Contents</span>.
</p></li>
<li><p> Unbind the ToC by selecting
<span class="guimenu">Tools</span> → <span class="guisubmenu">Field
Editing</span> → <span class="guimenuitem">Unprotect</span>.
</p></li>
<li><p> Delete the first line in the ToC, which is an entry for the
ToC itself.
</p></li>
</ol>
</li>
<li><p> Save the document as native <span class="productname">Applixware
Words</span> format to allow easier last minute editing
later.
</p></li>
<li><p> “<span class="quote">Print</span>” the document
to a file in Postscript format.
</p></li>
</ol>
</div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id902136"></a>G.3.5.Plain Text Files</h3></div></div></div>
<p> Several files are distributed as plain text, for reading during
the installation process. The <code class="filename">INSTALL</code> file
corresponds to <a href="installation.html" title="Chapter14. Installation Instructions">Chapter14, <i> Installation Instructions</i></a>, with some minor
changes to account for the different context. To recreate the
file, change to the directory <code class="filename">doc/src/sgml</code>
and enter <strong class="userinput"><code>gmake INSTALL</code></strong>. This will create
a file <code class="filename">INSTALL.html</code> that can be saved as text
with <span class="productname">Netscape Navigator</span> and put into
the place of the existing file.
<span class="productname">Netscape</span> seems to offer the best
quality for <acronym class="acronym">HTML</acronym> to text conversions (over
<span class="application">lynx</span> and
<span class="application">w3m</span>).
</p>
<p> The file <code class="filename">HISTORY</code> can be created similarly,
using the command <strong class="userinput"><code>gmake HISTORY</code></strong>. For the
file <code class="filename">src/test/regress/README</code> the command is
<strong class="userinput"><code>gmake regress_README</code></strong>.
</p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="id902244"></a>G.3.6.Syntax Check</h3></div></div></div>
<p> Building the documentation can take very long. But there is a
method to just check the correct syntax of the documentation
files, which only takes a few seconds:
</p>
<pre class="screen"><code class="prompt">doc/src/sgml$ </code><strong class="userinput"><code>gmake check</code></strong></pre>
<p>
</p>
</div>
</div></body>
</html>
|
