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
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
|
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.43 2003/02/19 04:06:27 momjian Exp $ -->
<appendix id="docguide">
<title>Documentation</title>
<para>
<productname>PostgreSQL</productname> has four primary documentation
formats:
<itemizedlist>
<listitem>
<para>
Plain text, for pre-installation information
</para>
</listitem>
<listitem>
<para>
<acronym>HTML</acronym>, for on-line browsing and reference
</para>
</listitem>
<listitem>
<para>
Postscript, for printing
</para>
</listitem>
<listitem>
<para>
man pages, for quick reference.
</para>
</listitem>
</itemizedlist>
Additionally, a number of plain-text README-type files can be found
throughout the <productname>PostgreSQL</productname> source tree,
documenting various implementation issues.
</para>
<para>
The documentation is organized into several <quote>books</quote>:
<itemizedlist>
<listitem>
<para>
<citetitle>Tutorial</citetitle>: introduction for new users
</para>
</listitem>
<listitem>
<para>
<citetitle>User's Guide</citetitle>: documents the SQL implementation
</para>
</listitem>
<listitem>
<para>
<citetitle>Reference Manual</citetitle>: reference pages for programs and SQL commands
</para>
</listitem>
<listitem>
<para>
<citetitle>Administrator's Guide</citetitle>: installation and server maintenance
</para>
</listitem>
<listitem>
<para>
<citetitle>Programmer's Guide</citetitle>: programming client
applications and server extensions
</para>
</listitem>
<listitem>
<para>
<citetitle>Developer's Guide</citetitle>: assorted information
for developers of <productname>PostgreSQL</> proper
</para>
</listitem>
</itemizedlist>
All books are available as HTML and Postscript. The
<citetitle>Reference Manual</citetitle> contains reference entries which
are also shipped as man pages.
</para>
<para>
<acronym>HTML</acronym> documentation and man pages are part of a
standard distribution and are installed by default. Postscript
format documentation is available separately for download.
</para>
<sect1>
<title>DocBook</title>
<para>
The documentation sources are written in
<firstterm>DocBook</firstterm>, which is a markup language
superficially similar to <acronym>HTML</acronym>. Both of these
languages are applications of the <firstterm>Standard Generalized
Markup Language</firstterm>, <acronym>SGML</acronym>, which is
essentially a language for describing other languages. In what
follows, the terms DocBook and SGML are both used, but technically
they are not interchangeable.
</para>
<para>
<productname>DocBook</productname> allows an author to specify the
structure and content of a technical document without worrying
about presentation details. A document style defines how that
content is rendered into one of several final forms. DocBook is
maintained by the <ulink
url="http://www.oasis-open.org">OASIS</ulink> group. The <ulink
url="http://www.oasis-open.org/docbook">official DocBook
site</ulink> has good introductory and reference documentation and
a complete O'Reilly book for your online reading pleasure. The
<ulink url="http://www.freebsd.org/docproj/docproj.html">FreeBSD
Documentation Project</ulink> also uses DocBook and has some good
information, including a number of style guidelines that might be
worth considering.
</para>
</sect1>
<sect1 id="doc-toolsets">
<title>Tool Sets</title>
<para>
The following tools are used to process the documentation. Some
may be optional, as noted.
<variablelist>
<varlistentry>
<term><ulink url="http://www.oasis-open.org/docbook/sgml/">DocBook DTD</ulink></term>
<listitem>
<para>
This is the definition of DocBook itself. We currently use
version 3.1; you cannot use later or earlier versions. Note
that there is also an <acronym>XML</acronym> version of DocBook
-- do not use that.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879 character entities</ulink></term>
<listitem>
<para>
These are required by DocBook but are distributed separately
because they are maintained by ISO.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://openjade.sourceforge.net">OpenJade</ulink></term>
<listitem>
<para>
This is the base package of <acronym>SGML</acronym> processing.
It contains an <acronym>SGML</acronym> parser, a
<acronym>DSSSL</acronym> processor (that is, a program to
convert <acronym>SGML</acronym> to other formats using
<acronym>DSSSL</acronym> stylesheets), as well as a number of
related tools. <productname>Jade</productname> is now being
maintained by the OpenJade group, no longer by James Clark.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://docbook.sourceforge.net/projects/dsssl/index.html">DocBook DSSSL Stylesheets</ulink></term>
<listitem>
<para>
These contain the processing instructions for converting the
DocBook sources to other formats, such as
<acronym>HTML</acronym>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://docbook2x.sourceforge.net">DocBook2X tools</ulink></term>
<listitem>
<para>
This optional package is used to create man pages. It has a
number of prerequisite packages of its own. Check the web
site.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><ulink url="http://jadetex.sourceforge.net">JadeTeX</ulink></term>
<listitem>
<para>
If you want to, you can also install
<productname>JadeTeX</productname> to use
<productname>TeX</productname> as a formatting backend for
<productname>Jade</productname>.
<application>JadeTeX</application> can create Postscript or
<acronym>PDF</acronym> files (the latter with bookmarks).
</para>
<para>
However, the output from <application>JadeTeX</application> is
inferior to what you get from the <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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
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
docs mailing list and we will include that information here.
</para>
<sect2>
<title><productname>Linux</productname> <acronym>RPM</acronym> Installation</title>
<para>
Many vendors provide a complete RPM set for DocBook processing in
their distribution, which is usually based on the <ulink
url="http://sources.redhat.com/docbook-tools/">docbook-tools</ulink>
effort at Red Hat Software. Look for an <quote>SGML</quote>
option while installing, or the following packages:
<filename>sgml-common</filename>, <filename>docbook</filename>,
<filename>stylesheets</filename>, <filename>openjade</filename>
(or <filename>jade</filename>). Possibly
<filename>sgml-tools</filename> 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.
</para>
</sect2>
<sect2>
<title>FreeBSD Installation</title>
<para>
The FreeBSD Documentation Project is itself a heavy user of
DocBook, so it comes as no surprise that there is a full set of
<quote>ports</quote> of the documentation tools available on
FreeBSD. The following ports need to be installed to build the
documentation on FreeBSD.
<itemizedlist>
<listitem>
<para><filename>textproc/sp</filename></para>
</listitem>
<listitem>
<para><filename>textproc/openjade</filename></para>
</listitem>
<listitem>
<para><filename>textproc/docbook-310</filename></para>
</listitem>
<listitem>
<para><filename>textproc/iso8879</filename></para>
</listitem>
<listitem>
<para><filename>textproc/dsssl-docbook-modular</filename></para>
</listitem>
</itemizedlist>
A number of things from <filename>/usr/ports/print</filename>
(<filename>tex</filename>, <filename>jadetex</filename>) might
also be of interest.
</para>
<para>
It's possible that the ports do not update the main catalog file
in <filename>/usr/local/share/sgml/catalog</filename>. Be sure to
have the following line in there:
<programlisting>
CATALOG "/usr/local/share/sgml/docbook/3.1/catalog"
</programlisting>
If you do not want to edit the file you can also set the
environment variable <envar>SGML_CATALOG_FILES</envar> to a
colon-separated list of catalog files (such as the one above).
</para>
<para>
More information about the FreeBSD documentation tools can be
found in the <ulink
url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/tools.html">FreeBSD
Documentation Project's instructions</ulink>.
</para>
</sect2>
<sect2>
<title>Debian Packages</title>
<para>
There is a full set of packages of the documentation tools
available for <productname>Debian GNU/Linux</productname>.
To install, simply use:
<programlisting>
apt-get install jade
apt-get install docbook
apt-get install docbook-stylesheets
</programlisting>
</para>
</sect2>
<sect2>
<title>Manual Installation from Source</title>
<para>
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 <quote>fancy</quote> features. For
details, you should study the documentation of the respective
package, and read <acronym>SGML</acronym> introductory material.
</para>
<sect3>
<title>Installing OpenJade</title>
<procedure>
<step>
<para>
The installation of OpenJade offers a GNU-style
<literal>./configure; make; make install</literal> build
process. Details can be found in the OpenJade source
distribution. In a nutshell:
<synopsis>
./configure --enable-default-catalog=/usr/local/share/sgml/catalog
make
make install
</synopsis>
Be sure to remember where you put the <quote>default
catalog</quote>; you will need it below. You can also leave
it off, but then you will have to set the environment variable
<envar>SGML_CATALOG_FILES</envar> to point to the file
whenever you use <application>jade</application> later on.
(This method is also an option if OpenJade is already
installed and you want to install the rest of the toolchain
locally.)
</para>
</step>
<step id="doc-openjade-install">
<para>
Additionally, you should install the files
<filename>dsssl.dtd</filename>, <filename>fot.dtd</filename>,
<filename>style-sheet.dtd</filename>, and
<filename>catalog</filename> from the
<filename>dsssl</filename> directory somewhere, perhaps into
<filename>/usr/local/share/sgml/dsssl</filename>. It's
probably easiest to copy the entire directory:
<synopsis>
cp -R dsssl /usr/local/share/sgml
</synopsis>
</para>
</step>
<step>
<para>
Finally, create the file
<filename>/usr/local/share/sgml/catalog</filename> and add
this line to it:
<programlisting>
CATALOG "dsssl/catalog"
</programlisting>
(This is a relative path reference to the file installed in
<xref linkend="doc-openjade-install">. Be sure to adjust it
if you chose your installation layout differently.)
</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<procedure>
<step>
<para>
Obtain the <ulink
url="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip">DocBook
V3.1</ulink> distribution.
</para>
</step>
<step>
<para>
Create the directory
<filename>/usr/local/share/sgml/docbook31</filename> and change
to it. (The exact location is irrelevant, but this one is
reasonable within the layout we are following here.)
<screen>
<prompt>$ </prompt><userinput>mkdir /usr/local/share/sgml/docbook31</userinput>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
</screen>
</para>
</step>
<step>
<para>
Unpack the archive.
<screen>
<prompt>$ </prompt><userinput>unzip -a ...../docbk31.zip</userinput>
</screen>
(The archive will unpack its files into the current directory.)
</para>
</step>
<step>
<para>
Edit the file
<filename>/usr/local/share/sgml/catalog</filename> (or whatever
you told jade during installation) and put a line like this
into it:
<programlisting>
CATALOG "docbook31/docbook.cat"
</programlisting>
</para>
</step>
<step>
<para>
Optionally, you can edit the file
<filename>docbook.cat</filename> and comment out or remove the
line containing <literal>DTDDECL</literal>. If you do not then
you will get warnings from <application>jade</application>, but
there is no further harm.
</para>
</step>
<step>
<para>
Download the <ulink
url="http://www.oasis-open.org/cover/ISOEnts.zip">ISO 8879
character entities</ulink> archive, unpack it, and put the
files in the same directory you put the DocBook files in.
<screen>
<prompt>$ </prompt><userinput>cd /usr/local/share/sgml/docbook31</userinput>
<prompt>$ </prompt><userinput>unzip ...../ISOEnts.zip</userinput>
</screen>
</para>
</step>
<step>
<para>
Run the following command in the directory with the DocBook and ISO files:
<programlisting>
perl -pi -e 's/iso-(.*).gml/ISO\1/g' docbook.cat
</programlisting>
(This fixes a mixup between the names used in the DocBook
catalog file and the actual names of the ISO character entity
files.)
</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Installing the DocBook <acronym>DSSSL</acronym> Style Sheets</title>
<para>
To install the style sheets, unzip and untar the distribution and
move it to a suitable place, for example
<filename>/usr/local/share/sgml</filename>. (The archive will
automatically create a subdirectory.)
<screen>
<prompt>$</prompt> <userinput>gunzip docbook-dsssl-1.<replaceable>xx</>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -C /usr/local/share/sgml -xf docbook-dsssl-1.<replaceable>xx</>.tar</userinput>
</screen>
</para>
<para>
The usual catalog entry in
<filename>/usr/local/share/sgml/catalog</filename> can also be
made:
<programlisting>
CATALOG "docbook-dsssl--1.<replaceable>xx</>/catalog
</programlisting>
Because stylesheets change rather often, and it's sometimes
beneficial to try out alternative versions,
<productname>PostgreSQL</productname> doesn't use this catalog
entry. See <xref linkend="doc-build"> for information about how
to select the stylesheets instead.
</para>
</sect3>
<sect3>
<title>Installing <productname>JadeTeX</productname></title>
<para>
To install and use <productname>JadeTeX</productname>, you will
need a working installation of <productname>TeX</productname> and
<productname>LaTeX2e</productname>, including the supported
<productname>tools</productname> and
<productname>graphics</productname> packages,
<productname>Babel</productname>,
<productname><acronym>AMS</acronym> fonts</productname> and
<productname>AMS-LaTeX</productname>, the
<productname><acronym>PSNFSS</acronym></productname> extension
and companion kit of <quote>the 35 fonts</quote>, the
<productname>dvips</productname> program for generating
<productname>PostScript</productname>, the macro packages
<productname>fancyhdr</productname>,
<productname>hyperref</productname>,
<productname>minitoc</productname>,
<productname>url</productname> and
<productname>ot2enc</productname>. All of these can be found on
your friendly neighborhood <ulink
url="http://www.ctan.org"><acronym>CTAN</acronym></ulink> site.
The installation of the <application>TeX</application> base
system is far beyond the scope of this introduction. Binary
packages should be available for any system that can run
<application>TeX</application>.
</para>
<para>
Before you can use <application>JadeTeX</application> with the
<productname>PostgreSQL</productname> documentation sources, you
will need to increase the size of
<application>TeX</application>'s internal data structures.
Details on this can be found in the <application>JadeTeX</application>
installation instructions.
</para>
<para>
Once that is finished you can install <application>JadeTeX</application>:
<screen>
<prompt>$</prompt> <userinput>gunzip jadetex-<replaceable>xxx</replaceable>.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar xf jadetex-<replaceable>xxx</replaceable>.tar</userinput>
<prompt>$</prompt> <userinput>cd jadetex</userinput>
<prompt>$</prompt> <userinput>make install</userinput>
<prompt>$</prompt> <userinput>mktexlsr</userinput>
</screen>
The last two need to be done as <systemitem>root</systemitem>.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="doc-build">
<title>Building The Documentation</title>
<para>
Before you can build the documentation you need to run the
<filename>configure</filename> script as you would when building
the programs themselves. Check the output near the end of the run,
it should look something like this:
<screen>
<computeroutput>
checking for onsgmls... onsgmls
checking for openjade... openjade
checking for DocBook V3.1... yes
checking for DocBook stylesheets... /usr/lib/sgml/stylesheets/nwalsh-modular
checking for sgmlspl... sgmlspl
</computeroutput>
</screen>
If neither <filename>onsgmls</filename> nor
<filename>nsgmls</filename> were found then you will not see the
remaining 4 lines. <filename>nsgmls</filename> is part of the Jade
package. If <quote>DocBook V3.1</quote> 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
<envar>DOCBOOKSTYLE</envar> to the location and rerun
<filename>configure</filename> afterwards.
</para>
<para>
Once you have everything set up, change to the directory
<filename>doc/src/sgml</filename> and run one of the following
commands: (Remember to use GNU make.)
<itemizedlist>
<listitem>
<para>
To build the <acronym>HTML</acronym> version of the
<citetitle>Administrator's Guide</citetitle>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.html</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
For the RTF version of the same:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.rtf</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
To get a <acronym>DVI</acronym> version via
<productname>JadeTeX</productname>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.dvi</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
And Postscript from the <acronym>DVI</acronym>:
<screen>
<prompt>doc/src/sgml$ </prompt><userinput>gmake admin.ps</userinput>
</screen>
</para>
<note>
<para>
The official Postscript format documentation is generated
differently. See <xref linkend="doc-hardcopy"> below.
</para>
</note>
</listitem>
</itemizedlist>
The other books can be built with analogous commands by replacing
<literal>admin</literal> with one of <literal>developer</literal>,
<literal>programmer</literal>, <literal>tutorial</literal>, or
<literal>user</literal>. Using <literal>postgres</literal> builds
an integrated version of all 5 books, which is practical since the
browser interface makes it easy to move around all of the
documentation by just clicking.
</para>
<sect2>
<title>HTML</title>
<para>
When building <acronym>HTML</acronym> documentation in
<filename>doc/src/sgml</filename>, some of the resulting files
will possibly (or quite certainly) have conflicting names between
books. Therefore the files are not in that directory in the
regular distribution. Instead, the files belonging to each book
are stored in a tar archive that is unpacked at installation time.
To create a set of <acronym>HTML</acronym> documentation packages
use the commands
<programlisting>
cd doc/src
gmake tutorial.tar.gz
gmake user.tar.gz
gmake admin.tar.gz
gmake programmer.tar.gz
gmake postgres.tar.gz
gmake install
</programlisting>
In the distribution, these archives live in the
<filename>doc</filename> directory and are installed by default
with <command>gmake install</command>.
</para>
</sect2>
<sect2 id="doc-manpages">
<title>Manpages</title>
<para>
We use the <application>docbook2man</application> utility to
convert <productname>DocBook</productname>
<sgmltag>REFENTRY</sgmltag> pages to *roff output suitable for man
pages. The man pages are also distributed as a tar archive,
similar to the <acronym>HTML</acronym> version. To create the man page package, use the commands
<programlisting>
cd doc/src
gmake man
</programlisting>
which will result in a tar file being generated in the
<filename>doc/src</filename> directory.
</para>
<para>
The man build leaves a lot of confusing output, and special care
must be taken to produce quality results. There is still room for
improvement in this area.
</para>
</sect2>
<sect2 id="doc-hardcopy">
<title>Hardcopy Generation</title>
<para>
The hardcopy Postscript documentation is generated by converting the
<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
importing into <productname>Applixware</productname>.
After a little cleanup (see the following
section) the output is <quote>printed</quote> to a postscript file.
</para>
<!--
<para>
Some figures were redrawn to avoid having bitmap
<acronym>GIF</acronym> files in the hardcopy documentation. One
figure, of the system catalogs, was sufficiently complex that there
was not time to redraw it. It was converted to fit using the
following commands:
<programlisting>
% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
</programlisting>
</para>
-->
<para>
Several areas are addressed while generating Postscript
hardcopy, including RTF repair, ToC generation, and page break
adjustments.
</para>
<procedure>
<title><productname>Applixware</productname> <acronym>RTF</acronym> Cleanup</title>
<para>
<application>jade</application>, an integral part of the
hardcopy procedure, omits specifying a default style for body
text. In the past, this undiagnosed problem led to a long process
of Table of Contents (ToC) generation. However, with great help
from the <productname>Applixware</productname> folks the symptom was diagnosed and a
workaround is available.
</para>
<step performance="required">
<para>
Generate the <acronym>RTF</acronym> input by typing (for example):
<programlisting>
% cd doc/src/sgml
% make tutorial.rtf
</programlisting>
</para>
</step>
<step performance="required">
<para>
Repair the RTF file to correctly specify all
styles, in particular the default style. If the document
contains <sgmltag>REFENTRY</sgmltag> sections, one must also
replace formatting hints which tie a
<emphasis>preceding</emphasis> paragraph to the current
paragraph, and instead tie the current paragraph to the
following one. A utility, <application>fixrtf</application> is
available in
<filename>doc/src/sgml</filename> to accomplish these repairs:
<programlisting>
% cd doc/src/sgml
% fixrtf tutorial.rtf
</programlisting>
or
<programlisting>
% cd doc/src/sgml
% fixrtf --refentry reference.rtf
</programlisting>
</para>
<para>
The script adds <literal>{\s0 Normal;}</literal> as
the zero-th style in the document. According to <productname>Applixware</productname>, the
RTF standard would prohibit adding an implicit zero-th style,
though M$Word happens to handle this case. For repairing
<sgmltag>REFENTRY</sgmltag> sections, the script replaces
<literal>\keepn</literal> tags with <literal>\keep</literal>.
</para>
</step>
<step performance="required">
<para>
Open a new document in <productname>Applixware Words</productname> and
then import the <acronym>RTF</acronym> file.
</para>
</step>
<step performance="required">
<para>
Generate a new ToC using <productname>Applixware</productname>.
</para>
<substeps>
<step>
<para>
Select the existing ToC lines, from the beginning of the first
character on the first line to the last character of the last
line.
</para>
</step>
<step>
<para>
Build a new ToC using
<literal>Tools.BookBuilding.CreateToC</literal>. 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
<productname>Applixware</productname> ToC.
</para>
</step>
<step>
<para>
Adjust the ToC formatting by using
<literal>Format.Style</literal>, selecting each of the three
ToC styles, and adjusting the indents for <literal>First</literal> and
<literal>Left</literal>. Use the following values:
<table>
<title>Indent Formatting for Table of Contents</title>
<tgroup cols="3">
<thead>
<row>
<entry>
Style
</entry>
<entry>
First Indent (inches)
</entry>
<entry>
Left Indent (inches)
</entry>
</row>
</thead>
<tbody>
<row>
<entry>
<literal>TOC-Heading 1</literal>
</entry>
<entry>
<literal>0.4</literal>
</entry>
<entry>
<literal>0.4</literal>
</entry>
</row>
<row>
<entry>
<literal>TOC-Heading 2</literal>
</entry>
<entry>
<literal>0.8</literal>
</entry>
<entry>
<literal>0.8</literal>
</entry>
</row>
<row>
<entry>
<literal>TOC-Heading 3</literal>
</entry>
<entry>
<literal>1.2</literal>
</entry>
<entry>
<literal>1.2</literal>
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</step>
</substeps>
</step>
<step performance="required">
<para>
Work through the document to:
<itemizedlist>
<listitem>
<para>
Adjust page breaks.
</para>
</listitem>
<listitem>
<para>
Adjust table column widths.
</para>
</listitem>
<listitem>
<para>
Insert figures into the document. Center each figure on the page using
the centering margins button on the <productname>Applixware</productname> toolbar.
<note>
<para>
Not all documents have figures.
You can grep the <acronym>SGML</acronym> source files for
the string <literal>graphic</literal> to identify those parts of the
documentation that may have figures. A few figures are replicated in
various parts of the documentation.
</para>
</note>
</para>
</listitem>
</itemizedlist>
</para>
</step>
<step performance="required">
<para>
Replace the right-justified page numbers in the Examples and
Figures portions of the ToC with
correct values. This only takes a few minutes per document.
</para>
</step>
<!--
Later stylesheets seem to not need this adjustment - thomas 2001-11-29
<step performance="required">
<para>
If a bibliography is present, remove the <firstterm>short
form</firstterm> reference title from each entry. The
<productname>DocBook</productname> stylesheets from Norm Walsh
seem to print these out, even though this is a subset of the
information immediately following.
</para>
</step>
-->
<step performance="optional">
<para>
Delete the index section from the document if it is empty.
</para>
</step>
<step performance="required">
<para>
Regenerate and adjust the table of contents.
</para>
<substeps>
<step>
<para>
Select the ToC field.
</para>
</step>
<step>
<para>
Select
<literal>Tools->Book Building->Create Table of
Contents</literal>.
</para>
</step>
<step>
<para>
Unbind the ToC by selecting
<literal>Tools->Field Editing->Unprotect</literal>.
</para>
</step>
<step>
<para>
Delete the first line in the ToC, which is an entry for the
ToC itself.
</para>
</step>
</substeps>
</step>
<step performance="required">
<para>
Save the document as native <productname>Applixware Words</productname> format to allow easier last
minute editing later.
</para>
</step>
<step performance="required">
<para>
<quote>Print</quote> the document
to a file in Postscript format.
</para>
</step>
<step performance="required">
<para>
Compress the Postscript file using <application>gzip</application>.
Place the compressed file into the <filename>doc</filename> directory.
</para>
</step>
</procedure>
</sect2>
<sect2>
<title>Plain Text Files</title>
<para>
Several files are distributed as plain text, for reading during
the installation process. The <filename>INSTALL</filename> file
corresponds to the chapter in the <citetitle>Administrator's
Guide</citetitle>, with some minor changes to account for the
different context. To recreate the file, change to the directory
<filename>doc/src/sgml</filename> and enter <userinput>gmake
INSTALL</userinput>. This will create a file
<filename>INSTALL.html</filename> that can be saved as text with
<productname>Netscape Navigator</productname> and put into the
place of the existing file. <productname>Netscape</productname>
seems to offer the best quality for <acronym>HTML</acronym> to
text conversions (over <application>lynx</application> and
<application>w3m</application>).
</para>
<para>
The file <filename>HISTORY</filename> can be created similarly,
using the command <userinput>gmake HISTORY</userinput>. For the
file <filename>src/test/regress/README</filename> the command is
<userinput>gmake regress_README</userinput>.
</para>
<!--
* This is how you can create text files via RTF and ApplixWare,
* for historical reference.
<procedure>
<title>Plain Text Generation</title>
<para>
Both <filename>INSTALL</filename> and
<filename>HISTORY</filename> are generated from existing
<acronym>SGML</acronym> sources. They are extracted from the same
intermediate <acronym>RTF</acronym> file.
</para>
<step performance="required">
<para>
Generate <acronym>RTF</acronym> by typing:
<programlisting>
% cd doc/src/sgml
% make installation.rtf
</programlisting>
</para>
</step>
<step performance="required">
<para>
Import <filename>installation.rtf</filename> into
<productname>Applix Words</productname>.
</para>
</step>
<step performance="required">
<para>
Set the page width and margins.
</para>
<substeps>
<step performance="required">
<para>
Adjust the page width in File.PageSetup to 10 inches.
</para>
</step>
<step performance="required">
<para>
Select all text.
Adjust the right margin using the ruler to 9.5 inches. This
will give a maximum column width of 79 characters, within the
80 columns upper limit goal.
</para>
</step>
</substeps>
</step>
<step performance="required">
<para>
Lop off the parts of the document that are not needed.
</para>
<para>
For <filename>INSTALL</filename>, remove all release notes from
the end of the text, except for those from the current release.
For <filename>HISTORY</filename>, remove all text up to the
release notes, preserving and modifying the title and ToC.
</para>
</step>
<step performance="required">
<para>
Export the result as <literal>ASCII Layout</literal>.
</para>
</step>
<step performance="required">
<para>
Using emacs or vi, clean up the tabular information in
<filename>INSTALL</filename>. Remove the <literal>mailto</literal>
<acronym>URLs</acronym> for the porting contributors to shrink
the column heights.
</para>
</step>
</procedure>
-->
</sect2>
</sect1>
<sect1 id="doc-sources">
<title>Documentation Authoring</title>
<para>
<acronym>SGML</acronym> and <productname>DocBook</productname> do
not suffer from an oversupply of open-source authoring tools. The
most common tool set is the
<productname>Emacs</productname>/<productname>XEmacs</productname>
editor with appropriate editing mode. On some systems
these tools are provided in a typical full installation.
</para>
<sect2>
<title>Emacs/PSGML</title>
<para>
<productname>PSGML</productname> is the most common and most
powerful mode for editing <acronym>SGML</acronym> documents.
When properly configured, it will allow you to use
<application>Emacs</application> to insert tags and check markup
consistency. You could use it for <acronym>HTML</acronym> as
well. Check the <ulink
url="http://www.lysator.liu.se/projects/about_psgml.html">PSGML
web site</ulink> for downloads, installation instructions, and
detailed documentation.
</para>
<para>
There is one important thing to note with
<productname>PSGML</productname>: its author assumed that your
main <acronym>SGML</acronym> <acronym>DTD</acronym> directory
would be <filename>/usr/local/lib/sgml</filename>. If, as in the
examples in this chapter, you use
<filename>/usr/local/share/sgml</filename>, you have to
compensate for this, either by setting
<envar>SGML_CATALOG_FILES</envar> environment variable, or you
can customize your <productname>PSGML</productname> installation
(its manual tells you how).
</para>
<para>
Put the following in your <filename>~/.emacs</filename>
environment file (adjusting the path names to be appropriate for
your system):
<programlisting>
; ********** for SGML mode (psgml)
(setq sgml-omittag t)
(setq sgml-shorttag t)
(setq sgml-minimize-attributes nil)
(setq sgml-always-quote-attributes t)
(setq sgml-indent-step 1)
(setq sgml-indent-data t)
(setq sgml-parent-document nil)
(setq sgml-default-dtd-file "./reference.ced")
(setq sgml-exposed-tags nil)
(setq sgml-catalog-files '("/usr/local/share/sgml/catalog"))
(setq sgml-ecat-files nil)
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t )
</programlisting>
and in the same file add an entry for <acronym>SGML</acronym>
into the (existing) definition for
<varname>auto-mode-alist</varname>:
<programlisting>
(setq
auto-mode-alist
'(("\\.sgml$" . sgml-mode)
))
</programlisting>
</para>
<para>
Currently, each <acronym>SGML</acronym> source file has the
following block at the end of the file:
<programlisting>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
</programlisting>
This will set up a number of editing mode parameters even if you
do not set up your <filename>~/.emacs</filename> file, but it is
a bit unfortunate, since if you followed the installation
instructions above, then the catalog path will not match your
location. Hence you might need to turn off local variables:
<programlisting>
(setq inhibit-local-variables t)
</programlisting>
</para>
<para>
The <productname>PostgreSQL</productname> distribution includes a
parsed DTD definitions file <filename>reference.ced</filename>.
You may find that when using PSGML, a comfortable way of working
with these separate files of book parts is to insert a proper
<literal>DOCTYPE</literal> declaration while you're editing them.
If you are working on this source, for instance, it is an
appendix chapter, so you would specify the document as an
<quote>appendix</quote> instance of a DocBook document by making
the first line look like this:
<programlisting>
<!doctype appendix PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
</programlisting>
This means that anything and everything that reads
<acronym>SGML</acronym> will get it right, and I can verify the
document with <command>nsgmls -s docguide.sgml</command>. (But
you need to take out that line before building the entire
documentation set.)
</para>
</sect2>
<sect2>
<title>Other Emacs modes</title>
<para>
<productname>GNU Emacs</productname> ships with a different SGML
mode, which is not quite as powerful as
<productname>PSGML</productname>, but it's less confusing and
lighter weight. Also, it offers syntax highlighting (font lock),
which can be very helpful.
</para>
<para>
Norm Walsh offers a major <ulink
url="http://nwalsh.com/emacs/docbookide/index.html">mode
specifically for DocBook</ulink> which also has font-lock and a
number of features to reduce typing.
</para>
</sect2>
</sect1>
<sect1 id="doc-style">
<title>Style Guide</title>
<sect2>
<title>Reference Pages</title>
<para>
Reference pages should follow a standard layout. This allows
users to find the desired information more quickly, and it also
encourages writers to document all relevant aspects of a command.
Consistency is not only desired among
<productname>PostgreSQL</productname> reference pages, but also
with reference pages provided by the operating system and other
packages. Hence the following guidelines have been developed.
They are for the most part consistent with similar guidelines
established by various operating systems.
</para>
<para>
Reference pages that describe executable commands should contain
the following sections, in this order. Sections that do not apply
may be omitted. Additional top-level sections should only be used
in special circumstances; often that information belongs in the
<quote>Usage</quote> section.
<variablelist>
<varlistentry>
<term>Name</term>
<listitem>
<para>
This section is generated automatically. It contains the
command name and a half-sentence summary of its functionality.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Synopsis</term>
<listitem>
<para>
This section contains the syntax diagram of the command. The
synopsis should normally not list each command-line option;
that is done below. Instead, list the major components of the
command line, such as where input and output files go.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Description</term>
<listitem>
<para>
Several paragraphs explaining what the command does.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Options</term>
<listitem>
<para>
A list describing each command-line option. If there are a
lot of options, subsections may be used.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Exit Status</term>
<listitem>
<para>
If the program uses 0 for success and non-zero for failure,
then you do not need to document it. If there is a meaning
behind the different non-zero exit codes, list them here.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Usage</term>
<listitem>
<para>
Describe any sublanguage or run-time interface of the program.
If the program is not interactive, this section can usually be
omitted. Otherwise, this section is a catch-all for
describing run-time features. Use subsections if appropriate.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Environment</term>
<listitem>
<para>
List all environment variables that the program might use.
Try to be complete; even seemingly trivial variables like
<envar>SHELL</envar> might be of interest to the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Files</term>
<listitem>
<para>
List any files that the program might access implicitly. That
is, do not list input and output files that were specified on
the command line, but list configuration files, etc.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Diagnostics</term>
<listitem>
<para>
Explain any unusual output that the program might create.
Refrain from listing every possible error message. This is a
lot of work and has little use in practice. But if, say, the
error messages have a standard format that the user can parse,
this would be the place to explain it.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Notes</term>
<listitem>
<para>
Anything that doesn't fit elsewhere, but in particular bugs,
implementation flaws, security considerations, compatibility
issues.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Examples</term>
<listitem>
<para>
Examples
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>History</term>
<listitem>
<para>
If there were some major milestones in the history of the
program, they might be listed here. Usually, this section can
be omitted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>See Also</term>
<listitem>
<para>
Cross-references, listed in the following order: other
<productname>PostgreSQL</productname> command reference pages,
<productname>PostgreSQL</productname> SQL command reference
pages, citation of <productname>PostgreSQL</productname>
manuals, other reference pages (e.g., operating system, other
packages), other documentation. Items in the same group are
listed alphabetically.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Reference pages describing SQL commands should contain the
following sections: Name, Synopsis, Description, Parameters,
Usage, Diagnostics, Notes, Examples, Compatibility, History, See
Also. The Parameters section is like the Options section, but
there is more freedom about which clauses of the command can be
listed. The Compatibility section should explain to what extent
this command conforms to the SQL standard(s), or to which other
database system it is compatible. The See Also section of SQL
commands should list SQL commands before cross-references to
programs.
</para>
</sect2>
</sect1>
</appendix>
<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
|