From cde8bbc413d006b3534d42bd7a789e3820a95596 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Wed, 19 Feb 2003 04:06:28 +0000
Subject: [PATCH] This patch makes the following changes to the documentation:
- more work from the SGML police
- some grammar improvements: rewriting a paragraph or two, replacing
contractions where (IMHO) appropriate
- fix missing utility commands in lock mode docs
- improve CLUSTER, REINDEX, SET SESSION AUTHORIZATION ref pages
Neil Conway
---
doc/src/sgml/advanced.sgml | 8 ++--
doc/src/sgml/arch-dev.sgml | 58 +++++++++++++-------------
doc/src/sgml/datatype.sgml | 4 +-
doc/src/sgml/ddl.sgml | 14 +++----
doc/src/sgml/docguide.sgml | 4 +-
doc/src/sgml/mvcc.sgml | 28 +++++++------
doc/src/sgml/page.sgml | 7 ++--
doc/src/sgml/plpgsql.sgml | 6 +--
doc/src/sgml/ref/alter_table.sgml | 26 ++++++------
doc/src/sgml/ref/cluster.sgml | 31 +++++++++++---
doc/src/sgml/ref/clusterdb.sgml | 4 +-
doc/src/sgml/ref/reindex.sgml | 44 +++++++++++++------
doc/src/sgml/ref/set_session_auth.sgml | 32 +++++++-------
doc/src/sgml/ref/vacuum.sgml | 10 ++++-
doc/src/sgml/runtime.sgml | 8 ++--
doc/src/sgml/sql.sgml | 47 +++++++++++----------
doc/src/sgml/start.sgml | 4 +-
doc/src/sgml/typeconv.sgml | 2 +-
doc/src/sgml/xfunc.sgml | 8 ++--
src/backend/catalog/index.c | 6 +--
20 files changed, 205 insertions(+), 146 deletions(-)
diff --git a/doc/src/sgml/advanced.sgml b/doc/src/sgml/advanced.sgml
index cc5d8cd52df..b7cc0595e3b 100644
--- a/doc/src/sgml/advanced.sgml
+++ b/doc/src/sgml/advanced.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.31 2002/11/11 20:14:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.32 2003/02/19 04:06:27 momjian Exp $
-->
<chapter id="tutorial-advanced">
@@ -41,7 +41,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/advanced.sgml,v 1.31 2002/11/11 20:14:02 pe
<para>
Refer back to the queries in <xref linkend="tutorial-join">.
Suppose the combined listing of weather records and city location
- is of particular interest to your application, but you don't want
+ is of particular interest to your application, but you do not want
to type the query each time you need it. You can create a
<firstterm>view</firstterm> over the query, which gives a name to
the query that you can refer to like an ordinary table.
@@ -232,7 +232,7 @@ COMMIT;
</para>
<para>
- If, partway through the transaction, we decide we don't want to
+ If, partway through the transaction, we decide we do not want to
commit (perhaps we just noticed that Alice's balance went negative),
we can issue the command <command>ROLLBACK</> instead of
<command>COMMIT</>, and all our updates so far will be canceled.
@@ -240,7 +240,7 @@ COMMIT;
<para>
<productname>PostgreSQL</> actually treats every SQL statement as being
- executed within a transaction. If you don't issue a <command>BEGIN</>
+ executed within a transaction. If you do not issue a <command>BEGIN</>
command,
then each individual statement has an implicit <command>BEGIN</> and
(if successful) <command>COMMIT</> wrapped around it. A group of
diff --git a/doc/src/sgml/arch-dev.sgml b/doc/src/sgml/arch-dev.sgml
index 05dba36ff91..d9619643e94 100644
--- a/doc/src/sgml/arch-dev.sgml
+++ b/doc/src/sgml/arch-dev.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.17 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.18 2003/02/19 04:06:27 momjian Exp $
-->
<chapter id="overview">
@@ -17,15 +17,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.17 2003/01/19 00:13:28 mo
<para>
This chapter gives an overview of the internal structure of the
- backend of <productname>PostgreSQL</productname>.
- After having read the following sections you
- should have an idea of how a query is processed. Don't expect a
- detailed description here (I think such a description dealing with
- all data structures and functions used within <productname>PostgreSQL</productname>
- would exceed 1000
- pages!). This chapter is intended to help understanding the general
- control and data flow within the backend from receiving a query to
- sending the results.
+ backend of <productname>PostgreSQL</productname>. After having
+ read the following sections you should have an idea of how a query
+ is processed. This chapter does not aim to provide a detailed
+ description of the internal operation of
+ <productname>PostgreSQL</productname>, as such a document would be
+ very extensive. Rather, this chapter is intended to help the reader
+ understand the general sequence of operations that occur within the
+ backend from the point at which a query is received, to the point
+ when the results are returned to the client.
</para>
<sect1 id="query-path">
@@ -118,23 +118,25 @@ $Header: /cvsroot/pgsql/doc/src/sgml/arch-dev.sgml,v 2.17 2003/01/19 00:13:28 mo
<title>How Connections are Established</title>
<para>
- <productname>PostgreSQL</productname> is implemented using a simple "process per-user"
- client/server model. In this model there is one <firstterm>client process</firstterm>
- connected to exactly one <firstterm>server process</firstterm>.
- As we don't know <foreignphrase>per se</foreignphrase>
- how many connections will be made, we have to use a <firstterm>master process</firstterm>
- that spawns a new server process every time a connection is
- requested. This master process is called <literal>postmaster</literal> and
- listens at a specified TCP/IP port for incoming connections. Whenever
- a request for a connection is detected the <literal>postmaster</literal> process
- spawns a new server process called <literal>postgres</literal>. The server
- tasks (<literal>postgres</literal> processes) communicate with each other using
- <firstterm>semaphores</firstterm> and <firstterm>shared memory</firstterm>
- to ensure data integrity
- throughout concurrent data access. Figure
- \ref{connection} illustrates the interaction of the master process
- <literal>postmaster</literal> the server process <literal>postgres</literal> and a client
- application.
+ <productname>PostgreSQL</productname> is implemented using a
+ simple "process per-user" client/server model. In this model
+ there is one <firstterm>client process</firstterm> connected to
+ exactly one <firstterm>server process</firstterm>. As we do not
+ know ahead of time how many connections will be made, we have to
+ use a <firstterm>master process</firstterm> that spawns a new
+ server process every time a connection is requested. This master
+ process is called <literal>postmaster</literal> and listens at a
+ specified TCP/IP port for incoming connections. Whenever a request
+ for a connection is detected the <literal>postmaster</literal>
+ process spawns a new server process called
+ <literal>postgres</literal>. The server tasks
+ (<literal>postgres</literal> processes) communicate with each
+ other using <firstterm>semaphores</firstterm> and
+ <firstterm>shared memory</firstterm> to ensure data integrity
+ throughout concurrent data access. Figure \ref{connection}
+ illustrates the interaction of the master process
+ <literal>postmaster</literal> the server process
+ <literal>postgres</literal> and a client application.
</para>
<para>
@@ -686,7 +688,7 @@ current context are performed.
for the <literal>varno</literal> fields in the
<literal>VAR</literal> nodes appearing in the <literal>mergeclauses</literal> list (and also in the
<literal>targetlist</literal>) mean that not the tuples of the current node should be
- considered but the tuples of the next "deeper" nodes (i.e. the top
+ considered but the tuples of the next <quote>deeper</quote> nodes (i.e. the top
nodes of the subplans) should be used instead.
</para>
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 093ce275af4..c7ee2aedd32 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.114 2003/02/19 03:48:10 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.115 2003/02/19 04:06:27 momjian Exp $
-->
<chapter id="datatype">
@@ -895,7 +895,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
actual string, and in case of <type>character</type> plus the
padding. Long strings are compressed by the system automatically, so
the physical requirement on disk may be less. Long values are also
- stored in background tables so they don't interfere with rapid
+ stored in background tables so they do not interfere with rapid
access to the shorter column values. In any case, the longest
possible character string that can be stored is about 1 GB. (The
maximum value that will be allowed for <replaceable>n</> in the data
diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index 01ea0488df3..666e6433ef6 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.11 2003/02/19 03:13:24 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ddl.sgml,v 1.12 2003/02/19 04:06:27 momjian Exp $ -->
<chapter id="ddl">
<title>Data Definition</title>
@@ -115,8 +115,8 @@ CREATE TABLE products (
</para>
<para>
- If you don't need a table anymore, you can remove it using the
- <literal>DROP TABLE</literal> command. For example:
+ If you no longer need a table, you can remove it using the
+ <command>DROP TABLE</command> command. For example:
<programlisting>
DROP TABLE my_first_table;
DROP TABLE products;
@@ -718,7 +718,7 @@ CREATE TABLE order_items (
<para>
We know that the foreign keys disallow creation of orders that
- don't relate to any products. But what if a product is removed
+ do not relate to any products. But what if a product is removed
after an order is created that references it? SQL allows you to
specify that as well. Intuitively, we have a few options:
<itemizedlist spacing="compact">
@@ -759,7 +759,7 @@ CREATE TABLE order_items (
<para>
Restricting and cascading deletes are the two most common options.
<literal>RESTRICT</literal> can also be written as <literal>NO
- ACTION</literal> and it's also the default if you don't specify
+ ACTION</literal> and it's also the default if you do not specify
anything. There are two other options for what should happen with
the foreign key columns when a primary key is deleted:
<literal>SET NULL</literal> and <literal>SET DEFAULT</literal>.
@@ -1602,7 +1602,7 @@ REVOKE CREATE ON public FROM PUBLIC;
<para>
In the SQL standard, the notion of objects in the same schema
being owned by different users does not exist. Moreover, some
- implementations don't allow you to create schemas that have a
+ implementations do not allow you to create schemas that have a
different name than their owner. In fact, the concepts of schema
and user are nearly equivalent in a database system that
implements only the basic schema support specified in the
@@ -1686,7 +1686,7 @@ NOTICE: constraint $1 on table orders depends on table products
ERROR: Cannot drop table products because other objects depend on it
Use DROP ... CASCADE to drop the dependent objects too
</screen>
- The error message contains a useful hint: If you don't want to
+ The error message contains a useful hint: if you do not want to
bother deleting all the dependent objects individually, you can run
<screen>
DROP TABLE products CASCADE;
diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml
index 10c0463844f..e52653ed146 100644
--- a/doc/src/sgml/docguide.sgml
+++ b/doc/src/sgml/docguide.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.42 2002/07/28 15:22:20 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.43 2003/02/19 04:06:27 momjian Exp $ -->
<appendix id="docguide">
<title>Documentation</title>
@@ -1327,7 +1327,7 @@ End:
<listitem>
<para>
If the program uses 0 for success and non-zero for failure,
- then you don't need to document it. If there is a meaning
+ then you do not need to document it. If there is a meaning
behind the different non-zero exit codes, list them here.
</para>
</listitem>
diff --git a/doc/src/sgml/mvcc.sgml b/doc/src/sgml/mvcc.sgml
index ef7278b1c6a..d8d16eae5da 100644
--- a/doc/src/sgml/mvcc.sgml
+++ b/doc/src/sgml/mvcc.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.32 2003/01/11 00:00:02 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.33 2003/02/19 04:06:28 momjian Exp $
-->
<chapter id="mvcc">
@@ -38,9 +38,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/mvcc.sgml,v 2.32 2003/01/11 00:00:02 petere
</para>
<para>
- The main difference between multiversion and lock models is that
- in <acronym>MVCC</acronym> locks acquired for querying (reading)
- data don't conflict with locks acquired for writing data, and so
+ The main advantage to using the <acronym>MVCC</acronym> model of
+ concurrency control rather than locking is that in
+ <acronym>MVCC</acronym> locks acquired for querying (reading) data
+ do not conflict with locks acquired for writing data, and so
reading never blocks writing and writing never blocks reading.
</para>
@@ -437,10 +438,10 @@ ERROR: Can't serialize access due to concurrent update
</para>
<para>
- The <command>SELECT</command> command acquires a
- lock of this mode on referenced tables. In general, any query
- that only reads a table and does not modify it will acquire
- this lock mode.
+ The commands <command>SELECT</command> and
+ <command>ANALYZE</command> acquire a lock of this mode on
+ referenced tables. In general, any query that only reads a table
+ and does not modify it will acquire this lock mode.
</para>
</listitem>
</varlistentry>
@@ -586,9 +587,10 @@ ERROR: Can't serialize access due to concurrent update
<para>
Acquired by the <command>ALTER TABLE</command>, <command>DROP
- TABLE</command>, and <command>VACUUM FULL</command> commands.
- This is also the default lock mode for <command>LOCK TABLE</command>
- statements that do not specify a mode explicitly.
+ TABLE</command>, <command>REINDEX</command>,
+ <command>CLUSTER</command>, and <command>VACUUM FULL</command>
+ commands. This is also the default lock mode for <command>LOCK
+ TABLE</command> statements that do not specify a mode explicitly.
</para>
</listitem>
</varlistentry>
@@ -612,7 +614,7 @@ ERROR: Can't serialize access due to concurrent update
A row-level lock on a specific row is automatically acquired when the
row is updated (or deleted or marked for update). The lock is held
until the transaction commits or rolls back.
- Row-level locks don't affect data
+ Row-level locks do not affect data
querying; they block <emphasis>writers to the same row</emphasis>
only. To acquire a row-level lock on a row without actually
modifying the row, select the row with <command>SELECT FOR
@@ -726,7 +728,7 @@ UPDATE accounts SET balance = balance - 100.00 WHERE acctnum = 22222;
<para>
Because readers in <productname>PostgreSQL</productname>
- don't lock data, regardless of
+ do not lock data, regardless of
transaction isolation level, data read by one transaction can be
overwritten by another concurrent transaction. In other words,
if a row is returned by <command>SELECT</command> it doesn't mean that
diff --git a/doc/src/sgml/page.sgml b/doc/src/sgml/page.sgml
index d7096a4bbe1..1c501e3d00e 100644
--- a/doc/src/sgml/page.sgml
+++ b/doc/src/sgml/page.sgml
@@ -196,9 +196,10 @@ data. Empty in ordinary tables.</entry>
<para>
- The final section is the "special section" which may contain anything the
- access method wishes to store. Ordinary tables do not use this at all
- (indicated by setting <structfield>pd_special</> to equal the pagesize).
+ The final section is the <quote>special section</quote> which may
+ contain anything the access method wishes to store. Ordinary tables
+ do not use this at all (indicated by setting
+ <structfield>pd_special</> to equal the pagesize).
</para>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 999b9805a2e..dc394ffa4f5 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.14 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.15 2003/02/19 04:06:28 momjian Exp $
-->
<chapter id="plpgsql">
@@ -578,7 +578,7 @@ user_id users.user_id%TYPE;
</para>
<para>
- By using <type>%TYPE</type> you don't need to know
+ By using <type>%TYPE</type> you do not need to know
the data type of the structure you are referencing,
and most important, if the data type of the
referenced item changes in the future (e.g: you
@@ -1649,7 +1649,7 @@ END LOOP;
up a <firstterm>cursor</> that encapsulates the query, and then read
the query result a few rows at a time. One reason for doing this is
to avoid memory overrun when the result contains a large number of
- rows. (However, <application>PL/pgSQL</> users don't normally need
+ rows. (However, <application>PL/pgSQL</> users do not normally need
to worry about that, since FOR loops automatically use a cursor
internally to avoid memory problems.) A more interesting usage is to
return a reference to a cursor that it has created, allowing the
diff --git a/doc/src/sgml/ref/alter_table.sgml b/doc/src/sgml/ref/alter_table.sgml
index 5499cd158cc..2b084456013 100644
--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.55 2003/02/13 05:19:59 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.56 2003/02/19 04:06:28 momjian Exp $
PostgreSQL documentation
-->
@@ -367,7 +367,7 @@ ALTER TABLE <replaceable class="PARAMETER">table</replaceable>
default and NOT NULL clauses for the new column are not supported.
The new column always comes into being with all values NULL.
You can use the <literal>SET DEFAULT</literal> form
- of <command>ALTER TABLE</command> to set the default afterwards.
+ of <command>ALTER TABLE</command> to set the default afterward.
(You may also want to update the already existing rows to the
new default value, using
<xref linkend="sql-update" endterm="sql-update-title">.)
@@ -392,19 +392,21 @@ VACUUM FULL table;
</para>
<para>
- If a table has any descendant tables, it is not permitted to ADD or
- RENAME a column in the parent table without doing the same to the
- descendants --- that is, ALTER TABLE ONLY will be rejected. This
- ensures that the descendants always have columns matching the parent.
+ If a table has any descendant tables, it is not permitted to ADD
+ or RENAME a column in the parent table without doing the same to
+ the descendants --- that is, <command>ALTER TABLE ONLY</command>
+ will be rejected. This ensures that the descendants always have
+ columns matching the parent.
</para>
<para>
- A recursive DROP COLUMN operation will remove a descendant table's column
- only if the descendant does not inherit that column from any other
- parents and never had an independent definition of the column.
- A nonrecursive DROP COLUMN (i.e., ALTER TABLE ONLY ... DROP COLUMN)
- never removes any descendant columns, but instead marks them as
- independently defined rather than inherited.
+ A recursive <literal>DROP COLUMN</literal> operation will remove a
+ descendant table's column only if the descendant does not inherit
+ that column from any other parents and never had an independent
+ definition of the column. A nonrecursive <literal>DROP
+ COLUMN</literal> (i.e., <command>ALTER TABLE ONLY ... DROP
+ COLUMN</command>) never removes any descendant columns, but
+ instead marks them as independently defined rather than inherited.
</para>
<para>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 95daa8bf176..1c3874c8d1a 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.23 2002/12/30 18:42:12 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.24 2003/02/19 04:06:28 momjian Exp $
PostgreSQL documentation
-->
@@ -117,11 +117,19 @@ CLUSTER
<command>CLUSTER</command> without any parameter re-clusters all the tables
in the
current database that the calling user owns, or all tables if called
- by a superuser. (Never-clustered tables are not touched.) This
+ by a superuser. (Never-clustered tables are not included.) This
form of <command>CLUSTER</command> cannot be called from inside a
transaction or function.
</para>
+ <para>
+ When a table is being clustered, an <literal>ACCESS
+ EXCLUSIVE</literal> lock is acquired on it. This prevents any other
+ database operations (both reads and writes) from preceding on the
+ table until the <command>CLUSTER</command> is finished. See the
+ &cite-user; for more information on database locking.
+ </para>
+
<refsect2 id="R2-SQL-CLUSTER-3">
<refsect2info>
<date>1998-09-08</date>
@@ -159,8 +167,9 @@ CLUSTER
</para>
<para>
- <command>CLUSTER</command> preserves GRANT, inheritance, index, foreign
- key, and other ancillary information about the table.
+ <command>CLUSTER</command> preserves <command>GRANT</command>,
+ inheritance, index, foreign key, and other ancillary information
+ about the table.
</para>
<para>
@@ -212,13 +221,15 @@ SELECT <replaceable class="parameter">columnlist</replaceable> INTO TABLE <repla
Usage
</title>
<para>
- Cluster the employees relation on the basis of its ID attribute:
+ Cluster the <literal>employees</literal> relation on the basis of
+ its ID attribute:
</para>
<programlisting>
CLUSTER emp_ind ON emp;
</programlisting>
<para>
- Cluster the employees relation using the same index that was used before:
+ Cluster the <literal>employees</literal> relation using the same
+ index that was used before:
</para>
<programlisting>
CLUSTER emp;
@@ -248,6 +259,14 @@ CLUSTER;
</para>
</refsect2>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="app-clusterdb" endterm="app-clusterdb-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index 1b8f9ba331a..4a158f334c8 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.6 2003/02/13 05:37:43 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.7 2003/02/19 04:06:28 momjian Exp $
PostgreSQL documentation
-->
@@ -37,7 +37,7 @@ PostgreSQL documentation
in a <productname>PostgreSQL</productname> database. It finds tables
that have previously been clustered, and clusters them again on the same
index that was last used. Tables that have never been clustered are not
- touched.
+ affected.
</para>
<para>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 08666b2f02a..e146fe53928 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.14 2002/11/17 23:43:32 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.15 2003/02/19 04:06:28 momjian Exp $
PostgreSQL documentation
-->
@@ -38,8 +38,9 @@ REINDEX { DATABASE | TABLE | INDEX } <replaceable class="PARAMETER">name</replac
<term>DATABASE</term>
<listitem>
<para>
- Recreate all system indexes of a specified database.
- (User-table indexes are not included.)
+ Recreate all system indexes of a specified database. Indexes on
+ user tables are not included. This form of <command>REINDEX</> can
+ only be used in standalone mode (see below).
</para>
</listitem>
</varlistentry>
@@ -116,16 +117,35 @@ REINDEX
Description
</title>
<para>
- <command>REINDEX</command> is used to rebuild corrupted indexes.
- Although in theory this should never be necessary, in practice
- indexes may become corrupted due to software bugs or hardware
- failures. <command>REINDEX</command> provides a recovery method.
- </para>
+ <command>REINDEX</command> rebuilds an index based on the data
+ stored in the table, replacing the old copy of the index. There are
+ two main reasons to use <command>REINDEX</command>:
- <para>
- <command>REINDEX</command> also removes certain dead index pages that
- can't be reclaimed any other way. See the "Routine Reindexing"
- section in the manual for more information.
+ <orderedlist>
+ <listitem>
+ <para>
+ An index has become corrupted, and no longer contains valid
+ data. Although in theory this should never be necessary, in
+ practice indexes may become corrupted due to software bugs or
+ hardware failures. <command>REINDEX</command> provides a
+ recovery method.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The index in question contains a lot of dead index pages that
+ are not being reclaimed. This can occur with B+-tree indexes
+ under certain access patterns. <command>REINDEX</command>
+ provides a way to reduce the space consumption of the index by
+ writing a new version of the index without the dead pages. See
+ the <quote>Routine Reindexing</quote> section in the
+ &cite-admin; for more information. The rest of this section
+ mostly discusses how to use <command>REINDEX</command> to
+ recover from index corruption.
+ </para>
+ </listitem>
+ </orderedlist>
</para>
<para>
diff --git a/doc/src/sgml/ref/set_session_auth.sgml b/doc/src/sgml/ref/set_session_auth.sgml
index eb9d760f10e..88d5578498c 100644
--- a/doc/src/sgml/ref/set_session_auth.sgml
+++ b/doc/src/sgml/ref/set_session_auth.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.7 2002/09/21 18:32:54 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.8 2003/02/19 04:06:28 momjian Exp $ -->
<refentry id="SQL-SET-SESSION-AUTHORIZATION">
<docinfo>
<date>2001-04-21</date>
@@ -16,7 +16,7 @@
<refsynopsisdiv>
<synopsis>
-SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <parameter>username</parameter>
+SET [ SESSION | LOCAL ] SESSION AUTHORIZATION <replaceable class="PARAMETER">username</replaceable>
SET [ SESSION | LOCAL ] SESSION AUTHORIZATION DEFAULT
RESET SESSION AUTHORIZATION
</synopsis>
@@ -27,12 +27,12 @@ RESET SESSION AUTHORIZATION
<para>
This command sets the session user identifier and the current user
- identifier of the current SQL-session context to be
- <parameter>username</parameter>. The user name may be written as
- either an identifier or a string literal.
- The session user identifier is valid for the duration of a
- connection; for example, it is possible to temporarily become an
- unprivileged user and later switch back to become a superuser.
+ identifier of the current SQL-session context to be <replaceable
+ class="PARAMETER">username</replaceable>. The user name may be
+ written as either an identifier or a string literal. The session
+ user identifier is valid for the duration of a connection; for
+ example, it is possible to temporarily become an unprivileged user
+ and later switch back to become a superuser.
</para>
<para>
@@ -68,19 +68,21 @@ RESET SESSION AUTHORIZATION
<refsect1>
<title>Examples</title>
-<screen>
-<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
- current_user | session_user
+<programlisting>
+SELECT SESSION_USER, CURRENT_USER;
+
+ session_user | current_user
--------------+--------------
peter | peter
-<userinput>SET SESSION AUTHORIZATION 'paul';</userinput>
+SET SESSION AUTHORIZATION 'paul';
+
+SELECT SESSION_USER, CURRENT_USER;
-<userinput>SELECT SESSION_USER, CURRENT_USER;</userinput>
- current_user | session_user
+ session_user | current_user
--------------+--------------
paul | paul
-</screen>
+</programlisting>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 07dbbaed2a7..b8ab33cbe4a 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.28 2003/01/19 00:13:31 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.29 2003/02/19 04:06:28 momjian Exp $
PostgreSQL documentation
-->
@@ -286,6 +286,14 @@ VACUUM
</para>
</refsect2>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="app-vacuumdb" endterm="app-vacuumdb-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index cd171c41d28..b023940dc3d 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.168 2003/02/06 20:25:31 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.169 2003/02/19 04:06:28 momjian Exp $
-->
<Chapter Id="runtime">
@@ -122,7 +122,7 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
<para>
However, while the directory contents are secure, the default
client authentication setup allows any local user to connect to the
- database and even become the database superuser. If you don't trust
+ database and even become the database superuser. If you do not trust
other local users, we recommend you use <command>initdb</command>'s
<option>-W</option> or <option>--pwprompt</option> option to assign a
password to the database superuser. After <command>initdb</command>,
@@ -365,7 +365,7 @@ FATAL 1: ShmemCreate: cannot create region
probably means your kernel's limit on the size of shared memory is
smaller than the buffer area <productname>PostgreSQL</productname>
is trying to create (83918612 bytes in this example). Or it could
- mean that you don't have System-V-style shared memory support
+ mean that you do not have System-V-style shared memory support
configured into your kernel at all. As a temporary workaround, you
can try starting the postmaster with a smaller-than-normal number
of buffers (<option>-B</option> switch). You will eventually want
@@ -2937,7 +2937,7 @@ default:\
On the other side of the coin, some systems allow individual
processes to open large numbers of files; if more than a few
processes do so then the system-wide limit can easily be exceeded.
- If you find this happening, and don't want to alter the system-wide
+ If you find this happening, and you do not want to alter the system-wide
limit, you can set <productname>PostgreSQL</productname>'s
<varname>max_files_per_process</varname> configuration parameter to
limit the consumption of open files.
diff --git a/doc/src/sgml/sql.sgml b/doc/src/sgml/sql.sgml
index 423f5155d24..9e788ff0616 100644
--- a/doc/src/sgml/sql.sgml
+++ b/doc/src/sgml/sql.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.29 2003/02/19 04:06:28 momjian Exp $
-->
<chapter id="sql">
@@ -24,7 +24,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian
<para>
<acronym>SQL</acronym> has become the most popular relational query
language.
- The name "<acronym>SQL</acronym>" is an abbreviation for
+ The name <quote><acronym>SQL</acronym></quote> is an abbreviation for
<firstterm>Structured Query Language</firstterm>.
In 1974 Donald Chamberlin and others defined the
language SEQUEL (<firstterm>Structured English Query
@@ -72,10 +72,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian
(<acronym>ISO</acronym>).
This original standard version of <acronym>SQL</acronym> is often
referred to,
- informally, as "<abbrev>SQL/86</abbrev>". In 1989 the original
+ informally, as <quote><abbrev>SQL/86</abbrev></quote>. In 1989 the original
standard was extended
and this new standard is often, again informally, referred to as
- "<abbrev>SQL/89</abbrev>". Also in 1989, a related standard called
+ <quote><abbrev>SQL/89</abbrev></quote>. Also in 1989, a related standard called
<firstterm>Database Language Embedded <acronym>SQL</acronym></firstterm>
(<acronym>ESQL</acronym>) was developed.
</para>
@@ -86,11 +86,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/sql.sgml,v 1.28 2003/01/15 18:01:05 momjian
definition of a greatly expanded version of the original standard,
referred to informally as <firstterm><acronym>SQL2</acronym></firstterm>
or <firstterm><acronym>SQL/92</acronym></firstterm>. This version became a
- ratified standard - "International Standard ISO/IEC 9075:1992,
- Database Language <acronym>SQL</acronym>" - in late 1992.
+ ratified standard - <quote>International Standard ISO/IEC 9075:1992,
+ Database Language <acronym>SQL</acronym></quote> - in late 1992.
<acronym>SQL/92</acronym> is the version
- normally meant when people refer to "the <acronym>SQL</acronym>
- standard". A detailed
+ normally meant when people refer to <quote>the <acronym>SQL</acronym>
+ standard</quote>. A detailed
description of <acronym>SQL/92</acronym> is given in
<xref linkend="DATE97" endterm="DATE97">. At the time of
writing this document a new standard informally referred to
@@ -768,8 +768,8 @@ x(A) ∣ F(x)
can be formulated using relational algebra can also be formulated
using the relational calculus and vice versa.
This was first proved by E. F. Codd in
- 1972. This proof is based on an algorithm ("Codd's reduction
- algorithm") by which an arbitrary expression of the relational
+ 1972. This proof is based on an algorithm (<quote>Codd's reduction
+ algorithm</quote>) by which an arbitrary expression of the relational
calculus can be reduced to a semantically equivalent expression of
relational algebra. For a more detailed discussion on that refer to
<xref linkend="DATE94" endterm="DATE94">
@@ -778,11 +778,12 @@ x(A) ∣ F(x)
</para>
<para>
- It is sometimes said that languages based on the relational calculus
- are "higher level" or "more declarative" than languages based on
- relational algebra because the algebra (partially) specifies the order
- of operations while the calculus leaves it to a compiler or
- interpreter to determine the most efficient order of evaluation.
+ It is sometimes said that languages based on the relational
+ calculus are <quote>higher level</quote> or <quote>more
+ declarative</quote> than languages based on relational algebra
+ because the algebra (partially) specifies the order of operations
+ while the calculus leaves it to a compiler or interpreter to
+ determine the most efficient order of evaluation.
</para>
</sect2>
</sect1>
@@ -870,9 +871,10 @@ SELECT [ ALL | DISTINCT [ ON ( <replaceable class="PARAMETER">expression</replac
</para>
<para>
- Now we will illustrate the complex syntax of the SELECT statement
- with various examples. The tables used for the examples are defined in
- <xref linkend="supplier-fig" endterm="supplier-fig">.
+ Now we will illustrate the complex syntax of the
+ <command>SELECT</command> statement with various examples. The
+ tables used for the examples are defined in <xref
+ linkend="supplier-fig" endterm="supplier-fig">.
</para>
<sect3>
@@ -903,7 +905,7 @@ SELECT * FROM PART
</para>
<para>
- Using "*" in the SELECT statement will deliver all attributes from
+ Using <quote>*</quote> in the SELECT statement will deliver all attributes from
the table. If we want to retrieve only the attributes PNAME and PRICE
from table PART we use the statement:
@@ -922,9 +924,10 @@ SELECT PNAME, PRICE
Cam | 25
</programlisting>
- Note that the <acronym>SQL</acronym> SELECT corresponds to the
- "projection" in relational algebra not to the "selection"
- (see <xref linkend="rel-alg" endterm="rel-alg"> for more details).
+ Note that the <acronym>SQL</acronym> SELECT corresponds to the
+ <quote>projection</quote> in relational algebra not to the
+ <quote>selection</quote> (see <xref linkend="rel-alg"
+ endterm="rel-alg"> for more details).
</para>
<para>
diff --git a/doc/src/sgml/start.sgml b/doc/src/sgml/start.sgml
index 5fff93e7d04..89abd3cf854 100644
--- a/doc/src/sgml/start.sgml
+++ b/doc/src/sgml/start.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.27 2002/11/11 20:14:04 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/start.sgml,v 1.28 2003/02/19 04:06:28 momjian Exp $
-->
<chapter id="tutorial-start">
@@ -242,7 +242,7 @@ createdb: database creation failed
</para>
<para>
- If you don't want to use your database anymore you can remove it.
+ If you do not want to use your database anymore you can remove it.
For example, if you are the owner (creator) of the database
<literal>mydb</literal>, you can destroy it using the following
command:
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index e0a330daeff..931b389cbdd 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -305,7 +305,7 @@ If only one candidate remains, use it; else continue to the next step.
<para>
If any input arguments are <quote>unknown</quote>, check the type
categories accepted at those argument positions by the remaining
-candidates. At each position, select the "string" category if any
+candidates. At each position, select the <quote>string</quote> category if any
candidate accepts that category (this bias towards string is appropriate
since an unknown-type literal does look like a string). Otherwise, if
all the remaining candidates accept the same type category, select that
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 62b7564f0fb..0ae9531f56a 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.64 2003/01/19 00:13:28 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.65 2003/02/19 04:06:28 momjian Exp $
-->
<chapter id="xfunc">
@@ -606,7 +606,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
The newer <quote>version 1</quote> calling convention is indicated by writing
a <literal>PG_FUNCTION_INFO_V1()</literal> macro call for the function,
as illustrated below. Lack of such a macro indicates an old-style
- ("version 0") function. The language name specified in <command>CREATE FUNCTION</command>
+ (<quote>version 0</quote>) function. The language name specified in <command>CREATE FUNCTION</command>
is <literal>C</literal> in either case. Old-style functions are now deprecated
because of portability problems and lack of functionality, but they
are still supported for compatibility reasons.
@@ -1380,7 +1380,7 @@ concat_text(PG_FUNCTION_ARGS)
zero, and a negative length requests that the remainder of the
value be returned. These routines provide more efficient access to
parts of large values in the case where they have storage type
- "external". (The storage type of a column can be specified using
+ <quote>external</quote>. (The storage type of a column can be specified using
<literal>ALTER TABLE <replaceable>tablename</replaceable> ALTER
COLUMN <replaceable>colname</replaceable> SET STORAGE
<replaceable>storagetype</replaceable></literal>. Storage type is one of
@@ -1583,7 +1583,7 @@ TupleTableSlot *TupleDescGetSlot(TupleDesc tupdesc)
HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values)
</programlisting>
can be used to build a <structname>HeapTuple</> given user data
- in C string form. "values" is an array of C strings, one for
+ in C string form. <quote>values</quote> is an array of C strings, one for
each attribute of the return tuple. Each C string should be in
the form expected by the input function of the attribute data
type. In order to return a null value for one of the attributes,
diff --git a/src/backend/catalog/index.c b/src/backend/catalog/index.c
index 5ccb70aee75..3533b24ca78 100644
--- a/src/backend/catalog/index.c
+++ b/src/backend/catalog/index.c
@@ -8,7 +8,7 @@
*
*
* IDENTIFICATION
- * $Header: /cvsroot/pgsql/src/backend/catalog/index.c,v 1.208 2002/12/15 16:17:38 tgl Exp $
+ * $Header: /cvsroot/pgsql/src/backend/catalog/index.c,v 1.209 2003/02/19 04:06:28 momjian Exp $
*
*
* INTERFACE ROUTINES
@@ -1894,8 +1894,8 @@ reindex_relation(Oid relid, bool force)
/*
* Ensure to hold an exclusive lock throughout the transaction. The
- * lock could be less intensive (in the non-overwrite path) but now
- * it's AccessExclusiveLock for simplicity.
+ * lock could be less intensive (in the non-overwrite path) but for
+ * now it's AccessExclusiveLock for simplicity.
*/
rel = heap_open(relid, AccessExclusiveLock);
--
GitLab