From f1f9ec3344d40961db0ca62cccd9f8f519f5abf2 Mon Sep 17 00:00:00 2001
From: "Thomas G. Lockhart" <lockhart@fourpalms.org>
Date: Fri, 30 Oct 1998 19:37:19 +0000
Subject: [PATCH] Minor editing and markup changes as a result of preparing the
Postscript documentation for v6.4. Bigger updates to the installation
instructions (install and config).
---
doc/src/sgml/Makefile | 4 +-
doc/src/sgml/admin.sgml | 23 +-
doc/src/sgml/config.sgml | 2 +-
doc/src/sgml/datatype.sgml | 35 +--
doc/src/sgml/docguide.sgml | 525 ++++++++++++++++++---------------
doc/src/sgml/info.sgml | 7 +-
doc/src/sgml/install.sgml | 310 ++++++++++++-------
doc/src/sgml/installation.sgml | 13 +-
doc/src/sgml/jdbc.sgml | 187 +++++-------
doc/src/sgml/libpgtcl.sgml | 7 +-
doc/src/sgml/libpq.sgml | 2 +-
doc/src/sgml/odbc.sgml | 3 +-
doc/src/sgml/page.sgml | 2 +
doc/src/sgml/ports.sgml | 156 +++++-----
doc/src/sgml/postgres.sgml | 21 +-
doc/src/sgml/programmer.sgml | 30 +-
doc/src/sgml/reference.sgml | 25 +-
doc/src/sgml/spi.sgml | 36 +--
doc/src/sgml/trigger.sgml | 7 +-
doc/src/sgml/user.sgml | 17 +-
doc/src/sgml/xaggr.sgml | 66 +++--
doc/src/sgml/xplang.sgml | 2 +-
doc/src/sgml/y2k.sgml | 2 +-
23 files changed, 831 insertions(+), 651 deletions(-)
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 83f14df581d..47b2c19f99a 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -8,7 +8,7 @@
#
#
# IDENTIFICATION
-# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.6 1998/09/30 05:41:39 thomas Exp $
+# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.7 1998/10/30 19:36:51 thomas Exp $
#
#----------------------------------------------------------------------------
@@ -119,5 +119,5 @@ distclean::
# Graphics
%.gif:
- cp -p ../graphics/%.gif .
+ cp -p ../graphics/$@ .
diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml
index 5b571d61d17..51330c90fb3 100644
--- a/doc/src/sgml/admin.sgml
+++ b/doc/src/sgml/admin.sgml
@@ -1,11 +1,16 @@
<!--
-$header$
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.7 1998/10/30 19:36:53 thomas Exp $
Postgres Administrator's Guide.
Derived from postgres.sgml.
-thomas 1998-02-27
+thomas 1998-10-27
+
+$Log: admin.sgml,v $
+Revision 1.7 1998/10/30 19:36:53 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
-$log$
-->
@@ -38,7 +43,7 @@ $log$
<Title>PostgreSQL Administrator's Guide</Title>
<BookInfo>
- <ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
+ <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@@ -61,12 +66,13 @@ $log$
<AuthorInitials>TGL</AuthorInitials>
-->
- <Date>(last updated 1998-02-23)</Date>
+ <Date>(last updated 1998-10-27)</Date>
</BookBiblio>
<LegalNotice>
<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
+<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
+by the Postgres Global Development Group.
</Para>
</LegalNotice>
@@ -114,8 +120,9 @@ It provides SQL92/SQL3 language support,
&biblio;
-<!-- Don't bother with an index until we get some index entries.
- -- - thomas 1998-10-26
+<!--
+Don't bother with an index until we get some index entries.
+- thomas 1998-10-26
<index id="index">
</index>
-->
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index 0ade15cd3ef..7f44b8992a2 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1,5 +1,5 @@
<chapter id="config">
-<title>Configuration Options</title>
+<title id="install-config">Configuration Options</title>
<sect1>
<title>Parameters for Configuration (<application>configure</application>)</title>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index f88a66ed803..cc90a0c1c34 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -386,8 +386,8 @@ should use the monetary conventions defined for
<Para>
<TABLE TOCENTRY="1">
-<TITLE><ProductName>Postgres</ProductName> Numeric Types</TITLE>
-<TITLEABBREV>Numerics</TITLEABBREV>
+<TITLE><ProductName>Postgres</ProductName> Monetary Types</TITLE>
+<TITLEABBREV>Money</TITLEABBREV>
<TGROUP COLS="4">
<THEAD>
<ROW>
@@ -1461,7 +1461,7 @@ The <Type>inet</Type> type stores hosts and networks in CIDR notation.
<Para>
<TABLE TOCENTRY="1">
-<TITLE><ProductName>Postgres</ProductName>IP Version 4 Type</TITLE>
+<TITLE><ProductName>Postgres</ProductName>IP Version 4 Types</TITLE>
<TITLEABBREV>IPV4</TITLEABBREV>
<TGROUP COLS="4">
<THEAD>
@@ -1500,51 +1500,48 @@ network and "/y" is the number of bits in the netmask.
If the "/y" part is left off, it is calculated using assumptions from
the old class system except that it is extended to include at least
all of the octets in the input.
-Here are some examples.
-
-<!-- There's a lot of examples here.
- -- Take some out if you think there are too many...
- -->
+Here are some examples:
<Para>
<TABLE TOCENTRY="1">
-<TGROUP COLS="4">
+<TITLE><ProductName>Postgres</ProductName>IP Types Examples</TITLE>
+<TGROUP COLS="2">
<THEAD>
<ROW>
- <ENTRY>Input</ENTRY>
- <ENTRY>Output</ENTRY>
+ <ENTRY>CIDR Input</ENTRY>
+ <ENTRY>CIDR Displayed</ENTRY>
</THEAD>
<TBODY>
<ROW>
- <ENTRY>select '192.168.1'::cidr</ENTRY>
+ <ENTRY>192.168.1</ENTRY>
<ENTRY>192.168.1/24</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '192.168'::cidr</ENTRY>
+ <ENTRY>192.168</ENTRY>
<ENTRY>192.168.0/24</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '128.1'::cidr</ENTRY>
+ <ENTRY>128.1</ENTRY>
<ENTRY>128.1/16</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '128':::cidr</ENTRY>
+ <ENTRY>128</ENTRY>
<ENTRY>128.0/16</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '128.1.2'::cidr</ENTRY>
+ <ENTRY>128.1.2</ENTRY>
<ENTRY>128.1.2/24</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '10.1.2'::cidr</ENTRY>
+ <ENTRY>10.1.2</ENTRY>
<ENTRY>10.1.2/24</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '10.1'::cidr</ENTRY>
+ <ENTRY>10.1</ENTRY>
<ENTRY>10.1/16</ENTRY>
</ROW>
<ROW>
- <ENTRY>select '10'::cidr</ENTRY>
+ <ENTRY>10</ENTRY>
<ENTRY>10/8</ENTRY>
</ROW>
</TBODY>
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 314b530ce16..04a5195eb8d 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,9 +1,14 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.10 1998/10/25 00:25:30 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.11 1998/10/30 19:36:57 thomas Exp $
Documentation Guide
Thomas Lockhart
$Log: docguide.sgml,v $
+Revision 1.11 1998/10/30 19:36:57 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
+
Revision 1.10 1998/10/25 00:25:30 thomas
Update info on source files for v6.4.
Should add/change ToDo list some more before release...
@@ -48,6 +53,9 @@ It should be able to answer
common questions and to allow a user to find those answers on his own
without resorting to mailing list support.
+<sect1>
+<title>Documentation Roadmap</title>
+
<para>
<productname>Postgres</productname> has four primary documentation
formats:
@@ -67,6 +75,48 @@ Hardcopy, for in-depth reading and reference.
</para></listitem>
</itemizedlist>
+<para>
+<table tocentry="1">
+<title><ProductName>Postgres</ProductName> Documentation Products</title>
+<tgroup cols="3">
+<thead>
+<row>
+<entry>
+File
+</entry>
+<entry>
+Description
+</entry>
+</row>
+</thead>
+
+<tbody>
+<row><entry> ./COPYRIGHT </entry><entry> Copyright notice </entry></row>
+<row><entry> ./INSTALL </entry><entry> Installation instructions (text from sgml->rtf->text) </entry></row>
+<row><entry> ./README </entry><entry> Introductory info </entry></row>
+<row><entry> ./register.txt </entry><entry> Registration message during make </entry></row>
+<row><entry> ./doc/bug.template </entry><entry> Bug report template </entry></row>
+<row><entry> ./doc/postgres.tar.gz </entry><entry> Integrated docs (<acronym>HTML</acronym>) </entry></row>
+<row><entry> ./doc/programmer.ps.gz </entry><entry> Programmer's Guide (Postscript) </entry></row>
+<row><entry> ./doc/programmer.tar.gz </entry><entry> Programmer's Guide (<acronym>HTML</acronym>) </entry></row>
+<row><entry> ./doc/reference.ps.gz </entry><entry> Reference Manual (Postscript) </entry></row>
+<row><entry> ./doc/reference.tar.gz </entry><entry> Reference Manual (<acronym>HTML</acronym>) </entry></row>
+<row><entry> ./doc/tutorial.ps.gz </entry><entry> Introduction (Postscript) </entry></row>
+<row><entry> ./doc/tutorial.tar.gz </entry><entry> Introduction (<acronym>HTML</acronym>) </entry></row>
+<row><entry> ./doc/user.ps.gz </entry><entry> User's Guide (Postscript) </entry></row>
+<row><entry> ./doc/user.tar.gz </entry><entry> User's Guide (<acronym>HTML</acronym>) </entry></row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+There are man pages available for installation, as well as a large number
+of plain-text README-type files throughout the <productname>Postgres</productname>
+source tree.
+
+<sect1>
+<title>Documentation Sources</title>
+
<para>
Documentation sources include plain text files, man pages, and html. However,
most new <productname>Postgres</productname> documentation will be written using the
@@ -75,10 +125,13 @@ most new <productname>Postgres</productname> documentation will be written using
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
-</para>
-<sect1>
-<title>Documentation Roadmap</title>
+<para>
+The purpose of <acronym>SGML</acronym> is to allow an author to
+specify the structure and content of a document (e.g. using the
+<productname>DocBook</productname> <acronym>DTD</acronym>), and to
+have the document style define how that content is rendered into a
+final form (e.g. using Norm Walsh's stylesheets).
<para>
Documentation has accumulated from several sources. As we integrate
@@ -89,80 +142,118 @@ happen to all documents at the same time. To ease the transition, and
to help guide developers and writers, we have defined a transition roadmap.
<para>
-Here is the documentation plan for v6.4:
+Here is the documentation plan for v6.5:
<itemizedlist>
<listitem>
<para>
-Convert <ulink url="sferac@bo.nettuno.it">Jose Soares Da Silva</ulink>'s
- text-based reference pages to <acronym>SGML</acronym>
-reference sections for the User's Guide.
-<ulink url="olly@lfix.co.uk">Oliver Elphick</ulink> is working on this
-and it is roughly half-way completed.
+Start compiling index information for the User's and Administrator's Guides.
<listitem>
<para>
Write more sections for the User's Guide covering areas outside the reference pages.
This would include introductory information and suggestions for approaches to typical
- design problems.
+design problems.
<listitem>
<para>
Merge information in the existing man pages into the reference pages and User's Guide.
+Condense the man pages down to reminder information, with references into the
+primary doc set.
<listitem>
<para>
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
-Brandon Ibach is working on the conversion filter.
<listitem>
<para>
-Rebuild the User's Guide, Reference Guide, and Administrator's Guide
-(the admin guide only if we get release notes and installation
-information updated in <acronym>SGML</acronym>).
-</itemizedlist>
+Convert all source graphics to CGM format files for portability. Currently we mostly have
+Applix Graphics sources from which we can generate .gif output. One graphic is only
+available in .gif and .ps, and should be redrawn or removed.
-<itemizedlist>
-<listitem><para>
-</para></listitem>
</itemizedlist>
+<sect2>
+<title>Document Structure</title>
+
<para>
-<table tocentry="1">
-<title><ProductName>Postgres</ProductName> Documentation Products</title>
-<tgroup cols="3">
-<thead>
-<row>
-<entry>
-File
-</entry>
-<entry>
-Description
-</entry>
-</row>
-</thead>
+There are currently five separate documents written in DocBook. Each document
+has a container source document which defines the DocBook environment and other
+document source files. These primary source files are located in
+<filename>doc/src/sgml/</filename>, along with many of the other source files
+used for the documentation. The primary source files are:
-<tbody>
-<row><entry> ./COPYRIGHT </entry><entry> Copyright notice </entry></row>
-<row><entry> ./INSTALL </entry><entry> Installation instructions (text from sgml->rtf->text) </entry></row>
-<row><entry> ./README </entry><entry> Introductory info </entry></row>
-<row><entry> ./register.txt </entry><entry> Registration message during make </entry></row>
-<row><entry> ./doc/bug.template </entry><entry> Bug report template </entry></row>
-<row><entry> ./doc/postgres.tar.gz </entry><entry> Integrated docs (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/programmer.ps.gz </entry><entry> Programmer's Guide (Postscript) </entry></row>
-<row><entry> ./doc/programmer.tar.gz </entry><entry> Programmer's Guide (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/reference.ps.gz </entry><entry> Reference Manual (Postscript) </entry></row>
-<row><entry> ./doc/reference.tar.gz </entry><entry> Reference Manual (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/tutorial.ps.gz </entry><entry> Introduction (Postscript) </entry></row>
-<row><entry> ./doc/tutorial.tar.gz </entry><entry> Introduction (<acronym>HTML</acronym>) </entry></row>
-<row><entry> ./doc/user.ps.gz </entry><entry> User's Guide (Postscript) </entry></row>
-<row><entry> ./doc/user.tar.gz </entry><entry> User's Guide (<acronym>HTML</acronym>) </entry></row>
-</tbody>
-</tgroup>
-</table>
+<variablelist>
+<varlistentry>
+<term>postgres.sgml</term>
+<listitem>
+<para>
+This is the integrated document, including all other documents as parts.
+Output is generated in <acronym>HTML</acronym> since the browser interface
+makes it easy to move around all of the documentation by just clicking.
+The other documents are available in both <acronym>HTML</acronym> and hardcopy.
+</para>
+</listitem>
+</varlistentry>
-<sect1>
-<title>Documentation Sources</title>
+<varlistentry>
+<term>tutorial.sgml</term>
+<listitem>
+<para>
+The introductory tutorial, with examples. Does not include programming topics,
+and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
+This is the "getting started" document.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>user.sgml</term>
+<listitem>
+<para>
+The User's Guide. Includes information on data types and user-level interfaces.
+This is the place to put information on "why".
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>reference.sgml</term>
+<listitem>
+<para>
+The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
+This is the place to put information on "how".
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>programming.sgml</term>
+<listitem>
+<para>
+The Programmer's Guide. Includes information on <productname>Postgres</productname>
+extensibility and on the programming interfaces.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>admin.sgml</term>
+<listitem>
+<para>
+The Administrator's Guide. Include installation and release notes.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+<!--
+Disable for the hardcopy production release.
+Too much tabular info and not very helpful in hardcopy.
+- thomas 1998-10-27
+
+<sect2>
+<title>Documentation Files</title>
<para>
<table tocentry="1">
@@ -333,8 +424,8 @@ Status
</tgroup>
</table>
-<sect1>
-<title>Document Conversion Status</title>
+<sect2>
+<title>Document Conversion</title>
<para>
<table tocentry="1">
@@ -579,82 +670,10 @@ Status
</tgroup>
</table>
-<sect2>
-<title>Document Structure</title>
-
-<para>
-There are currently five separate documents written in DocBook. Each document
-has a container source document which defines the DocBook environment and other
-document source files. These primary source files are located in
-<filename>doc/src/sgml/</filename>, along with many of the other source files
-used for the documentation. The primary source files are:
-
-<variablelist>
-<varlistentry>
-<term>postgres.sgml</term>
-<listitem>
-<para>
-This is the integrated document, including all other documents as parts.
-Output is generated in <acronym>HTML</acronym> since the browser interface
-makes it easy to move around all of the documentation by just clicking.
-The other documents are available in both <acronym>HTML</acronym> and hardcopy.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>tutorial.sgml</term>
-<listitem>
-<para>
-The introductory tutorial, with examples. Does not include programming topics,
-and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
-This is the "getting started" document.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>user.sgml</term>
-<listitem>
-<para>
-The User's Guide. Includes information on data types and user-level interfaces.
-This is the place to put information on "why".
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>reference.sgml</term>
-<listitem>
-<para>
-The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
-This is the place to put information on "how".
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>programming.sgml</term>
-<listitem>
-<para>
-The Programmer's Guide. Includes information on <productname>Postgres</productname>
-extensibility and on the programming interfaces.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>admin.sgml</term>
-<listitem>
-<para>
-The Administrator's Guide. Include installation and release notes.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
+-->
<sect1>
-<title>Introduction</title>
+<title>The Documentation Project</title>
<para>
Packaged documentation is available in both
@@ -708,9 +727,9 @@ exporting as a Postscript file.</para>
for several reasons, including the inability to make minor format
fixes before committing to hardcopy and generally inadequate table
support in the <productname>TeX</productname>
-stylesheets.</para></sect1>
+stylesheets.</para>
-<sect1>
+<sect2>
<title>Styles and Conventions</title>
<para>
@@ -756,80 +775,6 @@ be included below.
</para>
-->
-</sect1>
-
-<sect1>
-<title>Document Writing</title>
-
-<sect2>
-<title>Document Structure</title>
-
-<para>
-There are currently five separate documents written in DocBook. Each document
-has a container source document which defines the DocBook environment and other
-document source files. These primary source files are located in
-<filename>doc/src/sgml/</filename>, along with many of the other source files
-used for the documentation. The primary source files are:
-
-<variablelist>
-<varlistentry>
-<term>postgres.sgml</term>
-<listitem>
-<para>
-This is the integrated document, including all other documents.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>tutorial.sgml</term>
-<listitem>
-<para>
-The introductory tutorial, with examples. Does not include programming topics,
-and is intended to help get someone unfamiliar with <acronym>SQL</acronym> started.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>user.sgml</term>
-<listitem>
-<para>
-The User's Guide. Includes information on data types and user-level interfaces.
-This is the place to put information on "why".
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>reference.sgml</term>
-<listitem>
-<para>
-The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>programming.sgml</term>
-<listitem>
-<para>
-The Programmer's Guide. Includes information on <productname>Postgres</productname>
-extensibility and on the programming interfaces.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>admin.sgml</term>
-<listitem>
-<para>
-The Administrator's Guide. Include installation and release notes.
-</para>
-</listitem>
-</varlistentry>
-</variablelist>
-
<sect2>
<title>Authoring Tools</title>
@@ -925,13 +870,14 @@ by typing
</para></sect1>
<sect1>
-<title>Hardcopy Generation for v6.3</title>
+<title>Hardcopy Generation for v6.4</title>
<para>
The hardcopy Postscript documentation is generated by converting the
<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
-importing into Applixware. After a little cleanup (see the following
-section) the output is "printed" to a postscript file.</para>
+importing into <productname>ApplixWare-4.4.1</productname>.
+After a little cleanup (see the following
+section) the output is "printed" to a postscript file.
<para>
Some figures were redrawn to avoid having bitmap
@@ -941,9 +887,11 @@ was not time to redraw it. It was converted to fit using the
following commands:
<programlisting>
-% convert -v -geometry 400x400'>' figure03.gif con.gif
-% convert -v -crop 400x380 con.gif connections.gif
-</programlisting></para>
+% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
+% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
+</programlisting>
+
+</para>
<sect2>
<title><acronym>RTF</acronym> Cleanup Procedure</title>
@@ -1069,7 +1017,7 @@ described below.</para>
We understand that there are some other packaged distributions for
these tools. <productname>FreeBSD</productname> seems to have them
available. Please report package status to the docs mailing list and
-we will include that information here.</para>
+we will include that information here.
<sect2>
<title><acronym>RPM</acronym> installation on
@@ -1085,10 +1033,17 @@ and related packages.
<sect2>
<title>Manual installation of tools</title>
-<para>This is a brief run-through of the process of obtaining and
+<para>
+This is a brief run-through of the process of obtaining and
installing the software you'll need to edit DocBook source with Emacs
and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym>
-and <acronym>RTF</acronym>.</para>
+and <acronym>RTF</acronym>.
+
+<para>
+These instructions do not cover new <application>jade</application>/DocBook
+support in the <productname>sgml-tools</productname> package. The authors have
+not tried this package since it adopted DocBook, but it is almost certainly
+a good candidate for use.
<sect3><title>Prerequisites</title>
@@ -1114,9 +1069,9 @@ James Clark's <productname>Jade</productname> version 1.1</ulink>
<productname>DocBook</productname> version 3.0</ulink>
</para></listitem>
<listitem>
-<para><ulink url="http://nwalsh.com/docbook/dsssl/db107.zip">
+<para><ulink url="http://nwalsh.com/docbook/dsssl/db119.zip">
Norman Walsh's <productname>Modular Stylesheets</productname>
-version 1.07</ulink>
+version 1.19</ulink>
</para></listitem>
<listitem>
<para><ulink url="ftp://ftp.lysator.liu.se/pub/sgml/psgml-1.0.1.tar.gz">
@@ -1145,22 +1100,30 @@ Steve Pepper's Whirlwind Guide</ulink></para></listitem>
Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
</itemizedlist>
-</para>
-
</sect3>
-<sect3><title>Installing Jade</title>
+<sect3>
+<title>Installing Jade</title>
+<para>
-<para>First, read the installation instructions at the above listed
-URL.</para>
+<procedure>
+<title>Installing Jade</title>
+
+<step performance="required">
+<para>
+Read the installation instructions at the above listed
+URL.
-<para>Unzip the distribution kit in a suitable place. The command to do
+<step performance="required">
+<para>
+Unzip the distribution kit in a suitable place. The command to do
this will be something like
<programlisting>
unzip -aU jade1_1.zip
</programlisting>
</para>
+<step performance="required">
<para><productname>Jade</productname> is not built using
<productname>GNU Autoconf</productname>, so you'll need to edit a
<filename>Makefile</filename> yourself. Since James Clark has been
@@ -1202,17 +1165,24 @@ doesn't need the above settings for the math library and the
<filename>Makefile</filename>.
</para>
-<para>Now type <command>make</command> to build Jade and the various
+<step performance="required">
+<para>Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para>
+<step performance="required">
<para>Once the software is built, <command>make install</command> will
do the obvious.</para>
-</sect3>
+</procedure>
+
+<sect3>
+<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
-<sect3><title>Installing the <productname>DocBook</productname>
-<acronym>DTD</acronym> kit</title>
+<para>
+<procedure>
+<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
+<step performance="required">
<para>You'll want to place the files that make up the
<productname>DocBook</productname> <acronym>DTD</acronym> kit in the
directory you built <productname>Jade</productname> to expect them in,
@@ -1234,6 +1204,9 @@ the former, by giving it the single line of content:
<programlisting>
CATALOG /usr/local/share/sgml/CATALOG
</programlisting>
+
+<step performance="required">
+<para>
The <filename>CATALOG</filename> file should then contain three types
of lines. The first is the (optional) <acronym>SGML</acronym>
declaration, thus:
@@ -1250,6 +1223,9 @@ PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
</programlisting>
+
+<step performance="required">
+<para>
Of course, a file containing these comes with the
<productname>DocBook</productname> kit. Note that the last item on
each of these lines is a file name, given here without a path. You
@@ -1270,14 +1246,20 @@ named <filename>ISO</filename>. Again, proper catalog entries should
accompany the entity kit you fetch.
</para>
-</sect3>
+</procedure>
-<sect3><title>Installing Norman Walsh's <acronym>DSSSL</acronym>
-style sheets</title>
+<sect3>
+<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
+<para>
+
+<procedure>
+<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
-<para>First, read the installation instructions at the above listed
+<step performance="required">
+<para>Read the installation instructions at the above listed
URL.</para>
+<step performance="required">
<para>To install Norman's style sheets, simply unzip the distribution
kit in a suitable place. A good place to dot this would be
<filename>/usr/local/share</filename>, which places the kit in a
@@ -1288,29 +1270,54 @@ unzip -aU db107.zip
</programlisting>
</para>
+<step performance="required">
<para>One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
-<productname>PostgreSQL</productname> manual. Go to the <acronym>SGML</acronym> source
+<productname>PostgreSQL</productname> manual.
+
+<substeps>
+
+<step performance="required">
+<para>
+To build the <acronym>HTML</acronym> files,
+ go to the <acronym>SGML</acronym> source
directory, <filename>doc/src/sgml</filename>, and say
<programlisting>
jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
-to build the <acronym>HTML</acronym> files ("book1.htm" is the top level node), and
+
+<para>
+<filename>book1.htm</filename> is the top level node of the output..
+
+<step performance="required">
+<para>
+To generate the <acronym>RTF</acronym> output, ready for importing
+into your favorite word processing system and printing, type:
<programlisting>
jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
-to generate the <acronym>RTF</acronym> output, ready for importing
-into your favorite word processing system and printing.</para>
-</sect3>
+</substeps>
+
+</procedure>
-<sect3><title>Installing <productname>PSGML</productname></title>
+<sect3>
+<title>Installing <productname>PSGML</productname></title>
+<para>
+
+<procedure>
+<title>Installing <productname>PSGML</productname></title>
-<para>First, read the installation instructions at the above listed
+<step performance="required">
+<para>Read the installation instructions at the above listed
URL.</para>
+<step performance="required">
<para>Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place.
+
+<step performance="required">
+<para>
Then add the following lines to your
<filename>/usr/local/share/emacs/site-lisp/site-start.el</filename>
file to make <productname>Emacs</productname> properly load
@@ -1320,6 +1327,9 @@ file to make <productname>Emacs</productname> properly load
(cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
</programlisting>
+
+<step performance="optional">
+<para>
If you want to use <productname>PSGML</productname> when editing
<acronym>HTML</acronym> too, also add this:
<programlisting>
@@ -1328,22 +1338,39 @@ If you want to use <productname>PSGML</productname> when editing
</programlisting>
</para>
+
+<step performance="optional">
<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. You can set the
-<filename>SGML_CATALOG_FILES</filename> environment variable, you can
+have to compensate for this.
+
+<substeps>
+<step performance="optional">
+<para>
+You can set the
+<filename>SGML_CATALOG_FILES</filename> environment variable.
+
+<step performance="optional">
+<para>
+You can
customize your <productname>PSGML</productname> installation (its
-manual tells you how), or you can even edit the source file
+manual tells you how).
+
+<step performance="optional">
+<para>
+You can even edit the source file
<filename>psgml.el</filename> before compiling and installing
<productname>PSGML</productname>, changing the hard-coded paths to
match your own default.</para>
-</sect3>
+</substeps>
+
+</procedure>
-<sect3><title>Optional: installing <productname>JadeTeX</productname></title>
+<sect3><title>Installing <productname>JadeTeX</productname></title>
<para>If you want to, you can also install
<productname>JadeTeX</productname> to use
@@ -1419,6 +1446,15 @@ vary according to your installation.
<sect1>
<title>Alternate Toolsets</title>
+<para>
+<productname>sgml-tools</productname> v2.x
+now supports <application>jade</application>
+and <productname>DocBook</productname>. It may be the preferred toolset
+for working with <acronym>SGML</acronym> but we have not had a chance to
+evaluate the new package.
+
+<!--
+
<para>
The current stable release of <productname>sgml-tools</productname> is
version 1.0.4. The v1.0 release includes some restructuring of the
@@ -1433,12 +1469,9 @@ version of <productname>sgml-tools</productname> evaluated for
<para>
Install
-<productname>sgml-tools-0.99.0</productname>
+<productname>sgml-tools-0.99.0</productname>.
</para>
-<sect2>
-<title><productname>sgml-tools</productname></title>
-
<para>
Apply <ulink
url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">
@@ -1485,5 +1518,7 @@ null.sty to texmf/tex/latex/tools/ or the appropriate area.
Run <productname>texhash</productname> to update the tex database.
</para></sect2></sect1>
+-->
+
</appendix>
diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml
index 444ed9d35b0..0adb2db0ec0 100644
--- a/doc/src/sgml/info.sgml
+++ b/doc/src/sgml/info.sgml
@@ -48,7 +48,9 @@ Installation and management information. List of supported machines.
<Para>
Information for <ProductName>Postgres</ProductName> developers. This is intended
for those who are contributing to the <ProductName>Postgres</ProductName>
-project; application development information should appear in the Programmer's Guide.
+project; application development information should appear in the
+<citetitle>Programmer's Guide</citetitle>.
+Currently included in the <citetitle>Programmer's Guide</citetitle>.
</Para>
</ListItem>
</VarListEntry>
@@ -58,8 +60,7 @@ project; application development information should appear in the Programmer's G
<ListItem>
<Para>
Detailed reference information on command syntax.
-At the moment, this manual is very sparse, but eventually should contain
-information similar to that in the man pages.
+Currently included in the <citetitle>User's Guide</citetitle>.
</Para>
</ListItem>
</VarListEntry>
diff --git a/doc/src/sgml/install.sgml b/doc/src/sgml/install.sgml
index e3d9d593e4c..0553c53b8ef 100644
--- a/doc/src/sgml/install.sgml
+++ b/doc/src/sgml/install.sgml
@@ -414,16 +414,20 @@ $ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
the build process (see the --prefix option below). Type
<ProgramListing>
$ cd /usr/src/pgsql/src
-$ ./configure [ <replaceable>options as described below</replaceable> ]
+$ ./configure [ <replaceable>options</replaceable> ]
</ProgramListing>
</Para>
+<substeps>
+
+<Step Performance="optional">
<Para>
Among other chores, the configure script selects a system-specific
"template" file from the files provided in the template subdirectory.
If it cannot guess which one to use for your system, it will say so and
exit. In that case you'll need to figure out which one to use and run
- configure again, this time giving the <option>--with-template=TEMPLATE</option> option to
+ configure again, this time giving the
+<option>--with-template=TEMPLATE</option> option to
make the right file be chosen.
<note>
@@ -438,7 +442,14 @@ If your system is not automatically recognized by configure and you have to do t
</Para>
+<Step Performance="optional">
<Para>
+Choose configuration options. Check <xref linkend="config" endterm="install-config">
+for details. However, for a plain-vanilla first installation with no extra
+options like multi-byte character support or locale collation support it may
+be adequate to have chosen the installation areas and to run configure without
+extra options specified.
+
The configure script accepts many additional options that you can use
if you don't like the default configuration. To see them all, type
<ProgramListing>
@@ -449,35 +460,21 @@ If your system is not automatically recognized by configure and you have to do t
--prefix=BASEDIR Selects a different base directory for the
installation of the <ProductName>Postgres</ProductName> configuration.
The default is /usr/local/pgsql.
-
--with-template=TEMPLATE
Use template file TEMPLATE - the template
files are assumed to be in the directory
src/template, so look there for proper values.
-
- --with-pgport=PORT Sets the port that the postmaster process
- listens for incoming connections on. The
- default is port 5432.
-
--with-tcl Build interface libraries and programs requiring
Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
-
--with-perl Build the Perl interface library.
-
--with-odbc Build the ODBC driver package.
-
--enable-hba Enables Host Based Authentication (DEFAULT)
-
--disable-hba Disables Host Based Authentication
-
--enable-locale Enables USE_LOCALE
-
--enable-cassert Enables ASSERT_CHECKING
-
--with-CC=compiler
Use a specific C compiler that the configure
script cannot find.
-
--with-CXX=compiler
--without-CXX
Use a specific C++ compiler that the configure
@@ -487,9 +484,11 @@ If your system is not automatically recognized by configure and you have to do t
</ProgramListing>
</Para>
+<Step Performance="required">
<Para>
-As an example, here is the configure script used on a Sparc Solaris 2.5 system
- with <filename>/opt/postgres</filename> being the installation base directory:
+Here is the configure script used on a Sparc Solaris 2.5 system
+ with <filename>/opt/postgres</filename> specified as
+ the installation base directory:
<ProgramListing>
$ ./configure --prefix=/opt/postgres \
@@ -497,11 +496,17 @@ $ ./configure --prefix=/opt/postgres \
--enable-hba --disable-locale
</ProgramListing>
+<tip>
+<para>
Of course, you may type these three lines all
on the same line.
+</tip>
+
</Para>
</Step>
+</substeps>
+
<Step Performance="required">
<Para>
Install the <acronym>HTML</acronym> documentation. Type
@@ -653,10 +658,13 @@ pg_id: can't load library 'libpq.so'
Any account that will use <ProductName>Postgres</ProductName> must
be similarly prepared.
-<note>
<para>
-There are several ways to influence the runtime environment of the <ProductName>Postgres</ProductName>
-server. Refer to the chapter on <citetitle>Administrator's Guide</citetitle> for more information.
+There are several ways to influence the runtime environment of the
+ <ProductName>Postgres</ProductName>
+server. Refer to the <citetitle>Administrator's Guide</citetitle>
+ for more information.
+
+<note>
<para>
The following instructions are for a
bash/sh shell. Adapt accordingly for other shells.
@@ -664,8 +672,13 @@ The following instructions are for a
</Para>
+<substeps>
+
+<Step Performance="required">
<Para>
- Add the following lines to your login shell, <filename>~/.bash_profile</filename>:
+ Add the following lines to your login environment:
+
+ shell, <filename>~/.bash_profile</filename>:
<ProgramListing>
PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
@@ -675,6 +688,30 @@ export PATH MANPATH PGLIB PGDATA
</ProgramListing>
</Para>
+<Step Performance="required">
+<para>
+Several regression tests could failed if the user's locale collation
+scheme is different from that of standard C locale.
+
+<para>
+If you configure and compile <ProductName>Postgres</ProductName>
+ with the <option>--enable-locale</option> option then
+ set locale environment to C (or unset all LC_* variables)
+by putting these additional lines to your login environment
+ before starting postmaster:
+<ProgramListing>
+LC_COLLATE=C
+LC_CTYPE=C
+LC_COLLATE=C
+export LC_COLLATE LC_CTYPE LC_COLLATE
+</ProgramListing>
+
+<ProgramListing>
+
+</ProgramListing>
+
+
+<Step Performance="required">
<Para>
Make sure that you have defined these variables before continuing
with the remaining steps. The easiest way to do this is to type:
@@ -684,10 +721,15 @@ $ source ~/.bash_profile
</Para>
</Step>
+</substeps>
+
<Step Performance="required">
<Para>
- Create the database. <Emphasis>Do not do the following as root!</Emphasis>
- This would be a major security hole. Type
+ Create the database installation from your <ProductName>Postgres</ProductName>
+superuser account (typically account <literal>postgres</literal>).
+
+<Emphasis>Do not do the following as root!</Emphasis>
+This would be a major security hole. Type
<ProgramListing>
$ initdb
</ProgramListing>
@@ -710,15 +752,151 @@ $ initdb
</Step>
<Step Performance="required">
-<Para>
- Run postmaster from your <ProductName>Postgres</ProductName> superuser account (typically
- account postgres).
-<emphasis>Do not run <application>postmaster</application> from the root account!</emphasis>
+<para>
+Briefly test that the backend will start and run by running it from
+the command line.
+
+<substeps>
+
+<Step Performance="required">
+<para>
Start the postmaster daemon running in the background by typing
+<ProgramListing>
+$ cd
+$ postmaster -i
+</ProgramListing>
+</Para>
+</Step>
+
+<Step Performance="required">
+<para>
+Create a database by typing
+<ProgramListing>
+$ createdb
+</ProgramListing>
+
+<Step Performance="required">
+<para>
+Connect to the new database:
+<ProgramListing>
+$ psql
+</ProgramListing>
+
+<Step Performance="required">
+<para>
+And run a sample query:
+<ProgramListing>
+postgres=> SELECT datetime 'now';
+</ProgramListing>
+
+<Step Performance="required">
+<para>
+Exit <application>psql</application>:
+<ProgramListing>
+postgres=> \q
+</ProgramListing>
+
+<Step Performance="required">
+<para>
+Remove the test database (unless you will want to use it later for other tests):
+<ProgramListing>
+$ destroydb
+</ProgramListing>
+
+</substeps>
+
+<Step Performance="required">
+<Para>
+ Run postmaster in the background from your <ProductName>Postgres</ProductName>
+superuser account (typically account <literal>postgres</literal>).
+<emphasis>Do not run <application>postmaster</application>
+from the root account!</emphasis>
+
+<Para>
+Usually, you will want to modify
+ your computer so that it will automatically start postmaster whenever
+ it boots. It is not required; the <ProductName>Postgres</ProductName>
+server can
+be run successfully from non-privileged accounts without root intervention.
+
+<para>
+ Here are some suggestions on how to do this, contributed by various
+ users.
+
+<para>
+ Whatever you do, postmaster must be run by
+the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
+<emphasis>and not by root</emphasis>.
+This is why all of the examples below start by switching user
+ (su) to postgres. These commands also take into account the fact
+ that environment variables like PATH and PGDATA may not be set properly.
+
+ The examples are as follows. Use them with extreme caution.
+
+<itemizedlist mark="bullet">
+<listitem>
+<para>
+If you are installing from a non-privileged account and have no root access, then
+start the <application>postmaster</application> and send it to the background:
+
<ProgramListing>
$ cd
$ nohup postmaster > regress.log 2>&1 &
</ProgramListing>
+
+<listitem>
+<para>
+Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
+ 2.5.1 to contain the following single line:
+<programlisting>
+su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
+</programlisting>
+
+<listitem>
+<para>
+In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
+ contain the following lines and make it chmod 755 and chown
+ root:bin.
+
+<programlisting>
+#!/bin/sh
+[ -x /usr/local/pgsql/bin/postmaster ] && {
+ su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
+ -D/usr/local/pgsql/data
+ -S -o -F > /usr/local/pgsql/errlog' &
+ echo -n ' pgsql'
+}
+</programlisting>
+
+ You may put the line breaks as shown above. The shell is smart
+ enough to keep parsing beyond end-of-line if there is an
+ expression unfinished. The exec saves one layer of shell under
+ the postmaster process so the parent is init.
+
+<listitem>
+<para>
+In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
+which is based on the example in <filename>contrib/linux/</filename>.
+Then make a softlink to this file from
+ <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
+
+<listitem>
+<para>
+In RedHat Linux edit file /etc/inittab to add the
+ following as a single line:
+
+<programlisting>
+pg:2345:respawn:/bin/su - postgres -c
+ "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
+ >> /usr/local/pgsql/server.log 2>&1 </dev/null"
+</programlisting>
+
+ (The author of this example says this example will revive the
+ postmaster if it dies, but he doesn't know if there are other side
+ effects.)
+
+</itemizedlist>
+
</Para>
</Step>
@@ -819,82 +997,6 @@ $ gmake clean
</substeps>
-<Step Performance="required">
-<Para>
- If you haven't already done so, this would be a good time to modify
- your computer so that it will automatically start postmaster whenever
- you boot your computer.
-
- Here are some suggestions on how to do this, contributed by various
- users.
-
-<para>
- Whatever you do, postmaster must be run by
-the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
-<emphasis>and not by root</emphasis>.
-This is why all of the examples below start by switching user
- (su) to postgres. These commands also take into account the fact
- that environment variables like PATH and PGDATA may not be set properly.
-
- The examples are as follows. Use them with extreme caution.
-
-<itemizedlist>
-<listitem>
-<para>
-Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
- 2.5.1 to contain the following single line:
-<programlisting>
-su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
-</programlisting>
-
-<listitem>
-<para>
-In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
- contain the following lines and make it chmod 755 and chown
- root:bin.
-
-<programlisting>
-#!/bin/sh
-[ -x /usr/local/pgsql/bin/postmaster ] && {
- su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
- -D/usr/local/pgsql/data
- -S -o -F > /usr/local/pgsql/errlog' &
- echo -n ' pgsql'
-}
-</programlisting>
-
- You may put the line breaks as shown above. The shell is smart
- enough to keep parsing beyond end-of-line if there is an
- expression unfinished. The exec saves one layer of shell under
- the postmaster process so the parent is init.
-
-<listitem>
-<para>
-In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
-which is based on the example in <filename>contrib/linux/</filename>.
-Then make a softlink to this file from
- <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
-
-<listitem>
-<para>
-In RedHat Linux edit file /etc/inittab to add the
- following as a single line:
-
-<programlisting>
-pg:2345:respawn:/bin/su - postgres -c
- "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
- >> /usr/local/pgsql/server.log 2>&1 </dev/null"
-</programlisting>
-
- (The author of this example says this example will revive the
- postmaster if it dies, but he doesn't know if there are other side
- effects.)
-
-</itemizedlist>
-
-</Para>
-</Step>
-
<Step Performance="required">
<Para>
If you haven't already done so, this would be a good time to modify
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 73c5d025470..278a34ab048 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -1,10 +1,15 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.1 1998/10/27 06:11:08 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.2 1998/10/30 19:37:00 thomas Exp $
Postgres quick Installation Guide.
thomas 1998-10-26
$Log: installation.sgml,v $
+Revision 1.2 1998/10/30 19:37:00 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
+
Revision 1.1 1998/10/27 06:11:08 thomas
First cut at standalone installation guide to replace INSTALL text source.
@@ -20,6 +25,7 @@ First cut at standalone installation guide to replace INSTALL text source.
<!entity notation SYSTEM "notation.sgml">
<!entity y2k SYSTEM "y2k.sgml">
+<!entity config SYSTEM "config.sgml">
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity install SYSTEM "install.sgml">
<!entity options SYSTEM "pg_options.sgml">
@@ -37,9 +43,9 @@ First cut at standalone installation guide to replace INSTALL text source.
<!-- Title information -->
-<Title>PostgreSQL Administrator's Guide</Title>
+<Title>PostgreSQL Installation Guide</Title>
<BookInfo>
- <ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
+ <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@@ -115,6 +121,7 @@ and installing documentation, and then print or browse the
</chapter>
&ports;
+&config;
&install;
&release;
diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml
index 71758ddcfa2..4a3485e01ba 100644
--- a/doc/src/sgml/jdbc.sgml
+++ b/doc/src/sgml/jdbc.sgml
@@ -50,7 +50,7 @@ as the driver uses some dynamic
loading techniques for performance reasons,
and <application>javac</application> cannot cope.
The <filename>Makefile</filename> will generate the jar archive.
-<para>
+</note>
<sect2>
<title>Installing the Driver</title>
@@ -76,7 +76,7 @@ Loading the driver is covered later on in this chapter.
<para>
<sect1>
-<title>Preparing the database for <acronym>JDBC</acronym></title>
+<title>Preparing the Database for <acronym>JDBC</acronym></title>
<para>
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
@@ -89,10 +89,12 @@ to add something like:
<para>
host all 127.0.0.1 255.255.255.255 password
<para>
-Here access to all databases are possible from the local machine with <acronym>JDBC</acronym>.
+Here access to all databases are possible from the local machine
+with <acronym>JDBC</acronym>.
<para>
-The <acronym>JDBC</acronym> Driver supports trust, ident, password and crypt authentication methods.
+The <acronym>JDBC</acronym> Driver supports trust, ident,
+password and crypt authentication methods.
<para>
@@ -193,15 +195,15 @@ forms:
<itemizedlist>
<listitem>
<para>
-jdbc:postgresql:<replaceable class="parameter>database</replaceable>
+jdbc:postgresql:<replaceable class="parameter">database</replaceable>
<listitem>
<para>
-jdbc:postgresql://<replaceable class="parameter>host</replaceable>/<replaceable class="parameter>database</replaceable>
+jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
<listitem>
<para>
-jdbc:postgresql://<replaceable class="parameter>host</replaceable>:<replaceable class="parameter>port</replaceable>/<replaceable class="parameter>database</replaceable>
+jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
</itemizedlist>
where:
@@ -209,7 +211,7 @@ where:
<variablelist>
<varlistentry>
<term>
-<replaceable class="parameter>host</replaceable>
+<replaceable class="parameter">host</replaceable>
<listitem>
<para>
@@ -217,7 +219,7 @@ The hostname of the server. Defaults to "localhost".
<varlistentry>
<term>
-<replaceable class="parameter>port</replaceable>
+<replaceable class="parameter">port</replaceable>
<listitem>
<para>
@@ -226,7 +228,7 @@ standard port number (5432).
<varlistentry>
<term>
-<replaceable class="parameter>database</replaceable>
+<replaceable class="parameter">database</replaceable>
<listitem>
<para>
@@ -243,7 +245,7 @@ Connection db = DriverManager.getConnection(url,user,pwd);
<para>
<sect1>
-<title>Issuing a query and processing the result</title>
+<title>Issuing a Query and Processing the Result</title>
<para>
Any time you want to issue SQL statements to the database, you require a
@@ -252,11 +254,13 @@ method to issue a query. This will return a ResultSet instance, which contains
the entire result.
<para>
-<sect1>
-<title>Some notes about using the Statement interface:</title>
+<sect2>
+<title>Using the Statement Interface</title>
-<itemizedlist>
<para>
+The following must be considered when using the Statement interface:
+
+<itemizedlist>
<listitem>
<para>
You can use a Statement instance as many times as you want. You could
@@ -276,14 +280,16 @@ as it covers some important points.
</itemizedlist>
-<sect1>
-<title>Some notes about using the ResultSet interface:</title>
+<sect2>
+<title>Using the ResultSet Interface</title>
-<itemizedlist>
<para>
+The following must be considered when using the ResultSet interface:
+
+<itemizedlist>
<listitem>
<para>
-Before reading any values, you must call next(). This returns true if
+Before reading any values, you must call <function>next()</function>. This returns true if
there is a result, but more importantly, it prepares the row for processing.
<listitem>
@@ -291,58 +297,60 @@ there is a result, but more importantly, it prepares the row for processing.
Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest
to stick to this rule, although at the current time, the <application>Postgres</application> driver
will allow you to access a field as many times as you want.
+
<listitem>
<para>
-You must close() a ResultSet once you have finished with it.
+You must close a ResultSet by calling <function>close()</function> once you have finished with it.
+
<listitem>
<para>
Once you request another query with the Statement used to create a
-ResultSet, the currently open instance is closed().
+ResultSet, the currently open instance is closed.
</itemizedlist>
+<para>
+An example is as follows:
+
+<programlisting>
Statement st = db.createStatement();
ResultSet rs = st.executeQuery(<literal>select * from mytable</literal>);
while(rs.next()) {
-<itemizedlist>
-<para>
-<listitem>
-<para>
-System.out.print(<literal>Column 1 returned </literal>);
-<listitem>
-<para>
-System.out.println(rs.getString(1));
+ System.out.print(<literal>Column 1 returned </literal>);
+ System.out.println(rs.getString(1));
}
rs.close();
st.close();
-</itemizedlist>
+</programlisting>
<sect1>
-<title>Performing updates</title>
+<title>Performing Updates</title>
<para>
To perform an update (or any other SQL statement that does not return a
result), you simply use the executeUpdate() method:
-<para>
- st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
-<para>
+<programlisting>
+st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
+</programlisting>
+
<sect1>
-<title>Closing the connection</title>
+<title>Closing the Connection</title>
<para>
To close the database connection, simply call the close() method to the Connection:
-<para>
+<programlisting>
db.close();
-<para>
+</programlisting>
<sect1>
<title>Using Large Objects</title>
<para>
-In <application>Postgres</application>, large objects (also known as BLOBS) are used to hold data in
+In <application>Postgres</application>,
+large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
the database that cannot be stored in a normal SQL table. They are stored as a
Table/Index pair, and are refered to from your own tables, by an OID value.
@@ -357,118 +365,83 @@ In <acronym>JDBC</acronym>, the standard way to access them is using the getBina
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
methods make the large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the object.
+
<para>
-Example:
-<para>
-You have a table containing the file name of an image, and a large object
+For example, suppose
+you have a table containing the file name of an image, and a large object
containing that image:
-<para>
- create table images (imgname name,imgoid oid);
+
+<programlisting>
+create table images (imgname name,imgoid oid);
+</programlisting>
+
<para>
To insert an image, you would use:
-<para>
-<itemizedlist>
-<para>
-<listitem>
-<para>
+
+<programlisting>
File file = new File(<literal>myimage.gif</literal>);
-<listitem>
-<para>
FileInputStream fis = new FileInputStream(file);
-<listitem>
-<para>
-PreparedStatement ps = conn.prepareStatement(<literal>insert into images
-values (?,?)<literal>);
-<listitem>
-<para>
+PreparedStatement ps = conn.prepareStatement(<literal>insert into images values (?,?)</literal>);
ps.setString(1,file.getName());
-<listitem>
-<para>
ps.setBinaryStream(2,fis,file.length());
-<listitem>
-<para>
ps.executeUpdate();
-<listitem>
-<para>
ps.close();
-<listitem>
-<para>
fis.close();
-</itemizedlist>
+</programlisting>
+<para>
Now in this example, setBinaryStream transfers a set number of bytes from a
stream into a large object, and stores the OID into the field holding a
reference to it.
+
<para>
Retrieving an image is even easier (I'm using PreparedStatement here, but
Statement can equally be used):
-<para>
-<itemizedlist>
-<para>
-<listitem>
-<para>
-PreparedStatement ps = con.prepareStatement(<literal>select oid from
-images where name=?<literal>);
-<listitem>
-<para>
+
+<programlisting>
+PreparedStatement ps = con.prepareStatement(<literal>select oid from images where name=?</literal>);
ps.setString(1,<literal>myimage.gif</literal>);
-<listitem>
-<para>
ResultSet rs = ps.executeQuery();
-<listitem>
-<para>
if(rs!=null) {
-<listitem>
-<para>
while(rs.next()) {
-<listitem>
-<para>
-	InputStream is = rs.getBinaryInputStream(1);
-<listitem>
-<para>
-	// use the stream in some way here
-<listitem>
-<para>
-	is.close();
-<listitem>
-<para>
+ InputStream is = rs.getBinaryInputStream(1);
+ // use the stream in some way here
+ is.close();
}
-<listitem>
-<para>
rs.close();
-<listitem>
-<para>
}
-<listitem>
-<para>
ps.close();
-</itemizedlist>
+</programlisting>
+<para>
Now here you can see where the Large Object is retrieved as an InputStream.
You'll also notice that we close the stream before processing the next row in
the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any
InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
-<para>
<sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>
<para>
-<application>Postgres</application> is an extensible database system. You can add your own functions
+<application>Postgres</application> is an extensible database system.
+You can add your own functions
to the backend, which can then be called from queries, or even add your own
data types.
<para>
Now, as these are facilities unique to us, we support them from Java, with
-a set of extension <acronym>API</acronym>'s. Some features within the core of the standard driver
+a set of extension <acronym>API</acronym>'s. Some features within
+the core of the standard driver
actually use these extensions to implement Large Objects, etc.
-<para>
<!--
- -- Nothing marked up from here on. It looks like it will be tricky:
- -- what do we want to do with the class inheritance diagrams?
- -- - thomas 1998-10-23
- -->
+************************************************************
+Nothing marked up from here on. It looks like it will be tricky:
+what do we want to do with the class inheritance diagrams?
+- thomas 1998-10-23
+************************************************************
+-->
+
<programlisting>
Accessing the extensions
@@ -2548,10 +2521,10 @@ If you have not yet read it, I'd advise you read the <acronym>JDBC</acronym>
Documentation (supplied with Sun's <acronym>JDK</acronym>),
and the <acronym>JDBC</acronym> Specification.
Both are available on
-<ulink url="http://www.javasoft.com>JavaSoft's web site</ulink>.
+<ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>.
<para>
-<ulink url="http://www.retep.org.uk>My own web site</ulink>
+<ulink url="http://www.retep.org.uk">My own web site</ulink>
contains updated information not included in this
document, and also includes precompiled drivers for v6.4, and earlier.
diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml
index f917fb5b646..798dcebccdd 100644
--- a/doc/src/sgml/libpgtcl.sgml
+++ b/doc/src/sgml/libpgtcl.sgml
@@ -2,8 +2,9 @@
<Title>pgtcl</Title>
<Para>
-pgtcl is a tcl package for front-end programs to interface with <ProductName>Postgres</ProductName>
-backends. It makes most of the functionality of libpq available to
+<literal>pgtcl</literal> is a tcl package for front-end programs
+to interface with <ProductName>Postgres</ProductName>
+backends. It makes most of the functionality of <literal>libpq</literal> available to
tcl scripts.
</Para>
@@ -16,7 +17,7 @@ This package was originally written by Jolly Chen.
<Para>
<TABLE TOCENTRY="1">
-<TITLE>PGTCL Commands</TITLE>
+<TITLE><literal>pgtcl</literal> Commands</TITLE>
<TGROUP COLS="2">
<THEAD>
<ROW>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 57097a1c5ad..7657ac23192 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
<Chapter Id="libpq-chapter">
-<Title id="libpq"><FileName>libpq</FileName></Title>
+<Title id="libpq">libpq</Title>
<Para>
diff --git a/doc/src/sgml/odbc.sgml b/doc/src/sgml/odbc.sgml
index 069b9ab41ad..46033e9210d 100644
--- a/doc/src/sgml/odbc.sgml
+++ b/doc/src/sgml/odbc.sgml
@@ -577,8 +577,7 @@ be able to access the <productname>Postgres</productname>
<title>Enabling ApplixWare Database Access</title>
<para>
-Note that
-these instructions are for the 4.4.1 release of
+These instructions are for the 4.4.1 release of
<productname>ApplixWare</productname> on <productname>Linux</productname>.
Refer to the <citetitle>Linux Sys Admin</citetitle> on-line book
for more detailed information.
diff --git a/doc/src/sgml/page.sgml b/doc/src/sgml/page.sgml
index 024554b6f89..8c468ca3b1d 100644
--- a/doc/src/sgml/page.sgml
+++ b/doc/src/sgml/page.sgml
@@ -34,8 +34,10 @@ classes (e.g., a B-tree index) are structured.
<thead>
<row>
<entry>
+Item
</entry>
<entry>
+Description
</entry>
</row>
</thead>
diff --git a/doc/src/sgml/ports.sgml b/doc/src/sgml/ports.sgml
index 4cd3afaf5ea..ca8218e3b11 100644
--- a/doc/src/sgml/ports.sgml
+++ b/doc/src/sgml/ports.sgml
@@ -1,14 +1,19 @@
<Chapter Id="ports">
<Title>Ports</Title>
-<Sect1>
-<Title>Currently Supported Platforms</Title>
-
<Para>
This manual describes version 6.4 of <ProductName>Postgres</ProductName>.
The <ProductName>Postgres</ProductName> developer community has
-compiled and tested <ProductName>Postgres</ProductName> on the following
-platforms:
+compiled and tested <ProductName>Postgres</ProductName> on a
+number of platforms. Check
+<ulink url="http://www.postgresql.org/docs/admin/ports.htm">the web site</ulink>
+for the latest information.
+
+<Sect1>
+<Title>Currently Supported Platforms</Title>
+
+<para>
+At the time of publication, the following platforms have been tested:
<TABLE TOCENTRY="1">
<TITLE>Supported Platforms</TITLE>
@@ -24,13 +29,11 @@ platforms:
</THEAD>
<TBODY>
<ROW>
- <ENTRY>AIX 4.1.x-4.2</ENTRY>
+ <ENTRY>AIX 4.2.1</ENTRY>
<ENTRY>RS6000</ENTRY>
- <ENTRY>v6.3</ENTRY>
- <ENTRY>1998-03-01</ENTRY>
- <ENTRY>4.1.4.0,4.2 (<ULink url="mailto:darrenk@insightdist.com">Darren King</ULink>),
- 4.1.5 (<ULink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ULink>);
- 3.2.5 confirmed on v6.2.1 (<ULink url="mailto:danaf@ans.net">Frank Dana</ULink>)</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-27</ENTRY>
+ <ENTRY>(<ULink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>BSDI</ENTRY>
@@ -42,45 +45,25 @@ platforms:
<ROW>
<ENTRY>FreeBSD 2.2.x-3.x</ENTRY>
<ENTRY>x86</ENTRY>
- <ENTRY>v6.3</ENTRY>
- <ENTRY>1998-03-01</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-26</ENTRY>
<ENTRY>(<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>,
<ULink url="mailto:scrappy@hub.org">Marc Fournier</ULink>)</ENTRY>
</ROW>
- <ROW>
- <ENTRY>NetBSD 1.3.2</ENTRY>
- <ENTRY>x86</ENTRY>
- <ENTRY>v6.4</ENTRY>
- <ENTRY>1998-10-25</ENTRY>
- <ENTRY>(<ULink url="mailto:brook@trillium.NMSU.Edu">Brook Milligan</ULink>)</ENTRY>
- </ROW>
- <ROW>
- <ENTRY>NetBSD 1.3</ENTRY>
- <ENTRY>NS32532</ENTRY>
- <ENTRY>v6.3</ENTRY>
- <ENTRY>1998-07-20</ENTRY>
- <ENTRY>(<ULink url="mailto:phil@steelhead.cs.wwu.edu">Phil Nelson</ULink>)</ENTRY>
- </ROW>
- <ROW>
- <ENTRY>NetBSD 1.3</ENTRY>
- <ENTRY>Sparc</ENTRY>
- <ENTRY>v6.3</ENTRY>
- <ENTRY>1998-03-01</ENTRY>
- <ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
- </ROW>
- <ROW>
- <ENTRY>NetBSD 1.3</ENTRY>
- <ENTRY>VAX</ENTRY>
- <ENTRY>v6.3</ENTRY>
- <ENTRY>1998-03-01</ENTRY>
- <ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
- </ROW>
<ROW>
<ENTRY>DGUX 5.4R4.11</ENTRY>
<ENTRY>m88k</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
- <ENTRY>(<ULink url="mailto:geek+@cmu.edu">Brian E Gallew</ULink>)</ENTRY>
+ <ENTRY>v6.4 probably OK. Needs new maintainer. (<ULink url="mailto:geek+@cmu.edu">Brian E Gallew</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>Digital Unix 4.0</ENTRY>
+ <ENTRY>Alpha</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-29</ENTRY>
+ <ENTRY>Minor patchable problems
+ (<ULink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>HPUX</ENTRY>
@@ -99,30 +82,20 @@ platforms:
<ENTRY>5.x is different
(<ULink url="mailto:martin@biochemistry.ucl.ac.uk">Andrew Martin</ULink>)</ENTRY>
</ROW>
- <ROW>
- <ENTRY>Digital 4.0</ENTRY>
- <ENTRY>Alpha</ENTRY>
- <ENTRY>v6.3.2</ENTRY>
- <ENTRY>1998-04-16</ENTRY>
- <ENTRY>reported working for DUnix/v3.2g
- (<ULink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ULink>)</ENTRY>
- </ROW>
<ROW>
<ENTRY>linux 2.0.x</ENTRY>
<ENTRY>Alpha</ENTRY>
<ENTRY>v6.3.2</ENTRY>
<ENTRY>1998-04-16</ENTRY>
- <ENTRY>mostly successful
- (<ULink url="mailto:rkirkpat@nag.cs.colorado.edu">Ryan Kirkpatrick</ULink>,
- <ULink url="mailto:jsturm@zenacomp.com"> Jeff Sturm </ULink>)</ENTRY>
+ <ENTRY>Mostly successful. Needs work for v6.4.
+ (<ULink url="mailto:rkirkpat@nag.cs.colorado.edu">Ryan Kirkpatrick</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>linux 2.0.x</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.4</ENTRY>
- <ENTRY>1998-10-09</ENTRY>
- <ENTRY>(<ULink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ULink>,
- <ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
+ <ENTRY>1998-10-27</ENTRY>
+ <ENTRY>(<ULink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>linux 2.0.x/glibc2</ENTRY>
@@ -140,33 +113,76 @@ platforms:
<ENTRY>(<ULink url="mailto:szybist@boxhill.com">Tom Szybist</ULink>)</ENTRY>
</ROW>
<ROW>
- <ENTRY>mklinux</ENTRY>
+ <ENTRY>linuxPPC 2.1.24</ENTRY>
+ <ENTRY>PPC603e</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-26</ENTRY>
+ <ENTRY>Powerbook 2400c(<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>mklinux DR3</ENTRY>
<ENTRY>PPC750</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-09-16</ENTRY>
- <ENTRY>(<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
+ <ENTRY>PowerMac 7600 (<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
</ROW>
<ROW>
- <ENTRY>SCO</ENTRY>
+ <ENTRY>NetBSD/i386 1.3.2</ENTRY>
<ENTRY>x86</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-25</ENTRY>
+ <ENTRY>(<ULink url="mailto:brook@trillium.NMSU.Edu">Brook Milligan</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>NetBSD-current</ENTRY>
+ <ENTRY>NS32532</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-27</ENTRY>
+ <ENTRY>(small problems in date/time math (<ULink url="mailto:jonb@metronet.com">Jon Buller</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>NetBSD/sparc 1.3H</ENTRY>
+ <ENTRY>Sparc</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-27</ENTRY>
+ <ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>NetBSD 1.3</ENTRY>
+ <ENTRY>VAX</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
- <ENTRY>partial success
- (<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
+ <ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
</ROW>
<ROW>
- <ENTRY>Solaris</ENTRY>
+ <ENTRY>SCO UnixWare 2.x</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
+ <ENTRY>aka UNIVEL
+ (<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>SCO UnixWare 7</ENTRY>
+ <ENTRY>x86</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-04</ENTRY>
+ <ENTRY>(<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
+ </ROW>
+ <ROW>
+ <ENTRY>Solaris</ENTRY>
+ <ENTRY>x86</ENTRY>
+ <ENTRY>v6.4</ENTRY>
+ <ENTRY>1998-10-28</ENTRY>
<ENTRY>(<ULink url="mailto:scrappy@hub.org">Marc Fournier</ULink>)</ENTRY>
</ROW>
<ROW>
- <ENTRY>Solaris 2.5.1-2.6</ENTRY>
+ <ENTRY>Solaris 2.6-2.7</ENTRY>
<ENTRY>Sparc</ENTRY>
<ENTRY>v6.4</ENTRY>
- <ENTRY>1998-10-25</ENTRY>
- <ENTRY>(<ULink url="mailto:szybist@boxhill.com">Tom Szybist</ULink>)</ENTRY>
+ <ENTRY>1998-10-28</ENTRY>
+ <ENTRY>(<ULink url="mailto:szybist@boxhill.com">Tom Szybist</ULink>,
+ <ULink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>SunOS 4.1.4</ENTRY>
@@ -180,7 +196,7 @@ platforms:
<ENTRY>SVR4</ENTRY>
<ENTRY>MIPS</ENTRY>
<ENTRY>v6.4</ENTRY>
- <ENTRY>1998-10-08</ENTRY>
+ <ENTRY>1998-10-28</ENTRY>
<ENTRY>no 64-bit int support
(<ULink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ULink>)</ENTRY>
</ROW>
@@ -192,14 +208,6 @@ platforms:
<ENTRY>confirmed with patching
(<ULink url="mailto:dlw@seavme.xroads.com">Doug Winterburn</ULink>)</ENTRY>
</ROW>
- <ROW>
- <ENTRY>Unixware</ENTRY>
- <ENTRY>x86</ENTRY>
- <ENTRY>v6.4</ENTRY>
- <ENTRY>1998-10-04</ENTRY>
- <ENTRY>aka UNIVEL
- (<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
- </ROW>
<ROW>
<ENTRY>Windows NT</ENTRY>
<ENTRY>x86</ENTRY>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index 0aee12b828c..6c5f7b38503 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -1,11 +1,16 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.12 1998/10/27 06:14:01 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.13 1998/10/30 19:37:09 thomas Exp $
Postgres integrated documentation.
Other subset docs should be copied and shrunk from here.
thomas 1998-02-23
$Log: postgres.sgml,v $
+Revision 1.13 1998/10/30 19:37:09 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
+
Revision 1.12 1998/10/27 06:14:01 thomas
Include configuration chapter with new info on configure and make.
@@ -13,23 +18,16 @@ Revision 1.11 1998/10/25 00:24:31 thomas
Add Y2K statement for intros.
Make sure notation section is included in most intros.
-Revision 1.10 1998/10/21 05:31:52 thomas
+Revision 1.7-1.10 1998/10/21 05:31:52 thomas
Include new information from Massimo. Rearrange ODBC docs.
-
-Revision 1.9 1998/09/30 05:41:49 thomas
-Clean up pages. Add information for operator precedence.
+Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
and notation sections appear in all documents without having the history
show up everplace too.
Add full list of reserved and non-reserved key words in syntax.sgml.
Add a separate chapter to the admin guide on security.
-
-Revision 1.8 1998/08/17 16:20:33 thomas
Move SQL reference pages up into the User's Guide.
-Revision 1.7 1998/08/15 06:52:53 thomas
-Include new chapters.
-
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
@@ -149,7 +147,8 @@ Include new chapters.
<LegalNotice>
<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
+<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
+by the Postgres Global Development Group.
</Para>
</LegalNotice>
diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml
index 060066dc3bc..fd21d57e33b 100644
--- a/doc/src/sgml/programmer.sgml
+++ b/doc/src/sgml/programmer.sgml
@@ -1,11 +1,16 @@
<!--
-$header$
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.9 1998/10/30 19:37:11 thomas Exp $
Postgres programmer's guide.
Derived from postgres.sgml.
-thomas 1998-02-24
+thomas 1998-10-27
+
+$Log: programmer.sgml,v $
+Revision 1.9 1998/10/30 19:37:11 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
-$log$
-->
@@ -81,7 +86,7 @@ $log$
<Title>PostgreSQL Programmer's Guide</Title>
<BookInfo>
- <ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
+ <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@@ -104,7 +109,7 @@ $log$
<AuthorInitials>TGL</AuthorInitials>
-->
- <Date>(last updated 1998-02-24)</Date>
+ <Date>(last updated 1998-10-27)</Date>
</BookBiblio>
<LegalNotice>
@@ -129,7 +134,7 @@ Your name here...
</Dedication>
-->
-<Preface>
+<Preface id="preface">
<Title>Summary</Title>
<Para>
@@ -153,13 +158,19 @@ It provides SQL92/SQL3 language support,
&xaggr;
&rules;
&xindex;
-&xplang;
&gist;
+&xplang;
&dfunc;
<!-- reference -->
+<!--
+The func-ref chapter is not currently useful.
+Disable it until we put in some info.
+- thomas 1998-10-27
&func-ref;
+-->
+
&trigger;
&spi;
&lobj;
@@ -176,7 +187,7 @@ It provides SQL92/SQL3 language support,
The arch-dev chapter is current almost identical
to the arch-pg chapter appearing earlier in the
Programmer's Guide. If the Developer's Guide is
-split into a separate document the start using this
+split into a separate document then start using this
again.
- thomas 1998-10-23
&arch-dev;
@@ -198,7 +209,8 @@ again.
&biblio;
<!--
-<INDEX> </INDEX>
+<index id="index">
+</index>
-->
</Book>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index a7324a68ece..ecb45c91a2c 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,9 +1,18 @@
<!-- reference.sgml
--
-- Postgres User's Reference documentation.
+
+$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.4 1998/10/30 19:37:12 thomas Exp $
+
+Postgres User's Reference documentation.
- thomas 1998-08-31
--
-- -->
+
+$Log: reference.sgml,v $
+Revision 1.4 1998/10/30 19:37:12 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
+
+
+-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity intro SYSTEM "intro.sgml">
@@ -61,7 +70,8 @@
<LegalNotice>
<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
+<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
+by the Postgres Global Development Group.
</Para>
</LegalNotice>
@@ -101,11 +111,16 @@ It provides SQL92/SQL3 language support,
&commands;
+<!--
&contacts;
+-->
+
&biblio;
+<!--
<index Id="index">
</index>
+-->
</Book>
diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml
index c184ff28460..eb6b1d6679f 100644
--- a/doc/src/sgml/spi.sgml
+++ b/doc/src/sgml/spi.sgml
@@ -12,47 +12,49 @@
<Title>Server Programming Interface</Title>
<Para>
- The <FirstTerm>Server Programming Interface</FirstTerm> (<Acronym>SPI</Acronym>) is an attempt to give users the
-ability to run <Acronym>SQL</Acronym> queries inside user-defined <Acronym>C</Acronym> functions.
-Given the lack
-of a proper <FirstTerm>Procedural Language</FirstTerm> (<Acronym>PL</Acronym>) in the current version of
-<ProductName>Postgres</ProductName>,
-<Acronym>SPI</Acronym> is the only way to write server-stored procedures and triggers. In the future
-<Acronym>SPI</Acronym> will be used as the "workhorse" for a <Acronym>PL</Acronym>.
+The <FirstTerm>Server Programming Interface</FirstTerm>
+(<Acronym>SPI</Acronym>) gives users the
+ability to run <Acronym>SQL</Acronym> queries inside user-defined
+<Acronym>C</Acronym> functions.
+The available Procedural Languages (<Acronym>PL</Acronym>) give an alternate
+means to access these capabilities.
</Para>
<Para>
- In fact, <Acronym>SPI</Acronym> is just a set of native interface functions to simplify
-access to the Parser, Planner, Optimizer and Executor. <Acronym>SPI</Acronym> also does some
-memory management.
+In fact, <Acronym>SPI</Acronym> is just a set of native interface functions
+to simplify access to the Parser, Planner, Optimizer and Executor.
+<Acronym>SPI</Acronym> also does some memory management.
</Para>
<Para>
- To avoid misunderstanding we'll use <FirstTerm>function</FirstTerm> to mean <Acronym>SPI</Acronym> interface
-functions and <FirstTerm>procedure</FirstTerm> for user-defined C-functions using <Acronym>SPI</Acronym>.
+To avoid misunderstanding we'll use <FirstTerm>function</FirstTerm>
+to mean <Acronym>SPI</Acronym> interface functions and
+<FirstTerm>procedure</FirstTerm> for user-defined C-functions
+using <Acronym>SPI</Acronym>.
</Para>
<Para>
- <Acronym>SPI</Acronym> procedures are always called by some (upper) Executor and the <Acronym>SPI</Acronym>
+<Acronym>SPI</Acronym> procedures are always called by some (upper)
+Executor and the <Acronym>SPI</Acronym>
manager uses the Executor to run your queries. Other procedures may be
called by the Executor running queries from your procedure.
</Para>
<Para>
- Note, that if during execution of a query from a procedure the transaction
+Note, that if during execution of a query from a procedure the transaction
is aborted then control will not be returned to your procedure. Rather, all work
will be rolled back and the server will wait for the next command from the
client. This will be changed in future versions.
</Para>
<Para>
- Other restrictions are the inability to execute BEGIN, END and ABORT
+Other restrictions are the inability to execute BEGIN, END and ABORT
(transaction control statements) and cursor operations. This will also be
changed in the future.
</Para>
<Para>
- If successful, <Acronym>SPI</Acronym> functions return a non-negative result (either via
+If successful, <Acronym>SPI</Acronym> functions return a non-negative result (either via
a returned integer value or in SPI_result global variable, as described below).
On error, a negative or NULL result will be returned.
</Para>
@@ -892,7 +894,7 @@ TBD
<REFNAME>SPI_execp
</REFNAME>
<REFPURPOSE>
- Executes a plan prepared or returned by <Function>SPI_saveplan</Function>
+Executes a plan from <Function>SPI_saveplan</Function>
</REFPURPOSE>
<INDEXTERM ID="IX-SPI-SPIEXECP-1"><PRIMARY>SPI</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-SPI-SPIEXECP-2"><PRIMARY>SPI_execp</PRIMARY></INDEXTERM>
diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml
index f612f651686..4d18a042da1 100644
--- a/doc/src/sgml/trigger.sgml
+++ b/doc/src/sgml/trigger.sgml
@@ -2,9 +2,10 @@
<Title>Triggers</Title>
<Para>
- While the current version of <ProductName>Postgres</ProductName> has various client interfaces
-such as Perl, Tcl, Python and C, it lacks an actual <FirstTerm>Procedural Language</FirstTerm>
-(PL). We hope to have a proper PL one day. In the meantime it is possible
+<ProductName>Postgres</ProductName> has various client interfaces
+such as Perl, Tcl, Python and C, as well as two
+<FirstTerm>Procedural Languages</FirstTerm>
+(PL). It is also possible
to call C functions as trigger actions. Note that STATEMENT-level trigger
events are not supported in the current version. You can currently specify
BEFORE or AFTER on INSERT, DELETE or UPDATE of a tuple as a trigger event.
diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml
index 38bd7d942db..713235cb3e7 100644
--- a/doc/src/sgml/user.sgml
+++ b/doc/src/sgml/user.sgml
@@ -1,11 +1,16 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.6 1998/09/30 05:41:54 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.7 1998/10/30 19:37:16 thomas Exp $
Postgres User's Manual.
Derived from postgres.sgml.
thomas 1998-02-24
$Log: user.sgml,v $
+Revision 1.7 1998/10/30 19:37:16 thomas
+Minor editing and markup changes as a result of preparing the Postscript
+ documentation for v6.4.
+Bigger updates to the installation instructions (install and config).
+
Revision 1.6 1998/09/30 05:41:54 thomas
Clean up pages. Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
@@ -17,9 +22,6 @@ Add a separate chapter to the admin guide on security.
Revision 1.5 1998/08/17 16:20:32 thomas
Move SQL reference pages up into the User's Guide.
-Revision 1.4 1998/08/15 06:52:54 thomas
-Include new chapters.
-
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
@@ -29,6 +31,7 @@ Include new chapters.
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
+<!entity y2k SYSTEM "y2k.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity advanced SYSTEM "advanced.sgml">
@@ -87,7 +90,8 @@ Include new chapters.
<LegalNotice>
<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
+<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
+by the Postgres Global Development Group.
</Para>
</LegalNotice>
@@ -141,10 +145,13 @@ It provides SQL92/SQL3 language support,
<!--
&contacts;
-->
+
&biblio;
+<!--
<index Id="index">
</index>
+-->
</Book>
diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml
index b4d9aa44028..b0a5a48b28c 100644
--- a/doc/src/sgml/xaggr.sgml
+++ b/doc/src/sgml/xaggr.sgml
@@ -2,31 +2,36 @@
<Title>Extending <Acronym>SQL</Acronym>: Aggregates</Title>
<Para>
- Aggregates in <ProductName>Postgres</ProductName> are expressed in terms of state
+ Aggregates in <ProductName>Postgres</ProductName>
+are expressed in terms of state
transition functions. That is, an aggregate can be
defined in terms of state that is modified whenever an
instance is processed. Some state functions look at a
particular value in the instance when computing the new
- state (<Acronym>sfunc1</Acronym> in the create aggregate syntax) while
+ state (<Acronym>sfunc1</Acronym> in the
+create aggregate syntax) while
others only keep track of their own internal state
(<Acronym>sfunc2</Acronym>).
- If we define an aggregate that uses only <Acronym>sfunc1</Acronym>, we
+ If we define an aggregate that uses only
+<Acronym>sfunc1</Acronym>, we
define an aggregate that computes a running function of
the attribute values from each instance. "Sum" is an
example of this kind of aggregate. "Sum" starts at
zero and always adds the current instance's value to
- its running total. We will use the <Acronym>int4pl</Acronym> that is
- built into <ProductName>Postgres</ProductName> to perform this addition.
+ its running total. We will use the
+<Acronym>int4pl</Acronym> that is
+ built into <ProductName>Postgres</ProductName>
+to perform this addition.
<ProgramListing>
- CREATE AGGREGATE complex_sum (
- sfunc1 = complex_add,
- basetype = complex,
- stype1 = complex,
- initcond1 = '(0,0)'
- );
+CREATE AGGREGATE complex_sum (
+ sfunc1 = complex_add,
+ basetype = complex,
+ stype1 = complex,
+ initcond1 = '(0,0)'
+);
- SELECT complex_sum(a) FROM test_complex;
+SELECT complex_sum(a) FROM test_complex;
+------------+
|complex_sum |
@@ -37,22 +42,27 @@
</Para>
<Para>
- If we define only <Acronym>sfunc2</Acronym>, we are specifying an aggregate
+ If we define only <Acronym>sfunc2</Acronym>, we are
+specifying an aggregate
that computes a running function that is independent of
the attribute values from each instance.
"Count" is the most common example of this kind of
aggregate. "Count" starts at zero and adds one to its
running total for each instance, ignoring the instance
- value. Here, we use the built-in <Acronym>int4inc</Acronym> routine to do
+ value. Here, we use the built-in
+<Acronym>int4inc</Acronym> routine to do
the work for us. This routine increments (adds one to)
its argument.
<ProgramListing>
- CREATE AGGREGATE my_count (sfunc2 = int4inc, -- add one
- basetype = int4, stype2 = int4,
- initcond2 = '0')
+CREATE AGGREGATE my_count (
+ sfunc2 = int4inc, -- add one
+ basetype = int4,
+ stype2 = int4,
+ initcond2 = '0'
+);
- SELECT my_count(*) as emp_count from EMP;
+SELECT my_count(*) as emp_count from EMP;
+----------+
|emp_count |
@@ -74,16 +84,18 @@
the count.
<ProgramListing>
- CREATE AGGREGATE my_average (sfunc1 = int4pl, -- sum
- basetype = int4,
- stype1 = int4,
- sfunc2 = int4inc, -- count
- stype2 = int4,
- finalfunc = int4div, -- division
- initcond1 = '0',
- initcond2 = '0')
+CREATE AGGREGATE my_average (
+ sfunc1 = int4pl, -- sum
+ basetype = int4,
+ stype1 = int4,
+ sfunc2 = int4inc, -- count
+ stype2 = int4,
+ finalfunc = int4div, -- division
+ initcond1 = '0',
+ initcond2 = '0'
+);
- SELECT my_average(salary) as emp_average FROM EMP;
+SELECT my_average(salary) as emp_average FROM EMP;
+------------+
|emp_average |
diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml
index 742d6a3ba64..feb1cc88a29 100644
--- a/doc/src/sgml/xplang.sgml
+++ b/doc/src/sgml/xplang.sgml
@@ -1,5 +1,5 @@
<Chapter Id="xplang">
-<Title>Extending <Acronym>SQL</Acronym>: Procedural languages</Title>
+<Title>Procedural Languages</Title>
<!-- **********
* General information about procedural language support
diff --git a/doc/src/sgml/y2k.sgml b/doc/src/sgml/y2k.sgml
index a2d9f2e434e..ed317aaa451 100644
--- a/doc/src/sgml/y2k.sgml
+++ b/doc/src/sgml/y2k.sgml
@@ -42,7 +42,7 @@ are documented in the current
<ulink url="http://www.postgresql.org/docs/user/datatype.htm">User's Guide</ulink>
in the chapter on data types.
For two-digit years, the significant transition year is 1970, not 2000;
-i.e. <quote>70-01-01</quote> is interpreted as <quote>1970-01-01</quote>,
+e.g. <quote>70-01-01</quote> is interpreted as <quote>1970-01-01</quote>,
whereas <quote>69-01-01</quote> is interpreted as <quote>2069-01-01</quote>.
<listitem>
--
GitLab