sharpetronics/PostgreSQL
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-06-03 00:02:26 -04:00
Code Issues Projects Releases Wiki Activity

Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs.

Browse Source 
Use xreflabel attributes instead of endterm attributes to control the
appearance of links to subsections of SQL command reference pages.
This is simpler, it matches what we do elsewhere (e.g. for GUC variables),
and it doesn't draw "Unresolved ID reference" warnings from the PDF
toolchain.

Fix some places where the text was absolutely dependent on an <xref>
rendering exactly so, by using a <link> around the required text
instead.  At least one of those spots had already been turned into
bad grammar by subsequent changes, and the whole idea is just too
fragile for my taste.  <xref> does NOT have fixed output, don't write
as if it does.

Consistently include a page-level link in cross-man-page references,
because otherwise they are useless/nonsensical in man-page output.
Likewise, be consistent about mentioning "below" or "above" in same-page
references; we were doing that in about 90% of the cases, but now it's
100%.

Also get rid of another nonfunctional-in-PDF idea, of making
cross-references to functions by sticking ID tags on <row> constructs.
We can put the IDs on <indexterm>s instead --- which is probably not any
more sensible in abstract terms, but it works where the other doesn't.
(There is talk of attaching cross-reference IDs to most or all of
the docs' function descriptions, but for now I just fixed the two
that exist.)

Discussion: https://postgr.es/m/14480.1589154358@sss.pgh.pa.us
This commit is contained in:
Tom Lane 2020-05-11 14:15:49 -04:00
parent 624686abcf
commit 60c90c16c1
26 changed files with 167 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/src/sgml/config.sgml
View File

@ -7301,8 +7301,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
These settings control the behavior of the <firstterm>autovacuum</firstterm> These settings control the behavior of the <firstterm>autovacuum</firstterm>
feature. Refer to <xref linkend="autovacuum"/> for more information. feature. Refer to <xref linkend="autovacuum"/> for more information.
Note that many of these settings can be overridden on a per-table Note that many of these settings can be overridden on a per-table
basis; see <xref linkend="sql-createtable-storage-parameters" basis; see <xref linkend="sql-createtable-storage-parameters"/>.
endterm="sql-createtable-storage-parameters-title"/>.
</para> </para>
<variablelist> <variablelist>

8
doc/src/sgml/func.sgml
View File

@ -4355,9 +4355,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
</para></entry> </para></entry>
</row> </row>
<row id="function-encode"> <row>
<entry role="func_table_entry"><para role="func_signature"> <entry role="func_table_entry"><para role="func_signature">
<indexterm> <indexterm id="function-encode">
<primary>encode</primary> <primary>encode</primary>
</indexterm> </indexterm>
<function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>, <function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>,
@ -4377,9 +4377,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
</para></entry> </para></entry>
</row> </row>
<row id="function-decode"> <row>
<entry role="func_table_entry"><para role="func_signature"> <entry role="func_table_entry"><para role="func_signature">
<indexterm> <indexterm id="function-decode">
<primary>decode</primary> <primary>decode</primary>
</indexterm> </indexterm>
<function>decode</function> ( <parameter>string</parameter> <type>text</type>, <function>decode</function> ( <parameter>string</parameter> <type>text</type>,

3
doc/src/sgml/indices.sgml
View File

@ -98,8 +98,7 @@ CREATE INDEX test1_id_index ON test1 (id);
In production environments this is often unacceptable. In production environments this is often unacceptable.
It is possible to allow writes to occur in parallel with index It is possible to allow writes to occur in parallel with index
creation, but there are several caveats to be aware of &mdash; creation, but there are several caveats to be aware of &mdash;
for more information see <xref linkend="sql-createindex-concurrently" for more information see <xref linkend="sql-createindex-concurrently"/>.
endterm="sql-createindex-concurrently-title"/>.
</para> </para>
<para> <para>

3
doc/src/sgml/maintenance.sgml
View File

@ -827,8 +827,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
The default thresholds and scale factors are taken from The default thresholds and scale factors are taken from
<filename>postgresql.conf</filename>, but it is possible to override them <filename>postgresql.conf</filename>, but it is possible to override them
(and many other autovacuum control parameters) on a per-table basis; see (and many other autovacuum control parameters) on a per-table basis; see
<xref linkend="sql-createtable-storage-parameters" <xref linkend="sql-createtable-storage-parameters"/> for more information.
endterm="sql-createtable-storage-parameters-title"/> for more information.
If a setting has been changed via a table's storage parameters, that value If a setting has been changed via a table's storage parameters, that value
is used when processing that table; otherwise the global settings are is used when processing that table; otherwise the global settings are
used. See <xref linkend="runtime-config-autovacuum"/> for more details on used. See <xref linkend="runtime-config-autovacuum"/> for more details on

8
doc/src/sgml/queries.sgml
View File

@ -110,7 +110,7 @@ SELECT random();
<title>The <literal>FROM</literal> Clause</title> <title>The <literal>FROM</literal> Clause</title>
<para> <para>
The <xref linkend="sql-from" endterm="sql-from-title"/> derives a The <link linkend="sql-from"><literal>FROM</literal></link> clause derives a
table from one or more other tables given in a comma-separated table from one or more other tables given in a comma-separated
table reference list. table reference list.
<synopsis> <synopsis>
@ -907,8 +907,8 @@ WHERE pname IS NULL;
</indexterm> </indexterm>
<para> <para>
The syntax of the <xref linkend="sql-where" The syntax of the <link linkend="sql-where"><literal>WHERE</literal></link>
endterm="sql-where-title"/> is clause is
<synopsis> <synopsis>
WHERE <replaceable>search_condition</replaceable> WHERE <replaceable>search_condition</replaceable>
</synopsis> </synopsis>
@ -1014,7 +1014,7 @@ SELECT <replaceable>select_list</replaceable>
</synopsis> </synopsis>
<para> <para>
The <xref linkend="sql-groupby" endterm="sql-groupby-title"/> is The <link linkend="sql-groupby"><literal>GROUP BY</literal></link> clause is
used to group together those rows in a table that have the same used to group together those rows in a table that have the same
values in all the columns listed. The order in which the columns values in all the columns listed. The order in which the columns
are listed does not matter. The effect is to combine each set are listed does not matter. The effect is to combine each set

7
doc/src/sgml/ref/alter_collation.sgml
View File

@ -93,16 +93,15 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
<listitem> <listitem>
<para> <para>
Update the collation's version. Update the collation's version.
See <xref linkend="sql-altercollation-notes" See <xref linkend="sql-altercollation-notes"/> below.
endterm="sql-altercollation-notes-title"/> below.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
</refsect1> </refsect1>
<refsect1 id="sql-altercollation-notes"> <refsect1 id="sql-altercollation-notes" xreflabel="Notes">
<title id="sql-altercollation-notes-title">Notes</title> <title>Notes</title>
<para> <para>
When using collations provided by the ICU library, the ICU-specific version When using collations provided by the ICU library, the ICU-specific version

16
doc/src/sgml/ref/alter_table.sgml
View File

@ -405,8 +405,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
database will not assume that the constraint holds for all rows in database will not assume that the constraint holds for all rows in
the table, until it is validated by using the <literal>VALIDATE the table, until it is validated by using the <literal>VALIDATE
CONSTRAINT</literal> option. CONSTRAINT</literal> option.
See <xref linkend="sql-altertable-notes" See <xref linkend="sql-altertable-notes"/> below for more information
endterm="sql-altertable-notes-title"/> below for more information
about using the <literal>NOT VALID</literal> option. about using the <literal>NOT VALID</literal> option.
</para> </para>
@ -504,9 +503,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
previously created as <literal>NOT VALID</literal>, by scanning the previously created as <literal>NOT VALID</literal>, by scanning the
table to ensure there are no rows for which the constraint is not table to ensure there are no rows for which the constraint is not
satisfied. Nothing happens if the constraint is already marked valid. satisfied. Nothing happens if the constraint is already marked valid.
(See <xref linkend="sql-altertable-notes" (See <xref linkend="sql-altertable-notes"/> below for an explanation
endterm="sql-altertable-notes-title"/> below for an explanation of the of the usefulness of this command.)
usefulness of this command.)
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -708,8 +706,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<listitem> <listitem>
<para> <para>
This form changes one or more storage parameters for the table. See This form changes one or more storage parameters for the table. See
<xref linkend="sql-createtable-storage-parameters" <xref linkend="sql-createtable-storage-parameters"/> in the
endterm="sql-createtable-storage-parameters-title"/> <xref linkend="sql-createtable"/> documentation
for details on the available parameters. Note that the table contents for details on the available parameters. Note that the table contents
will not be modified immediately by this command; depending on the will not be modified immediately by this command; depending on the
parameter you might need to rewrite the table to get the desired effects. parameter you might need to rewrite the table to get the desired effects.
@ -1210,8 +1208,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</variablelist> </variablelist>
</refsect1> </refsect1>
<refsect1 id="sql-altertable-notes"> <refsect1 id="sql-altertable-notes" xreflabel="Notes">
<title id="sql-altertable-notes-title">Notes</title> <title>Notes</title>
<para> <para>
The key word <literal>COLUMN</literal> is noise and can be omitted. The key word <literal>COLUMN</literal> is noise and can be omitted.

8
doc/src/sgml/ref/create_aggregate.sgml
View File

@ -434,8 +434,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
This option specifies whether the final function is a pure function This option specifies whether the final function is a pure function
that does not modify its arguments. <literal>READ_ONLY</literal> indicates that does not modify its arguments. <literal>READ_ONLY</literal> indicates
it does not; the other two values indicate that it may change the it does not; the other two values indicate that it may change the
transition state value. See <xref linkend="sql-createaggregate-notes" transition state value. See <xref linkend="sql-createaggregate-notes"/>
endterm="sql-createaggregate-notes-title"/> below for more detail. The below for more detail. The
default is <literal>READ_ONLY</literal>, except for ordered-set aggregates, default is <literal>READ_ONLY</literal>, except for ordered-set aggregates,
for which the default is <literal>READ_WRITE</literal>. for which the default is <literal>READ_WRITE</literal>.
</para> </para>
@ -664,8 +664,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
</para> </para>
</refsect1> </refsect1>
<refsect1 id="sql-createaggregate-notes"> <refsect1 id="sql-createaggregate-notes" xreflabel="Notes">
<title id="sql-createaggregate-notes-title">Notes</title> <title>Notes</title>
<para> <para>
In parameters that specify support function names, you can write In parameters that specify support function names, you can write

15
doc/src/sgml/ref/create_index.sgml
View File

@ -126,8 +126,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
updates, or deletes on the table; whereas a standard index build updates, or deletes on the table; whereas a standard index build
locks out writes (but not reads) on the table until it's done. locks out writes (but not reads) on the table until it's done.
There are several caveats to be aware of when using this option There are several caveats to be aware of when using this option
&mdash; see <xref linkend="sql-createindex-concurrently" &mdash; see <xref linkend="sql-createindex-concurrently"/> below.
endterm="sql-createindex-concurrently-title"/>.
</para> </para>
<para> <para>
For temporary tables, <command>CREATE INDEX</command> is always For temporary tables, <command>CREATE INDEX</command> is always
@ -337,7 +336,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
<listitem> <listitem>
<para> <para>
The name of an index-method-specific storage parameter. See The name of an index-method-specific storage parameter. See
<xref linkend="sql-createindex-storage-parameters" endterm="sql-createindex-storage-parameters-title"/> <xref linkend="sql-createindex-storage-parameters"/> below
for details. for details.
</para> </para>
</listitem> </listitem>
@ -366,8 +365,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
</variablelist> </variablelist>
<refsect2 id="sql-createindex-storage-parameters"> <refsect2 id="sql-createindex-storage-parameters" xreflabel="Index Storage Parameters">
<title id="sql-createindex-storage-parameters-title">Index Storage Parameters</title> <title>Index Storage Parameters</title>
<para> <para>
The optional <literal>WITH</literal> clause specifies <firstterm>storage The optional <literal>WITH</literal> clause specifies <firstterm>storage
@ -559,8 +558,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
</variablelist> </variablelist>
</refsect2> </refsect2>
<refsect2 id="sql-createindex-concurrently"> <refsect2 id="sql-createindex-concurrently" xreflabel="Building Indexes Concurrently">
<title id="sql-createindex-concurrently-title">Building Indexes Concurrently</title> <title>Building Indexes Concurrently</title>
<indexterm zone="sql-createindex-concurrently"> <indexterm zone="sql-createindex-concurrently">
<primary>index</primary> <primary>index</primary>
@ -688,7 +687,7 @@ Indexes:
</para> </para>
<para> <para>
An <firstterm>operator class</firstterm> with its optional parameters An <firstterm>operator class</firstterm> with optional parameters
can be specified for each column of an index. can be specified for each column of an index.
The operator class identifies the operators to be The operator class identifies the operators to be
used by the index for that column. For example, a B-tree index on used by the index for that column. For example, a B-tree index on

5
doc/src/sgml/ref/create_materialized_view.sgml
View File

@ -106,8 +106,9 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
<listitem> <listitem>
<para> <para>
This clause specifies optional storage parameters for the new This clause specifies optional storage parameters for the new
materialized view; see <xref linkend="sql-createtable-storage-parameters" materialized view; see
endterm="sql-createtable-storage-parameters-title"/> for more <xref linkend="sql-createtable-storage-parameters"/> in the
<xref linkend="sql-createtable"/> documentation for more
information. All parameters supported for <literal>CREATE information. All parameters supported for <literal>CREATE
TABLE</literal> are also supported for <literal>CREATE MATERIALIZED TABLE</literal> are also supported for <literal>CREATE MATERIALIZED
VIEW</literal>. VIEW</literal>.

14
doc/src/sgml/ref/create_table.sgml
View File

@ -192,8 +192,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
can be written before <literal>TEMPORARY</literal> or <literal>TEMP</literal>. can be written before <literal>TEMPORARY</literal> or <literal>TEMP</literal>.
This presently makes no difference in <productname>PostgreSQL</productname> This presently makes no difference in <productname>PostgreSQL</productname>
and is deprecated; see and is deprecated; see
<xref linkend="sql-createtable-compatibility" <xref linkend="sql-createtable-compatibility"/> below.
endterm="sql-createtable-compatibility-title"/>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1201,8 +1200,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
<listitem> <listitem>
<para> <para>
This clause specifies optional storage parameters for a table or index; This clause specifies optional storage parameters for a table or index;
see <xref linkend="sql-createtable-storage-parameters" see <xref linkend="sql-createtable-storage-parameters"/> below for more
endterm="sql-createtable-storage-parameters-title"/> for more
information. For backward-compatibility the <literal>WITH</literal> information. For backward-compatibility the <literal>WITH</literal>
clause for a table can also include <literal>OIDS=FALSE</literal> to clause for a table can also include <literal>OIDS=FALSE</literal> to
specify that rows of the new table should not contain OIDs (object specify that rows of the new table should not contain OIDs (object
@ -1302,8 +1300,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
</variablelist> </variablelist>
<refsect2 id="sql-createtable-storage-parameters"> <refsect2 id="sql-createtable-storage-parameters" xreflabel="Storage Parameters">
<title id="sql-createtable-storage-parameters-title">Storage Parameters</title> <title>Storage Parameters</title>
<indexterm zone="sql-createtable-storage-parameters"> <indexterm zone="sql-createtable-storage-parameters">
<primary>storage parameters</primary> <primary>storage parameters</primary>
@ -2063,8 +2061,8 @@ CREATE TABLE cities_partdef
</programlisting></para> </programlisting></para>
</refsect1> </refsect1>
<refsect1 id="sql-createtable-compatibility"> <refsect1 id="sql-createtable-compatibility" xreflabel="Compatibility">
<title id="sql-createtable-compatibility-title">Compatibility</title> <title>Compatibility</title>
<para> <para>
The <command>CREATE TABLE</command> command conforms to the The <command>CREATE TABLE</command> command conforms to the

4
doc/src/sgml/ref/create_table_as.sgml
View File

@ -140,8 +140,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
<listitem> <listitem>
<para> <para>
This clause specifies optional storage parameters for the new table; This clause specifies optional storage parameters for the new table;
see <xref linkend="sql-createtable-storage-parameters" see <xref linkend="sql-createtable-storage-parameters"/> in the
endterm="sql-createtable-storage-parameters-title"/> for more <xref linkend="sql-createtable"/> documentation for more
information. For backward-compatibility the <literal>WITH</literal> information. For backward-compatibility the <literal>WITH</literal>
clause for a table can also include <literal>OIDS=FALSE</literal> to clause for a table can also include <literal>OIDS=FALSE</literal> to
specify that rows of the new table should contain no OIDs (object specify that rows of the new table should contain no OIDs (object

8
doc/src/sgml/ref/declare.sgml
View File

@ -99,8 +99,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
<literal>NO SCROLL</literal> specifies that the cursor cannot be <literal>NO SCROLL</literal> specifies that the cursor cannot be
used to retrieve rows in a nonsequential fashion. The default is to used to retrieve rows in a nonsequential fashion. The default is to
allow scrolling in some cases; this is not the same as specifying allow scrolling in some cases; this is not the same as specifying
<literal>SCROLL</literal>. See <xref linkend="sql-declare-notes" <literal>SCROLL</literal>. See <xref linkend="sql-declare-notes"/>
endterm="sql-declare-notes-title"/> for details. below for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -139,8 +139,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
</para> </para>
</refsect1> </refsect1>
<refsect1 id="sql-declare-notes"> <refsect1 id="sql-declare-notes" xreflabel="Notes">
<title id="sql-declare-notes-title">Notes</title> <title>Notes</title>
<para> <para>
Normal cursors return data in text format, the same as a Normal cursors return data in text format, the same as a

4
doc/src/sgml/ref/delete.sgml
View File

@ -122,8 +122,8 @@ DELETE FROM [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ *
<para> <para>
A table expression allowing columns from other tables to appear A table expression allowing columns from other tables to appear
in the <literal>WHERE</literal> condition. This uses the same in the <literal>WHERE</literal> condition. This uses the same
syntax as the <xref linkend="sql-from" endterm="sql-from-title"/> syntax as the <link linkend="sql-from"><literal>FROM</literal></link>
of a <command>SELECT</command> statement; for example, an alias clause of a <command>SELECT</command> statement; for example, an alias
for the table name can be specified. Do not repeat the target for the table name can be specified. Do not repeat the target
table as a <replaceable class="parameter">from_item</replaceable> table as a <replaceable class="parameter">from_item</replaceable>
unless you wish to set up a self-join (in which case it must appear unless you wish to set up a self-join (in which case it must appear

5
doc/src/sgml/ref/execute.sgml
View File

@ -94,9 +94,8 @@ EXECUTE <replaceable class="parameter">name</replaceable> [ ( <replaceable class
<refsect1> <refsect1>
<title>Examples</title> <title>Examples</title>
<para> <para>
Examples are given in the <xref linkend="sql-prepare-examples" Examples are given in <xref linkend="sql-prepare-examples"/>
endterm="sql-prepare-examples-title"/> section of the <xref in the <xref linkend="sql-prepare"/> documentation.
linkend="sql-prepare"/> documentation.
</para> </para>
</refsect1> </refsect1>

11
doc/src/sgml/ref/insert.sgml
View File

@ -77,8 +77,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
<para> <para>
<literal>ON CONFLICT</literal> can be used to specify an alternative <literal>ON CONFLICT</literal> can be used to specify an alternative
action to raising a unique constraint or exclusion constraint action to raising a unique constraint or exclusion constraint
violation error. (See <xref linkend="sql-on-conflict" violation error. (See <xref linkend="sql-on-conflict"/> below.)
endterm="sql-on-conflict-title"/> below.)
</para> </para>
<para> <para>
@ -128,8 +127,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
<refsect1> <refsect1>
<title>Parameters</title> <title>Parameters</title>
<refsect2 id="sql-inserting-params"> <refsect2>
<title id="sql-inserting-params-title">Inserting</title> <title>Inserting</title>
<para> <para>
This section covers parameters that may be used when only This section covers parameters that may be used when only
@ -315,8 +314,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
</variablelist> </variablelist>
</refsect2> </refsect2>
<refsect2 id="sql-on-conflict"> <refsect2 id="sql-on-conflict" xreflabel="ON CONFLICT Clause">
<title id="sql-on-conflict-title"><literal>ON CONFLICT</literal> Clause</title> <title><literal>ON CONFLICT</literal> Clause</title>
<indexterm zone="sql-insert"> <indexterm zone="sql-insert">
<primary>UPSERT</primary> <primary>UPSERT</primary>
</indexterm> </indexterm>

5
doc/src/sgml/ref/lock.sgml
View File

@ -202,9 +202,8 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ]
<command>LOCK TABLE</command> is concerned, differing only in the rules <command>LOCK TABLE</command> is concerned, differing only in the rules
about which modes conflict with which. For information on how to about which modes conflict with which. For information on how to
acquire an actual row-level lock, see <xref linkend="locking-rows"/> acquire an actual row-level lock, see <xref linkend="locking-rows"/>
and the <xref linkend="sql-for-update-share" and <xref linkend="sql-for-update-share"/>
endterm="sql-for-update-share-title"/> in the <command>SELECT</command> in the <xref linkend="sql-select"/> documentation.
reference documentation.
</para> </para>
</refsect1> </refsect1>

25
doc/src/sgml/ref/pg_dump.sgml
View File

@ -387,12 +387,12 @@ PostgreSQL documentation
selected by writing multiple <option>-n</option> switches. The selected by writing multiple <option>-n</option> switches. The
<replaceable class="parameter">pattern</replaceable> parameter is <replaceable class="parameter">pattern</replaceable> parameter is
interpreted as a pattern according to the same rules used by interpreted as a pattern according to the same rules used by
<application>psql</application>'s <literal>\d</literal> commands (see <xref <application>psql</application>'s <literal>\d</literal> commands
linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>), (see <xref linkend="app-psql-patterns"/> below),
so multiple schemas can also be selected by writing wildcard characters so multiple schemas can also be selected by writing wildcard characters
in the pattern. When using wildcards, be careful to quote the pattern in the pattern. When using wildcards, be careful to quote the pattern
if needed to prevent the shell from expanding the wildcards; see if needed to prevent the shell from expanding the wildcards; see
<xref linkend="pg-dump-examples" endterm="pg-dump-examples-title"/>. <xref linkend="pg-dump-examples"/> below.
</para> </para>
<note> <note>
@ -524,12 +524,12 @@ PostgreSQL documentation
can be selected by writing multiple <option>-t</option> switches. The can be selected by writing multiple <option>-t</option> switches. The
<replaceable class="parameter">pattern</replaceable> parameter is <replaceable class="parameter">pattern</replaceable> parameter is
interpreted as a pattern according to the same rules used by interpreted as a pattern according to the same rules used by
<application>psql</application>'s <literal>\d</literal> commands (see <xref <application>psql</application>'s <literal>\d</literal> commands
linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>), (see <xref linkend="app-psql-patterns"/> below),
so multiple tables can also be selected by writing wildcard characters so multiple tables can also be selected by writing wildcard characters
in the pattern. When using wildcards, be careful to quote the pattern in the pattern. When using wildcards, be careful to quote the pattern
if needed to prevent the shell from expanding the wildcards; see if needed to prevent the shell from expanding the wildcards; see
<xref linkend="pg-dump-examples" endterm="pg-dump-examples-title"/>. <xref linkend="pg-dump-examples"/> below.
</para> </para>
<para> <para>
@ -777,12 +777,12 @@ PostgreSQL documentation
<option>--include-foreign-data</option> switches. <option>--include-foreign-data</option> switches.
Also, the <replaceable class="parameter">foreignserver</replaceable> parameter is Also, the <replaceable class="parameter">foreignserver</replaceable> parameter is
interpreted as a pattern according to the same rules used by interpreted as a pattern according to the same rules used by
<application>psql</application>'s <literal>\d</literal> commands (see <xref <application>psql</application>'s <literal>\d</literal> commands
linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>), (see <xref linkend="app-psql-patterns"/> below),
so multiple foreign servers can also be selected by writing wildcard characters so multiple foreign servers can also be selected by writing wildcard characters
in the pattern. When using wildcards, be careful to quote the pattern in the pattern. When using wildcards, be careful to quote the pattern
if needed to prevent the shell from expanding the wildcards; see if needed to prevent the shell from expanding the wildcards; see
<xref linkend="pg-dump-examples" endterm="pg-dump-examples-title"/>. <xref linkend="pg-dump-examples"/> below.
The only exception is that an empty pattern is disallowed. The only exception is that an empty pattern is disallowed.
</para> </para>
@ -1367,8 +1367,8 @@ CREATE DATABASE foo WITH TEMPLATE template0;
</para> </para>
</refsect1> </refsect1>
<refsect1 id="pg-dump-examples"> <refsect1 id="pg-dump-examples" xreflabel="Examples">
<title id="pg-dump-examples-title">Examples</title> <title>Examples</title>
<para> <para>
To dump a database called <literal>mydb</literal> into a SQL-script file: To dump a database called <literal>mydb</literal> into a SQL-script file:
@ -1477,8 +1477,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
<para> <para>
To specify an upper-case or mixed-case name in <option>-t</option> and related To specify an upper-case or mixed-case name in <option>-t</option> and related
switches, you need to double-quote the name; else it will be folded to switches, you need to double-quote the name; else it will be folded to
lower case (see <xref lower case (see <xref linkend="app-psql-patterns"/> below). But
linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>). But
double quotes are special to the shell, so in turn they must be quoted. double quotes are special to the shell, so in turn they must be quoted.
Thus, to dump a single table with a mixed-case name, you need something Thus, to dump a single table with a mixed-case name, you need something
like like

3
doc/src/sgml/ref/pg_dumpall.sgml
View File

@ -310,8 +310,7 @@ PostgreSQL documentation
<replaceable class="parameter">pattern</replaceable> parameter is <replaceable class="parameter">pattern</replaceable> parameter is
interpreted as a pattern according to the same rules used by interpreted as a pattern according to the same rules used by
<application>psql</application>'s <literal>\d</literal> <application>psql</application>'s <literal>\d</literal>
commands (see <xref commands (see <xref linkend="app-psql-patterns"/> below),
linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
so multiple databases can also be excluded by writing wildcard so multiple databases can also be excluded by writing wildcard
characters in the pattern. When using wildcards, be careful to characters in the pattern. When using wildcards, be careful to
quote the pattern if needed to prevent shell wildcard expansion. quote the pattern if needed to prevent shell wildcard expansion.

7
doc/src/sgml/ref/postgres-ref.sgml
View File

@ -530,8 +530,7 @@ PostgreSQL documentation
<para> <para>
The following options only apply to the single-user mode The following options only apply to the single-user mode
(see <xref linkend="app-postgres-single-user" (see <xref linkend="app-postgres-single-user"/> below).
endterm="app-postgres-single-user-title"/>).
</para> </para>
<variablelist> <variablelist>
@ -753,8 +752,8 @@ PostgreSQL documentation
</para> </para>
</refsect1> </refsect1>
<refsect1 id="app-postgres-single-user"> <refsect1 id="app-postgres-single-user" xreflabel="Single-User Mode">
<title id="app-postgres-single-user-title">Single-User Mode</title> <title>Single-User Mode</title>
<para> <para>
To start a single-user mode server, use a command like To start a single-user mode server, use a command like

4
doc/src/sgml/ref/prepare.sgml
View File

@ -208,8 +208,8 @@ EXPLAIN EXECUTE <replaceable>name</replaceable>(<replaceable>parameter_values</r
</para> </para>
</refsect1> </refsect1>
<refsect1 id="sql-prepare-examples"> <refsect1 id="sql-prepare-examples" xreflabel="Examples">
<title id="sql-prepare-examples-title">Examples</title> <title>Examples</title>
<para> <para>
Create a prepared statement for an <command>INSERT</command> Create a prepared statement for an <command>INSERT</command>
statement, and then execute it: statement, and then execute it:

67
doc/src/sgml/ref/psql-ref.sgml
View File

@ -809,7 +809,7 @@ testdb=&gt;
If an unquoted colon (<literal>:</literal>) followed by a If an unquoted colon (<literal>:</literal>) followed by a
<application>psql</application> variable name appears within an argument, it is <application>psql</application> variable name appears within an argument, it is
replaced by the variable's value, as described in <xref replaced by the variable's value, as described in <xref
linkend="app-psql-interpolation" endterm="app-psql-interpolation-title"/>. linkend="app-psql-interpolation"/> below.
The forms <literal>:'<replaceable>variable_name</replaceable>'</literal> and The forms <literal>:'<replaceable>variable_name</replaceable>'</literal> and
<literal>:"<replaceable>variable_name</replaceable>"</literal> described there <literal>:"<replaceable>variable_name</replaceable>"</literal> described there
work as well. work as well.
@ -1163,8 +1163,7 @@ testdb=&gt;
also shown. For foreign tables, the associated foreign also shown. For foreign tables, the associated foreign
server is shown as well. server is shown as well.
(<quote>Matching the pattern</quote> is defined in (<quote>Matching the pattern</quote> is defined in
<xref linkend="app-psql-patterns" endterm="app-psql-patterns-title"/> <xref linkend="app-psql-patterns"/> below.)
below.)
</para> </para>
<para> <para>
@ -1946,9 +1945,8 @@ testdb=&gt;
<tip> <tip>
<para> <para>
See under <xref linkend="app-psql-environment" See <xref linkend="app-psql-environment"/>, below, for how to
endterm="app-psql-environment-title"/> for how to configure and configure and customize your editor.
customize your editor.
</para> </para>
</tip> </tip>
</listitem> </listitem>
@ -2022,9 +2020,8 @@ Tue Oct 26 21:40:57 CEST 1999
<tip> <tip>
<para> <para>
See under <xref linkend="app-psql-environment" See <xref linkend="app-psql-environment"/>, below, for how to
endterm="app-psql-environment-title"/> for how to configure and configure and customize your editor.
customize your editor.
</para> </para>
</tip> </tip>
</listitem> </listitem>
@ -2230,8 +2227,8 @@ CREATE INDEX
<listitem> <listitem>
<para> <para>
Sends the current query buffer to the server and stores the Sends the current query buffer to the server and stores the
query's output into <application>psql</application> variables (see <xref query's output into <application>psql</application> variables
linkend="app-psql-variables" endterm="app-psql-variables-title"/>). (see <xref linkend="app-psql-variables"/> below).
The query to be executed must return exactly one row. Each column of The query to be executed must return exactly one row. Each column of
the row is stored into a separate variable, named the same as the the row is stored into a separate variable, named the same as the
column. For example: column. For example:
@ -3078,8 +3075,7 @@ lo_import 152801
<para> <para>
Illustrations of how these different formats look can be seen in Illustrations of how these different formats look can be seen in
the <xref linkend="app-psql-examples" <xref linkend="app-psql-examples"/>, below.
endterm="app-psql-examples-title"/> section.
</para> </para>
<tip> <tip>
@ -3163,9 +3159,7 @@ lo_import 152801
<para> <para>
Valid variable names can contain letters, digits, and Valid variable names can contain letters, digits, and
underscores. See the section <xref underscores. See <xref linkend="app-psql-variables"/> below for details.
linkend="app-psql-variables"
endterm="app-psql-variables-title"/> below for details.
Variable names are case-sensitive. Variable names are case-sensitive.
</para> </para>
@ -3173,8 +3167,7 @@ lo_import 152801
Certain variables are special, in that they Certain variables are special, in that they
control <application>psql</application>'s behavior or are control <application>psql</application>'s behavior or are
automatically set to reflect connection state. These variables are automatically set to reflect connection state. These variables are
documented in <xref linkend="app-psql-variables" documented in <xref linkend="app-psql-variables"/>, below.
endterm="app-psql-variables-title"/>, below.
</para> </para>
<note> <note>
@ -3318,8 +3311,7 @@ testdb=&gt; <userinput>\setenv LESS -imx4F</userinput>
Most variables that control <application>psql</application>'s behavior Most variables that control <application>psql</application>'s behavior
cannot be unset; instead, an <literal>\unset</literal> command is interpreted cannot be unset; instead, an <literal>\unset</literal> command is interpreted
as setting them to their default values. as setting them to their default values.
See <xref linkend="app-psql-variables" See <xref linkend="app-psql-variables"/> below.
endterm="app-psql-variables-title"/>, below.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -3489,8 +3481,8 @@ select 1\; select 2\; select 3;
</variablelist> </variablelist>
</para> </para>
<refsect3 id="app-psql-patterns"> <refsect3 id="app-psql-patterns" xreflabel="Patterns">
<title id="app-psql-patterns-title">Patterns</title> <title>Patterns</title>
<indexterm> <indexterm>
<primary>patterns</primary> <primary>patterns</primary>
@ -3582,8 +3574,8 @@ select 1\; select 2\; select 3;
<refsect2> <refsect2>
<title>Advanced Features</title> <title>Advanced Features</title>
<refsect3 id="app-psql-variables"> <refsect3 id="app-psql-variables" xreflabel="Variables">
<title id="app-psql-variables-title">Variables</title> <title>Variables</title>
<para> <para>
<application>psql</application> provides variable substitution <application>psql</application> provides variable substitution
@ -3607,8 +3599,7 @@ testdb=&gt; <userinput>\echo :foo</userinput>
bar bar
</programlisting> </programlisting>
This works in both regular SQL commands and meta-commands; there is This works in both regular SQL commands and meta-commands; there is
more detail in <xref linkend="app-psql-interpolation" more detail in <xref linkend="app-psql-interpolation"/>, below.
endterm="app-psql-interpolation-title"/>, below.
</para> </para>
<para> <para>
@ -4016,8 +4007,7 @@ bar
<para> <para>
These specify what the prompts <application>psql</application> These specify what the prompts <application>psql</application>
issues should look like. See <xref issues should look like. See <xref
linkend="app-psql-prompting" linkend="app-psql-prompting"/> below.
endterm="app-psql-prompting-title"/> below.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -4151,8 +4141,8 @@ bar
</refsect3> </refsect3>
<refsect3 id="app-psql-interpolation"> <refsect3 id="app-psql-interpolation" xreflabel="SQL Interpolation">
<title id="app-psql-interpolation-title"><acronym>SQL</acronym> Interpolation</title> <title><acronym>SQL</acronym> Interpolation</title>
<para> <para>
A key feature of <application>psql</application> A key feature of <application>psql</application>
@ -4236,8 +4226,8 @@ testdb=&gt; <userinput>INSERT INTO my_table VALUES (:'content');</userinput>
</refsect3> </refsect3>
<refsect3 id="app-psql-prompting"> <refsect3 id="app-psql-prompting" xreflabel="Prompting">
<title id="app-psql-prompting-title">Prompting</title> <title>Prompting</title>
<para> <para>
The prompts <application>psql</application> issues can be customized The prompts <application>psql</application> issues can be customized
@ -4393,9 +4383,8 @@ testdb=&gt; <userinput>INSERT INTO my_table VALUES (:'content');</userinput>
<listitem> <listitem>
<para> <para>
The value of the <application>psql</application> variable The value of the <application>psql</application> variable
<replaceable class="parameter">name</replaceable>. See the <replaceable class="parameter">name</replaceable>. See
section <xref linkend="app-psql-variables" <xref linkend="app-psql-variables"/>, above, for details.
endterm="app-psql-variables-title"/> for details.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -4492,8 +4481,8 @@ $endif
</refsect1> </refsect1>
<refsect1 id="app-psql-environment"> <refsect1 id="app-psql-environment" xreflabel="Environment">
<title id="app-psql-environment-title">Environment</title> <title>Environment</title>
<variablelist> <variablelist>
@ -4798,8 +4787,8 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
</refsect1> </refsect1>
<refsect1 id="app-psql-examples"> <refsect1 id="app-psql-examples" xreflabel="Examples">
<title id="app-psql-examples-title">Examples</title> <title>Examples</title>
<para> <para>
The first example shows how to spread a command over several lines of The first example shows how to spread a command over several lines of

7
doc/src/sgml/ref/reindex.sgml
View File

@ -163,8 +163,7 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN
updates, or deletes on the table; whereas a standard index rebuild updates, or deletes on the table; whereas a standard index rebuild
locks out writes (but not reads) on the table until it's done. locks out writes (but not reads) on the table until it's done.
There are several caveats to be aware of when using this option There are several caveats to be aware of when using this option
&mdash; see <xref linkend="sql-reindex-concurrently" &mdash; see <xref linkend="sql-reindex-concurrently"/> below.
endterm="sql-reindex-concurrently-title"/>.
</para> </para>
<para> <para>
For temporary tables, <command>REINDEX</command> is always For temporary tables, <command>REINDEX</command> is always
@ -264,8 +263,8 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { IN
Each individual partition can be reindexed separately instead. Each individual partition can be reindexed separately instead.
</para> </para>
<refsect2 id="sql-reindex-concurrently"> <refsect2 id="sql-reindex-concurrently" xreflabel="Rebuilding Indexes Concurrently">
<title id="sql-reindex-concurrently-title">Rebuilding Indexes Concurrently</title> <title>Rebuilding Indexes Concurrently</title>
<indexterm zone="sql-reindex-concurrently"> <indexterm zone="sql-reindex-concurrently">
<primary>index</primary> <primary>index</primary>

102
doc/src/sgml/ref/select.sgml
View File

@ -95,7 +95,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
that is referenced more than once in <literal>FROM</literal> is that is referenced more than once in <literal>FROM</literal> is
computed only once, computed only once,
unless specified otherwise with <literal>NOT MATERIALIZED</literal>. unless specified otherwise with <literal>NOT MATERIALIZED</literal>.
(See <xref linkend="sql-with" endterm="sql-with-title"/> below.) (See <xref linkend="sql-with"/> below.)
</para> </para>
</listitem> </listitem>
@ -105,7 +105,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
(Each element in the <literal>FROM</literal> list is a real or (Each element in the <literal>FROM</literal> list is a real or
virtual table.) If more than one element is specified in the virtual table.) If more than one element is specified in the
<literal>FROM</literal> list, they are cross-joined together. <literal>FROM</literal> list, they are cross-joined together.
(See <xref linkend="sql-from" endterm="sql-from-title"/> below.) (See <xref linkend="sql-from"/> below.)
</para> </para>
</listitem> </listitem>
@ -113,8 +113,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
<para> <para>
If the <literal>WHERE</literal> clause is specified, all rows If the <literal>WHERE</literal> clause is specified, all rows
that do not satisfy the condition are eliminated from the that do not satisfy the condition are eliminated from the
output. (See <xref linkend="sql-where" output. (See <xref linkend="sql-where"/> below.)
endterm="sql-where-title"/> below.)
</para> </para>
</listitem> </listitem>
@ -126,8 +125,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
values, and the results of aggregate functions are computed. values, and the results of aggregate functions are computed.
If the <literal>HAVING</literal> clause is present, it If the <literal>HAVING</literal> clause is present, it
eliminates groups that do not satisfy the given condition. (See eliminates groups that do not satisfy the given condition. (See
<xref linkend="sql-groupby" endterm="sql-groupby-title"/> and <xref linkend="sql-groupby"/> and
<xref linkend="sql-having" endterm="sql-having-title"/> below.) <xref linkend="sql-having"/> below.)
</para> </para>
</listitem> </listitem>
@ -135,9 +134,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
<para> <para>
The actual output rows are computed using the The actual output rows are computed using the
<command>SELECT</command> output expressions for each selected <command>SELECT</command> output expressions for each selected
row or row group. (See row or row group. (See <xref linkend="sql-select-list"/> below.)
<xref linkend="sql-select-list" endterm="sql-select-list-title"/>
below.)
</para> </para>
</listitem> </listitem>
@ -146,8 +143,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
result. <literal>SELECT DISTINCT ON</literal> eliminates rows that result. <literal>SELECT DISTINCT ON</literal> eliminates rows that
match on all the specified expressions. <literal>SELECT ALL</literal> match on all the specified expressions. <literal>SELECT ALL</literal>
(the default) will return all candidate rows, including (the default) will return all candidate rows, including
duplicates. (See <xref linkend="sql-distinct" duplicates. (See <xref linkend="sql-distinct"/> below.)
endterm="sql-distinct-title"/> below.)
</para> </para>
</listitem> </listitem>
@ -168,9 +164,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
eliminating duplicate rows. Notice that <literal>DISTINCT</literal> is eliminating duplicate rows. Notice that <literal>DISTINCT</literal> is
the default behavior here, even though <literal>ALL</literal> is the default behavior here, even though <literal>ALL</literal> is
the default for <command>SELECT</command> itself. (See the default for <command>SELECT</command> itself. (See
<xref linkend="sql-union" endterm="sql-union-title"/>, <xref <xref linkend="sql-union"/>, <xref linkend="sql-intersect"/>, and
linkend="sql-intersect" endterm="sql-intersect-title"/>, and <xref linkend="sql-except"/> below.)
<xref linkend="sql-except" endterm="sql-except-title"/> below.)
</para> </para>
</listitem> </listitem>
@ -180,7 +175,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
returned rows are sorted in the specified order. If returned rows are sorted in the specified order. If
<literal>ORDER BY</literal> is not given, the rows are returned <literal>ORDER BY</literal> is not given, the rows are returned
in whatever order the system finds fastest to produce. (See in whatever order the system finds fastest to produce. (See
<xref linkend="sql-orderby" endterm="sql-orderby-title"/> below.) <xref linkend="sql-orderby"/> below.)
</para> </para>
</listitem> </listitem>
@ -189,7 +184,7 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
If the <literal>LIMIT</literal> (or <literal>FETCH FIRST</literal>) or <literal>OFFSET</literal> If the <literal>LIMIT</literal> (or <literal>FETCH FIRST</literal>) or <literal>OFFSET</literal>
clause is specified, the <command>SELECT</command> statement clause is specified, the <command>SELECT</command> statement
only returns a subset of the result rows. (See <xref only returns a subset of the result rows. (See <xref
linkend="sql-limit" endterm="sql-limit-title"/> below.) linkend="sql-limit"/> below.)
</para> </para>
</listitem> </listitem>
@ -199,8 +194,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
or <literal>FOR KEY SHARE</literal> or <literal>FOR KEY SHARE</literal>
is specified, the is specified, the
<command>SELECT</command> statement locks the selected rows <command>SELECT</command> statement locks the selected rows
against concurrent updates. (See <xref linkend="sql-for-update-share" against concurrent updates. (See <xref linkend="sql-for-update-share"/>
endterm="sql-for-update-share-title"/> below.) below.)
</para> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>
@ -219,8 +214,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
<refsect1> <refsect1>
<title>Parameters</title> <title>Parameters</title>
<refsect2 id="sql-with"> <refsect2 id="sql-with" xreflabel="WITH Clause">
<title id="sql-with-title"><literal>WITH</literal> Clause</title> <title><literal>WITH</literal> Clause</title>
<para> <para>
The <literal>WITH</literal> clause allows you to specify one or more The <literal>WITH</literal> clause allows you to specify one or more
@ -336,8 +331,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-from"> <refsect2 id="sql-from" xreflabel="FROM Clause">
<title id="sql-from-title"><literal>FROM</literal> Clause</title> <title><literal>FROM</literal> Clause</title>
<para> <para>
The <literal>FROM</literal> clause specifies one or more source The <literal>FROM</literal> clause specifies one or more source
@ -707,8 +702,8 @@ TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-where"> <refsect2 id="sql-where" xreflabel="WHERE Clause">
<title id="sql-where-title"><literal>WHERE</literal> Clause</title> <title><literal>WHERE</literal> Clause</title>
<para> <para>
The optional <literal>WHERE</literal> clause has the general form The optional <literal>WHERE</literal> clause has the general form
@ -724,8 +719,8 @@ WHERE <replaceable class="parameter">condition</replaceable>
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-groupby"> <refsect2 id="sql-groupby" xreflabel="GROUP BY Clause">
<title id="sql-groupby-title"><literal>GROUP BY</literal> Clause</title> <title><literal>GROUP BY</literal> Clause</title>
<para> <para>
The optional <literal>GROUP BY</literal> clause has the general form The optional <literal>GROUP BY</literal> clause has the general form
@ -798,8 +793,8 @@ GROUP BY <replaceable class="parameter">grouping_element</replaceable> [, ...]
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-having"> <refsect2 id="sql-having" xreflabel="HAVING Clause">
<title id="sql-having-title"><literal>HAVING</literal> Clause</title> <title><literal>HAVING</literal> Clause</title>
<para> <para>
The optional <literal>HAVING</literal> clause has the general form The optional <literal>HAVING</literal> clause has the general form
@ -841,8 +836,8 @@ HAVING <replaceable class="parameter">condition</replaceable>
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-window"> <refsect2 id="sql-window" xreflabel="WINDOW Clause">
<title id="sql-window-title"><literal>WINDOW</literal> Clause</title> <title><literal>WINDOW</literal> Clause</title>
<para> <para>
The optional <literal>WINDOW</literal> clause has the general form The optional <literal>WINDOW</literal> clause has the general form
@ -874,8 +869,8 @@ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceabl
<para> <para>
The elements of the <literal>PARTITION BY</literal> list are interpreted in The elements of the <literal>PARTITION BY</literal> list are interpreted in
much the same fashion as elements of a much the same fashion as elements of a <link
<xref linkend="sql-groupby" endterm="sql-groupby-title"/>, except that linkend="sql-groupby"><literal>GROUP BY</literal></link> clause, except that
they are always simple expressions and never the name or number of an they are always simple expressions and never the name or number of an
output column. output column.
Another difference is that these expressions can contain aggregate Another difference is that these expressions can contain aggregate
@ -886,8 +881,8 @@ WINDOW <replaceable class="parameter">window_name</replaceable> AS ( <replaceabl
<para> <para>
Similarly, the elements of the <literal>ORDER BY</literal> list are interpreted Similarly, the elements of the <literal>ORDER BY</literal> list are interpreted
in much the same fashion as elements of an in much the same fashion as elements of a statement-level <link
<xref linkend="sql-orderby" endterm="sql-orderby-title"/>, except that linkend="sql-orderby"><literal>ORDER BY</literal></link> clause, except that
the expressions are always taken as simple expressions and never the name the expressions are always taken as simple expressions and never the name
or number of an output column. or number of an output column.
</para> </para>
@ -1011,8 +1006,9 @@ EXCLUDE NO OTHERS
<para> <para>
The purpose of a <literal>WINDOW</literal> clause is to specify the The purpose of a <literal>WINDOW</literal> clause is to specify the
behavior of <firstterm>window functions</firstterm> appearing in the query's behavior of <firstterm>window functions</firstterm> appearing in the query's
<xref linkend="sql-select-list" endterm="sql-select-list-title"/> or <link linkend="sql-select-list"><command>SELECT</command> list</link> or
<xref linkend="sql-orderby" endterm="sql-orderby-title"/>. These functions <link linkend="sql-orderby"><literal>ORDER BY</literal></link> clause.
These functions
can reference the <literal>WINDOW</literal> clause entries by name can reference the <literal>WINDOW</literal> clause entries by name
in their <literal>OVER</literal> clauses. A <literal>WINDOW</literal> clause in their <literal>OVER</literal> clauses. A <literal>WINDOW</literal> clause
entry does not have to be referenced anywhere, however; if it is not entry does not have to be referenced anywhere, however; if it is not
@ -1038,8 +1034,8 @@ EXCLUDE NO OTHERS
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-select-list"> <refsect2 id="sql-select-list" xreflabel="SELECT List">
<title id="sql-select-list-title"><command>SELECT</command> List</title> <title><command>SELECT</command> List</title>
<para> <para>
The <command>SELECT</command> list (between the key words The <command>SELECT</command> list (between the key words
@ -1119,8 +1115,8 @@ EXCLUDE NO OTHERS
</note> </note>
</refsect2> </refsect2>
<refsect2 id="sql-distinct"> <refsect2 id="sql-distinct" xreflabel="DISTINCT Clause">
<title id="sql-distinct-title"><literal>DISTINCT</literal> Clause</title> <title><literal>DISTINCT</literal> Clause</title>
<para> <para>
If <literal>SELECT DISTINCT</literal> is specified, all duplicate rows are If <literal>SELECT DISTINCT</literal> is specified, all duplicate rows are
@ -1164,8 +1160,8 @@ SELECT DISTINCT ON (location) location, time, report
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-union"> <refsect2 id="sql-union" xreflabel="UNION Clause">
<title id="sql-union-title"><literal>UNION</literal> Clause</title> <title><literal>UNION</literal> Clause</title>
<para> <para>
The <literal>UNION</literal> clause has this general form: The <literal>UNION</literal> clause has this general form:
@ -1217,8 +1213,8 @@ SELECT DISTINCT ON (location) location, time, report
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-intersect"> <refsect2 id="sql-intersect" xreflabel="INTERSECT Clause">
<title id="sql-intersect-title"><literal>INTERSECT</literal> Clause</title> <title><literal>INTERSECT</literal> Clause</title>
<para> <para>
The <literal>INTERSECT</literal> clause has this general form: The <literal>INTERSECT</literal> clause has this general form:
@ -1265,8 +1261,8 @@ SELECT DISTINCT ON (location) location, time, report
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-except"> <refsect2 id="sql-except" xreflabel="EXCEPT Clause">
<title id="sql-except-title"><literal>EXCEPT</literal> Clause</title> <title><literal>EXCEPT</literal> Clause</title>
<para> <para>
The <literal>EXCEPT</literal> clause has this general form: The <literal>EXCEPT</literal> clause has this general form:
@ -1309,8 +1305,8 @@ SELECT DISTINCT ON (location) location, time, report
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-orderby"> <refsect2 id="sql-orderby" xreflabel="ORDER BY Clause">
<title id="sql-orderby-title"><literal>ORDER BY</literal> Clause</title> <title><literal>ORDER BY</literal> Clause</title>
<para> <para>
The optional <literal>ORDER BY</literal> clause has this general form: The optional <literal>ORDER BY</literal> clause has this general form:
@ -1407,8 +1403,8 @@ SELECT name FROM distributors ORDER BY code;
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-limit"> <refsect2 id="sql-limit" xreflabel="LIMIT Clause">
<title id="sql-limit-title"><literal>LIMIT</literal> Clause</title> <title><literal>LIMIT</literal> Clause</title>
<para> <para>
The <literal>LIMIT</literal> clause consists of two independent The <literal>LIMIT</literal> clause consists of two independent
@ -1492,8 +1488,8 @@ FETCH { FIRST | NEXT } [ <replaceable class="parameter">count</replaceable> ] {
</para> </para>
</refsect2> </refsect2>
<refsect2 id="sql-for-update-share"> <refsect2 id="sql-for-update-share" xreflabel="The Locking Clause">
<title id="sql-for-update-share-title">The Locking Clause</title> <title>The Locking Clause</title>
<para> <para>
<literal>FOR UPDATE</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR SHARE</literal> <literal>FOR UPDATE</literal>, <literal>FOR NO KEY UPDATE</literal>, <literal>FOR SHARE</literal>
@ -2086,7 +2082,7 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
used by <productname>MySQL</productname>. The SQL:2008 standard used by <productname>MySQL</productname>. The SQL:2008 standard
has introduced the clauses <literal>OFFSET ... FETCH {FIRST|NEXT} has introduced the clauses <literal>OFFSET ... FETCH {FIRST|NEXT}
...</literal> for the same functionality, as shown above ...</literal> for the same functionality, as shown above
in <xref linkend="sql-limit" endterm="sql-limit-title"/>. This in <xref linkend="sql-limit"/>. This
syntax is also used by <productname>IBM DB2</productname>. syntax is also used by <productname>IBM DB2</productname>.
(Applications written for <productname>Oracle</productname> (Applications written for <productname>Oracle</productname>
frequently use a workaround involving the automatically frequently use a workaround involving the automatically

5
doc/src/sgml/ref/update.sgml
View File

@ -172,8 +172,9 @@ UPDATE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [
<para> <para>
A table expression allowing columns from other tables to appear in A table expression allowing columns from other tables to appear in
the <literal>WHERE</literal> condition and update expressions. This the <literal>WHERE</literal> condition and update expressions. This
uses the same syntax as the <xref linkend="sql-from" uses the same syntax as the <link
endterm="sql-from-title"/> of a <command>SELECT</command> statement; linkend="sql-from"><literal>FROM</literal></link> clause of
a <command>SELECT</command> statement;
for example, an alias for the table name can be specified. Do not for example, an alias for the table name can be specified. Do not
repeat the target table as a <replaceable>from_item</replaceable> repeat the target table as a <replaceable>from_item</replaceable>
unless you intend a self-join (in which case it must appear with unless you intend a self-join (in which case it must appear with

13
doc/src/sgml/ref/values.sgml
View File

@ -85,7 +85,8 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, ..
rows. This expression can refer to the columns of the rows. This expression can refer to the columns of the
<command>VALUES</command> result as <literal>column1</literal>, <literal>column2</literal>, <command>VALUES</command> result as <literal>column1</literal>, <literal>column2</literal>,
etc. For more details see etc. For more details see
<xref linkend="sql-orderby" endterm="sql-orderby-title"/>. <xref linkend="sql-orderby"/>
in the <xref linkend="sql-select"/> documentation.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -95,7 +96,8 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, ..
<listitem> <listitem>
<para> <para>
A sorting operator. For details see A sorting operator. For details see
<xref linkend="sql-orderby" endterm="sql-orderby-title"/>. <xref linkend="sql-orderby"/>
in the <xref linkend="sql-select"/> documentation.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -105,7 +107,8 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, ..
<listitem> <listitem>
<para> <para>
The maximum number of rows to return. For details see The maximum number of rows to return. For details see
<xref linkend="sql-limit" endterm="sql-limit-title"/>. <xref linkend="sql-limit"/>
in the <xref linkend="sql-select"/> documentation.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -115,8 +118,8 @@ VALUES ( <replaceable class="parameter">expression</replaceable> [, ...] ) [, ..
<listitem> <listitem>
<para> <para>
The number of rows to skip before starting to return rows. The number of rows to skip before starting to return rows.
For details see For details see <xref linkend="sql-limit"/>
<xref linkend="sql-limit" endterm="sql-limit-title"/>. in the <xref linkend="sql-select"/> documentation.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>