Skip to content

Commit b524cb3

Browse files
tglsfdctglsfdc
committed
Make an editorial pass over the reference pages.
1 parent cad0e82 commit b524cb3

26 files changed

+200
-145
lines changed

‎doc/src/sgml/maintenance.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.49 2005/10/21 19:39:08 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/maintenance.sgml,v 1.50 2005/11/01 21:09:49 tgl Exp $
33
-->
44

55
<chapter id="maintenance">
@@ -586,7 +586,8 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
586586

587587
<para>
588588
In some situations it is worthwhile to rebuild indexes periodically
589-
with the <command>REINDEX</> command.
589+
with the <xref linkend="sql-reindex" endterm="sql-reindex-title">
590+
command.
590591
</para>
591592

592593
<para>

‎doc/src/sgml/ref/alter_domain.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_domain.sgml,v 1.18 2005/10/13 22:44:51 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_domain.sgml,v 1.19 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -237,7 +237,8 @@ ALTER DOMAIN zipcode SET SCHEMA customers;
237237
<title>Compatibility</title>
238238

239239
<para>
240-
<command>ALTER DOMAIN</command> conforms with <acronym>SQL:2003</acronym>,
240+
<command>ALTER DOMAIN</command> conforms to the <acronym>SQL</acronym>
241+
standard,
241242
except for the <literal>OWNER</> and <literal>SET SCHEMA</> variants,
242243
which are <productname>PostgreSQL</productname> extensions.
243244
</para>

‎doc/src/sgml/ref/alter_function.sgml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_function.sgml,v 1.9 2005/10/13 22:44:51 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_function.sgml,v 1.10 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -149,8 +149,9 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
149149
<literal>CALLED ON NULL INPUT</literal> changes the function so
150150
that it will be invoked when some or all of its arguments are
151151
null. <literal>RETURNS NULL ON NULL INPUT</literal> or
152-
<literal>STRICT</literal> changes the function so that it
153-
always returns null if any of its arguments are null. See <xref
152+
<literal>STRICT</literal> changes the function so that it is not
153+
invoked if any of its arguments are null; instead, a null result
154+
is assumed automatically. See <xref
154155
linkend="sql-createfunction"> for more information.
155156
</para>
156157
</listitem>
@@ -164,8 +165,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
164165
<listitem>
165166
<para>
166167
Change the volatility of the function to the specified
167-
type. See <xref linkend="sql-createfunction"> for more
168-
information about function volatility.
168+
setting. See <xref linkend="sql-createfunction"> for details.
169169
</para>
170170
</listitem>
171171
</varlistentry>
@@ -233,7 +233,7 @@ ALTER FUNCTION sqrt(integer) SET SCHEMA maths;
233233
properties of a function to be modified, but does not provide the
234234
ability to rename a function, make a function a security definer,
235235
or change the owner, schema, or volatility of a function. The standard also
236-
requires the <literal>RESTRICT</> key word; it is optional in
236+
requires the <literal>RESTRICT</> key word, which is optional in
237237
<productname>PostgreSQL</>.
238238
</para>
239239
</refsect1>

‎doc/src/sgml/ref/alter_sequence.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_sequence.sgml,v 1.12 2005/10/15 20:12:33 neilc Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_sequence.sgml,v 1.13 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -215,7 +215,8 @@ ALTER SEQUENCE serial RESTART WITH 105;
215215
<title>Compatibility</title>
216216

217217
<para>
218-
<command>ALTER SEQUENCE</command> conforms with <acronym>SQL:2003</acronym>,
218+
<command>ALTER SEQUENCE</command> conforms to the <acronym>SQL</acronym>
219+
standard,
219220
except for the <literal>SET SCHEMA</literal> variant, which is a
220221
<productname>PostgreSQL</productname> extension.
221222
</para>

‎doc/src/sgml/ref/create_cast.sgml

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.21 2005/07/14 06:17:36 neilc Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/create_cast.sgml,v 1.22 2005/11/01 21:09:50 tgl Exp $ -->
22

33
<refentry id="SQL-CREATECAST">
44
<refmeta>
@@ -298,8 +298,9 @@ CREATE CAST (text AS int4) WITH FUNCTION int4(text);
298298
<title>Compatibility</title>
299299

300300
<para>
301-
The <command>CREATE CAST</command> command conforms to SQL:2003,
302-
except that SQL:2003 does not make provisions for binary-compatible
301+
The <command>CREATE CAST</command> command conforms to the
302+
<acronym>SQL</acronym> standard,
303+
except that SQL does not make provisions for binary-compatible
303304
types or extra arguments to implementation functions.
304305
<literal>AS IMPLICIT</> is a <productname>PostgreSQL</productname>
305306
extension, too.

‎doc/src/sgml/ref/create_domain.sgml

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.24 2005/09/23 02:01:35 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_domain.sgml,v 1.25 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -55,13 +55,17 @@ where <replaceable class="PARAMETER">constraint</replaceable> is:
5555
constraints individually.
5656
</para>
5757

58-
<note>
58+
<caution>
5959
<para>
60-
Keep in mind also that declaring a function result value as a domain
60+
At present, declaring a function result value as a domain
6161
is pretty dangerous, because none of the PLs enforce domain constraints
62-
on their results.
62+
on their results. You'll need to make sure that the function code itself
63+
respects the constraints. In <application>PL/pgSQL</>, one possible
64+
workaround is to explicitly cast the result value to the domain type
65+
when you return it. <application>PL/pgSQL</> does not enforce domain
66+
constraints for local variables within functions, either.
6367
</para>
64-
</note>
68+
</caution>
6569
</refsect1>
6670

6771
<refsect1>

‎doc/src/sgml/ref/create_function.sgml

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.66 2005/07/14 06:17:36 neilc Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_function.sgml,v 1.67 2005/11/01 21:09:50 tgl Exp $
33
-->
44

55
<refentry id="SQL-CREATEFUNCTION">
@@ -228,9 +228,9 @@ CREATE [ OR REPLACE ] FUNCTION
228228
change even within a single table scan, so no optimizations can be
229229
made. Relatively few database functions are volatile in this sense;
230230
some examples are <literal>random()</>, <literal>currval()</>,
231-
<literal>timeofday()</>. Note that any function that has side-effects
232-
must be classified volatile, even if its result is quite predictable,
233-
to prevent calls from being optimized away; an example is
231+
<literal>timeofday()</>. But note that any function that has
232+
side-effects must be classified volatile, even if its result is quite
233+
predictable, to prevent calls from being optimized away; an example is
234234
<literal>setval()</>.
235235
</para>
236236

@@ -279,9 +279,9 @@ CREATE [ OR REPLACE ] FUNCTION
279279
</para>
280280

281281
<para>
282-
The key word <literal>EXTERNAL</literal> is present for SQL
283-
conformance but is optional since, unlike in SQL, this feature
284-
does not only apply to external functions.
282+
The key word <literal>EXTERNAL</literal> is allowed for SQL
283+
conformance, but it is optional since, unlike in SQL, this feature
284+
applies to all functions not only external ones.
285285
</para>
286286
</listitem>
287287
</varlistentry>
@@ -478,7 +478,7 @@ SELECT * FROM dup(42);
478478
<title>Compatibility</title>
479479

480480
<para>
481-
A <command>CREATE FUNCTION</command> command is defined in SQL:2003.
481+
A <command>CREATE FUNCTION</command> command is defined in SQL:1999 and later.
482482
The <productname>PostgreSQL</productname> version is similar but
483483
not fully compatible. The attributes are not portable, neither are the
484484
different available languages.

‎doc/src/sgml/ref/create_sequence.sgml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.42 2004/11/27 21:27:07 petere Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.43 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -297,8 +297,8 @@ END;
297297
<title>Compatibility</title>
298298

299299
<para>
300-
<command>CREATE SEQUENCE</command> is is specified in <acronym>SQL:2003</acronym>.
301-
<productname>PostgreSQL</productname> conforms with the standard, with the following exceptions:
300+
<command>CREATE SEQUENCE</command> conforms to the <acronym>SQL</acronym>
301+
standard, with the following exceptions:
302302
<itemizedlist>
303303
<listitem><para>The standard's <literal>AS &lt;data type&gt;</literal> expression is not supported.</para></listitem>
304304
<listitem><para>Obtaining the next value is done using the <function>nextval()</> function instead of the standard's <command>NEXT VALUE FOR</command> expression.</para></listitem>

‎doc/src/sgml/ref/create_table.sgml

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.95 2005/10/31 18:13:52 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table.sgml,v 1.96 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -20,11 +20,12 @@ PostgreSQL documentation
2020

2121
<refsynopsisdiv>
2222
<synopsis>
23-
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable class="PARAMETER">table_name</replaceable> (
24-
[ <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ DEFAULT <replaceable>default_expr</> ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ]
23+
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable class="PARAMETER">table_name</replaceable> ( [
24+
{ <replaceable class="PARAMETER">column_name</replaceable> <replaceable class="PARAMETER">data_type</replaceable> [ DEFAULT <replaceable>default_expr</> ] [ <replaceable class="PARAMETER">column_constraint</replaceable> [ ... ] ]
2525
| <replaceable>table_constraint</replaceable>
26-
| LIKE <replaceable>parent_table</replaceable> [ { INCLUDING | EXCLUDING } DEFAULTS ] ] [, ... ]
27-
)
26+
| LIKE <replaceable>parent_table</replaceable> [ { INCLUDING | EXCLUDING } DEFAULTS ] }
27+
[, ... ]
28+
] )
2829
[ INHERITS ( <replaceable>parent_table</replaceable> [, ... ] ) ]
2930
[ WITH OIDS | WITHOUT OIDS ]
3031
[ ON COMMIT { PRESERVE ROWS | DELETE ROWS | DROP } ]
@@ -861,8 +862,8 @@ CREATE TABLE cinemas (
861862
<title id="SQL-CREATETABLE-compatibility-title">Compatibility</title>
862863

863864
<para>
864-
The <command>CREATE TABLE</command> command conforms to SQL-92 and
865-
to a subset of SQL:2003, with exceptions listed below.
865+
The <command>CREATE TABLE</command> command conforms to the
866+
<acronym>SQL</acronym> standard, with exceptions listed below.
866867
</para>
867868

868869
<refsect2>
@@ -940,8 +941,8 @@ CREATE TABLE cinemas (
940941
<para>
941942
Multiple inheritance via the <literal>INHERITS</literal> clause is
942943
a <productname>PostgreSQL</productname> language extension.
943-
SQL:2003 defines single inheritance using a
944-
different syntax and different semantics. SQL:2003-style
944+
SQL:1999 and later define single inheritance using a
945+
different syntax and different semantics. SQL:1999-style
945946
inheritance is not yet supported by
946947
<productname>PostgreSQL</productname>.
947948
</para>

‎doc/src/sgml/ref/create_table_as.sgml

Lines changed: 30 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.30 2005/10/15 20:12:33 neilc Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/create_table_as.sgml,v 1.31 2005/11/01 21:09:50 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -20,7 +20,8 @@ PostgreSQL documentation
2020

2121
<refsynopsisdiv>
2222
<synopsis>
23-
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable> [ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
23+
CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name</replaceable>
24+
[ (<replaceable>column_name</replaceable> [, ...] ) ] [ [ WITH | WITHOUT ] OIDS ]
2425
AS <replaceable>query</replaceable>
2526
</synopsis>
2627
</refsynopsisdiv>
@@ -143,17 +144,17 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } ] TABLE <replaceable>table_name
143144
<para>
144145
Prior to <productname>PostgreSQL</productname> 8.0, <command>CREATE
145146
TABLE AS</command> always included OIDs in the table it
146-
produced. As of <productname>PostgreSQL</productname> 8.0,
147+
created. As of <productname>PostgreSQL</productname> 8.0,
147148
the <command>CREATE TABLE AS</command> command allows the user to
148149
explicitly specify whether OIDs should be included. If the
149150
presence of OIDs is not explicitly specified,
150151
the <xref linkend="guc-default-with-oids"> configuration variable is
151-
used. While this variable currently defaults to true, the default
152-
value may be changed in the future. Therefore, applications that
152+
used. As of <productname>PostgreSQL</productname> 8.1,
153+
this variable is false by default, so the default behavior is not
154+
identical to pre-8.0 releases. Applications that
153155
require OIDs in the table created by <command>CREATE TABLE
154-
AS</command> should explicitly specify <literal>WITH
155-
OIDS</literal> to ensure compatibility with future versions
156-
of <productname>PostgreSQL</productname>.
156+
AS</command> should explicitly specify <literal>WITH OIDS</literal>
157+
to ensure proper behavior.
157158
</para>
158159
</refsect1>
159160

@@ -175,10 +176,8 @@ CREATE TABLE films_recent AS
175176
<title>Compatibility</title>
176177

177178
<para>
178-
<command>CREATE TABLE AS</command> is specified by the SQL:2003
179-
standard. There are some small differences between the definition
180-
of the command in SQL:2003 and its implementation in
181-
<productname>PostgreSQL</>:
179+
<command>CREATE TABLE AS</command> conforms to the <acronym>SQL</acronym>
180+
standard, with the following exceptions:
182181

183182
<itemizedlist spacing="compact">
184183
<listitem>
@@ -198,8 +197,26 @@ CREATE TABLE films_recent AS
198197

199198
<listitem>
200199
<para>
201-
The standard defines a <literal>WITH DATA</literal> clause;
200+
The standard defines a <literal>WITH [ NO ] DATA</literal> clause;
202201
this is not currently implemented by <productname>PostgreSQL</>.
202+
The behavior provided by <productname>PostgreSQL</> is equivalent
203+
to the standard's <literal>WITH DATA</literal> case.
204+
</para>
205+
</listitem>
206+
207+
<listitem>
208+
<para>
209+
<literal>WITH/WITHOUT OIDS</> is a <productname>PostgreSQL</>
210+
extension.
211+
</para>
212+
</listitem>
213+
214+
<listitem>
215+
<para>
216+
<productname>PostgreSQL</> handles temporary tables in a way
217+
rather different from the standard; see
218+
<xref linkend="sql-createtable" endterm="sql-createtable-title">
219+
for details.
203220
</para>
204221
</listitem>
205222
</itemizedlist>

0 commit comments

Comments
 (0)