Skip to content

Commit 3143220

Browse files
author
Thomas G. Lockhart
committed
Add information on generating INSTALL and HISTORY from sgml sources.
1 parent f8a9892 commit 3143220

File tree

1 file changed

+160
-48
lines changed

1 file changed

+160
-48
lines changed

‎doc/src/sgml/docguide.sgml

Lines changed: 160 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,12 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.16 1999/06/14 07:36:11 thomas Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.17 1999/06/23 06:19:36 thomas Exp $
33
Documentation Guide
44
Thomas Lockhart
55

6-
$Log: docguide.sgml,v $
7-
Revision 1.16 1999/06/14 07:36:11 thomas
8-
Minor updates for release.
9-
106
Revision 1.15 1999/05/27 15:49:07 thomas
117
Markup fixes.
128
Update for v6.5 release.
139

14-
Revision 1.14 1999/01/07 03:01:27 thomas
15-
Fix column formatting for a table. No content changes.
16-
17-
Revision 1.13 1998/12/29 02:24:14 thomas
18-
Clean up to ensure tag completion as required by the newest versions
19-
of Norm's Modular Style Sheets and jade/docbook.
20-
From Vince Vielhaber <vev@michvhf.com>.
21-
2210
Revision 1.12 1998/12/18 16:17:29 thomas
2311
Include more details on editing with Emacs.
2412
Remove mention of the old "migration" flat files.
@@ -31,22 +19,11 @@ Minor editing and markup changes as a result of preparing the Postscript
3119
documentation for v6.4.
3220
Bigger updates to the installation instructions (install and config).
3321

34-
Revision 1.10 1998/10/25 00:25:30 thomas
35-
Update info on source files for v6.4.
36-
Should add/change ToDo list some more before release...
37-
38-
Revision 1.9 1998/10/15 05:46:54 momjian
39-
SGML updates from post 6.3.2 manual changes. Added pg_upgrade man page.
40-
4122
Revision 1.8 1998/08/17 16:17:07 thomas
4223
Bring document list closer to up to day.
4324
Add a note on sgml-tools that they are now working with jade and so
4425
may become the toolset of choice in the future.
4526

46-
Revision 1.7 1998/08/15 06:53:52 thomas
47-
Include working list of all documentation sources, with current status
48-
and plans for some of them.
49-
5027
-->
5128

5229
<appendix label="DG2" id="docguide">
@@ -115,27 +92,67 @@ Include working list of all documentation sources, with current status
11592
</thead>
11693

11794
<tbody>
118-
<row><entry>./COPYRIGHT</entry><entry>Copyright notice</entry></row>
119-
<row><entry>./INSTALL</entry><entry>Installation instructions (text from sgml->rtf->text)</entry></row>
120-
<row><entry>./README</entry><entry>Introductory info</entry></row>
121-
<row><entry>./register.txt</entry><entry>Registration message during make</entry></row>
122-
<row><entry>./doc/bug.template</entry><entry>Bug report template</entry></row>
123-
<row><entry>./doc/postgres.tar.gz</entry><entry>Integrated docs (<acronym>HTML</acronym>)</entry></row>
124-
<row><entry>./doc/programmer.ps.gz</entry><entry>Programmer's Guide (Postscript)</entry></row>
125-
<row><entry>./doc/programmer.tar.gz</entry><entry>Programmer's Guide (<acronym>HTML</acronym>)</entry></row>
126-
<row><entry>./doc/reference.ps.gz</entry><entry>Reference Manual (Postscript)</entry></row>
127-
<row><entry>./doc/reference.tar.gz</entry><entry>Reference Manual (<acronym>HTML</acronym>)</entry></row>
128-
<row><entry>./doc/tutorial.ps.gz</entry><entry>Introduction (Postscript)</entry></row>
129-
<row><entry>./doc/tutorial.tar.gz</entry><entry>Introduction (<acronym>HTML</acronym>)</entry></row>
130-
<row><entry>./doc/user.ps.gz</entry><entry>User's Guide (Postscript)</entry></row>
131-
<row><entry>./doc/user.tar.gz</entry><entry>User's Guide (<acronym>HTML</acronym>)</entry></row>
95+
<row>
96+
<entry>./COPYRIGHT</entry><entry>Copyright notice</entry>
97+
</row>
98+
<row>
99+
<entry>./INSTALL</entry>
100+
<entry>Installation instructions (text from sgml->rtf->text)</entry>
101+
</row>
102+
<row>
103+
<entry>./README</entry>
104+
<entry>Introductory info</entry>
105+
</row>
106+
<row>
107+
<entry>./register.txt</entry>
108+
<entry>Registration message during make</entry>
109+
</row>
110+
<row>
111+
<entry>./doc/bug.template</entry>
112+
<entry>Bug report template</entry>
113+
</row>
114+
<row>
115+
<entry>./doc/postgres.tar.gz</entry>
116+
<entry>Integrated docs (<acronym>HTML</acronym>)</entry>
117+
</row>
118+
<row>
119+
<entry>./doc/programmer.ps.gz</entry>
120+
<entry>Programmer's Guide (Postscript)</entry>
121+
</row>
122+
<row>
123+
<entry>./doc/programmer.tar.gz</entry>
124+
<entry>Programmer's Guide (<acronym>HTML</acronym>)</entry>
125+
</row>
126+
<row>
127+
<entry>./doc/reference.ps.gz</entry>
128+
<entry>Reference Manual (Postscript)</entry>
129+
</row>
130+
<row>
131+
<entry>./doc/reference.tar.gz</entry>
132+
<entry>Reference Manual (<acronym>HTML</acronym>)</entry>
133+
</row>
134+
<row>
135+
<entry>./doc/tutorial.ps.gz</entry>
136+
<entry>Introduction (Postscript)</entry>
137+
</row>
138+
<row>
139+
<entry>./doc/tutorial.tar.gz</entry>
140+
<entry>Introduction (<acronym>HTML</acronym>)</entry>
141+
</row>
142+
<row>
143+
<entry>./doc/user.ps.gz</entry>
144+
<entry>User's Guide (Postscript)</entry></row>
145+
<row>
146+
<entry>./doc/user.tar.gz</entry>
147+
<entry>User's Guide (<acronym>HTML</acronym>)</entry>
148+
</row>
132149
</tbody>
133150
</tgroup>
134151
</table>
135152
</para>
136153

137154
<para>
138-
There are man pages available for installation, as well as a large number
155+
There are man pages available, as well as a large number
139156
of plain-text README-type files throughout the <productname>Postgres</productname>
140157
source tree.
141158
</para>
@@ -166,19 +183,23 @@ Include working list of all documentation sources, with current status
166183

167184
<para>
168185
See
169-
<ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">Introduction to DocBook</ulink>
186+
<ulink url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html">
187+
Introduction to DocBook</ulink>
170188
for a nice "quickstart" summary of DocBook features.
171-
<ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/"> DocBook Elements</ulink>
189+
<ulink url="http://www.ora.com/homepages/dtdparse/docbook/3.0/">
190+
DocBook Elements</ulink>
172191
provides a powerful cross-reference for features of
173192
<productname>DocBook</productname>.
174193
</para>
175194

176195
<para>
177196
This documentation set is constructed using several tools, including
178197
James Clark's
179-
<ulink url="http://www.jclark.com/jade/"> <productname>jade</productname></ulink>
198+
<ulink url="http://www.jclark.com/jade/">
199+
<productname>jade</productname></ulink>
180200
and Norm Walsh's
181-
<ulink url="http://www.nwalsh.com/docbook/dsssl/">Modular DocBook Stylesheets</ulink>.
201+
<ulink url="http://www.nwalsh.com/docbook/dsssl/">
202+
Modular DocBook Stylesheets</ulink>.
182203
</para>
183204

184205
<para>
@@ -191,7 +212,7 @@ Include working list of all documentation sources, with current status
191212
<para>
192213
<ulink url="http://sunsite.unc.edu/pub/packages/TeX/systems/unix/">
193214
<productname>TeX</productname></ulink> is a supported format for
194-
<application>jade</application> output, but was not used at this time
215+
<application>jade</application> output, but is not used at this time
195216
for several reasons, including the inability to make minor format
196217
fixes before committing to hardcopy and generally inadequate table
197218
support in the <productname>TeX</productname>
@@ -999,7 +1020,97 @@ by typing
9991020
-->
10001021

10011022
<sect2>
1002-
<title><acronym>RTF</acronym> Cleanup Procedure</title>
1023+
<title>Text Hardcopy</title>
1024+
1025+
<para>
1026+
<filename>INSTALL</filename> and <filename>HISTORY</filename> are
1027+
updated for each release. For historical reasons, these files are
1028+
in plain text, but are derived from the newer
1029+
<acronym>SGML</acronym> sources.
1030+
</para>
1031+
1032+
<procedure>
1033+
<title>Plain Text Generation</title>
1034+
1035+
<para>
1036+
Both <filename>INSTALL</filename> and
1037+
<filename>HISTORY</filename> are generated from existing
1038+
<acronym>SGML</acronym> sources. They are extracted from the same
1039+
intermediate <acronym>RTF</acronym> file.
1040+
</para>
1041+
1042+
<step performance="required">
1043+
<para>
1044+
Generate <acronym>RTF</acronym> by typing:
1045+
<programlisting>
1046+
% cd doc/src/sgml
1047+
% make installation.rtf
1048+
</programlisting>
1049+
</para>
1050+
</step>
1051+
1052+
<step performance="required">
1053+
<para>
1054+
Import <filename>installation.rtf</filename> into
1055+
<productname>Applix Words</productname>.
1056+
</para>
1057+
</step>
1058+
1059+
<step performance="required">
1060+
<para>
1061+
Set the page width and margins.
1062+
</para>
1063+
1064+
<substeps>
1065+
<step performance="required">
1066+
<para>
1067+
Adjust the page width in File.PageSetup to 10 inches.
1068+
</para>
1069+
</step>
1070+
1071+
<step performance="required">
1072+
<para>
1073+
Select all text.
1074+
Adjust the right margin using the ruler to 9.5 inches. This
1075+
will give a maximum column width of 79 characters, within the
1076+
80 columns upper limit goal.
1077+
</para>
1078+
</step>
1079+
</substeps>
1080+
</step>
1081+
1082+
<step performance="required">
1083+
<para>
1084+
Lop off the parts of the document which are not needed.
1085+
</para>
1086+
1087+
<para>
1088+
For <filename>INSTALL</filename>, remove all release notes from
1089+
the end of the text, except for those from the current release.
1090+
For <filename>HISTORY</filename>, remove all text up to the
1091+
release notes, preserving and modifying the title and ToC.
1092+
</para>
1093+
</step>
1094+
1095+
<step performance="required">
1096+
<para>
1097+
Export the result as <quote>ASCII Layout</quote>.
1098+
</para>
1099+
</step>
1100+
1101+
<step performance="required">
1102+
<para>
1103+
Using emacs or vi, clean up the tabular information in
1104+
<filename>INSTALL</filename>. Remove the <quote>mailto</quote>
1105+
<acronym>URLs</acronym> for the porting contributors to shrink
1106+
the column heights.
1107+
</para>
1108+
</step>
1109+
</procedure>
1110+
</sect2>
1111+
1112+
<sect2>
1113+
<title>Postscript Hardcopy</title>
10031114

10041115
<para>
10051116
Several items must be addressed in generating Postscript
@@ -1018,7 +1129,7 @@ by typing
10181129

10191130
<step performance="required">
10201131
<para>
1021-
Generate the <acronym>RTF</acronym> input by typing
1132+
Generate the <acronym>RTF</acronym> input by typing (for example):
10221133
<programlisting>
10231134
% cd doc/src/sgml
10241135
% make tutorial.rtf
@@ -1048,7 +1159,7 @@ by typing
10481159
<para>
10491160
Not all documents have figures.
10501161
You can grep the <acronym>SGML</acronym> source files for
1051-
the string <quote>Graphic</quote> to identify those parts of the
1162+
the string <quote>graphic</quote> to identify those parts of the
10521163
documentation which may have figures. A few figures are replicated in
10531164
various parts of the documentation.
10541165
</para>
@@ -1093,7 +1204,8 @@ by typing
10931204

10941205
<step performance="required">
10951206
<para>
1096-
Export the document to a file in Postscript format.
1207+
<quote>Print</quote> the document
1208+
to a file in Postscript format.
10971209
</para>
10981210
</step>
10991211

0 commit comments

Comments
 (0)