Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 60c90c1

Browse files
tglsfdctglsfdc
committed
Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs.
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
1 parent 624686a commit 60c90c1

26 files changed

+167
-193
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7301,8 +7301,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
73017301
These settings control the behavior of the <firstterm>autovacuum</firstterm>
73027302
feature. Refer to <xref linkend="autovacuum"/> for more information.
73037303
Note that many of these settings can be overridden on a per-table
7304-
basis; see <xref linkend="sql-createtable-storage-parameters"
7305-
endterm="sql-createtable-storage-parameters-title"/>.
7304+
basis; see <xref linkend="sql-createtable-storage-parameters"/>.
73067305
</para>
73077306

73087307
<variablelist>

‎doc/src/sgml/func.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4355,9 +4355,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
43554355
</para></entry>
43564356
</row>
43574357

4358-
<row id="function-encode">
4358+
<row>
43594359
<entry role="func_table_entry"><para role="func_signature">
4360-
<indexterm>
4360+
<indexterm id="function-encode">
43614361
<primary>encode</primary>
43624362
</indexterm>
43634363
<function>encode</function> ( <parameter>bytes</parameter> <type>bytea</type>,
@@ -4377,9 +4377,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
43774377
</para></entry>
43784378
</row>
43794379

4380-
<row id="function-decode">
4380+
<row>
43814381
<entry role="func_table_entry"><para role="func_signature">
4382-
<indexterm>
4382+
<indexterm id="function-decode">
43834383
<primary>decode</primary>
43844384
</indexterm>
43854385
<function>decode</function> ( <parameter>string</parameter> <type>text</type>,

‎doc/src/sgml/indices.sgml

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,7 @@ CREATE INDEX test1_id_index ON test1 (id);
9898
In production environments this is often unacceptable.
9999
It is possible to allow writes to occur in parallel with index
100100
creation, but there are several caveats to be aware of &mdash;
101-
for more information see <xref linkend="sql-createindex-concurrently"
102-
endterm="sql-createindex-concurrently-title"/>.
101+
for more information see <xref linkend="sql-createindex-concurrently"/>.
103102
</para>
104103

105104
<para>

‎doc/src/sgml/maintenance.sgml

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

‎doc/src/sgml/queries.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ SELECT random();
110110
<title>The <literal>FROM</literal> Clause</title>
111111

112112
<para>
113-
The <xref linkend="sql-from" endterm="sql-from-title"/> derives a
113+
The <link linkend="sql-from"><literal>FROM</literal></link> clause derives a
114114
table from one or more other tables given in a comma-separated
115115
table reference list.
116116
<synopsis>
@@ -907,8 +907,8 @@ WHERE pname IS NULL;
907907
</indexterm>
908908

909909
<para>
910-
The syntax of the <xref linkend="sql-where"
911-
endterm="sql-where-title"/> is
910+
The syntax of the <link linkend="sql-where"><literal>WHERE</literal></link>
911+
clause is
912912
<synopsis>
913913
WHERE <replaceable>search_condition</replaceable>
914914
</synopsis>
@@ -1014,7 +1014,7 @@ SELECT <replaceable>select_list</replaceable>
10141014
</synopsis>
10151015

10161016
<para>
1017-
The <xref linkend="sql-groupby" endterm="sql-groupby-title"/> is
1017+
The <link linkend="sql-groupby"><literal>GROUP BY</literal></link> clause is
10181018
used to group together those rows in a table that have the same
10191019
values in all the columns listed. The order in which the columns
10201020
are listed does not matter. The effect is to combine each set

‎doc/src/sgml/ref/alter_collation.sgml

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -93,16 +93,15 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
9393
<listitem>
9494
<para>
9595
Update the collation's version.
96-
See <xref linkend="sql-altercollation-notes"
97-
endterm="sql-altercollation-notes-title"/> below.
96+
See <xref linkend="sql-altercollation-notes"/> below.
9897
</para>
9998
</listitem>
10099
</varlistentry>
101100
</variablelist>
102101
</refsect1>
103102

104-
<refsect1 id="sql-altercollation-notes">
105-
<title id="sql-altercollation-notes-title">Notes</title>
103+
<refsect1 id="sql-altercollation-notes" xreflabel="Notes">
104+
<title>Notes</title>
106105

107106
<para>
108107
When using collations provided by the ICU library, the ICU-specific version

‎doc/src/sgml/ref/alter_table.sgml

Lines changed: 7 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -405,8 +405,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
405405
database will not assume that the constraint holds for all rows in
406406
the table, until it is validated by using the <literal>VALIDATE
407407
CONSTRAINT</literal> option.
408-
See <xref linkend="sql-altertable-notes"
409-
endterm="sql-altertable-notes-title"/> below for more information
408+
See <xref linkend="sql-altertable-notes"/> below for more information
410409
about using the <literal>NOT VALID</literal> option.
411410
</para>
412411

@@ -504,9 +503,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
504503
previously created as <literal>NOT VALID</literal>, by scanning the
505504
table to ensure there are no rows for which the constraint is not
506505
satisfied. Nothing happens if the constraint is already marked valid.
507-
(See <xref linkend="sql-altertable-notes"
508-
endterm="sql-altertable-notes-title"/> below for an explanation of the
509-
usefulness of this command.)
506+
(See <xref linkend="sql-altertable-notes"/> below for an explanation
507+
of the usefulness of this command.)
510508
</para>
511509
</listitem>
512510
</varlistentry>
@@ -708,8 +706,8 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
708706
<listitem>
709707
<para>
710708
This form changes one or more storage parameters for the table. See
711-
<xref linkend="sql-createtable-storage-parameters"
712-
endterm="sql-createtable-storage-parameters-title"/>
709+
<xref linkend="sql-createtable-storage-parameters"/> in the
710+
<xref linkend="sql-createtable"/> documentation
713711
for details on the available parameters. Note that the table contents
714712
will not be modified immediately by this command; depending on the
715713
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
12101208
</variablelist>
12111209
</refsect1>
12121210

1213-
<refsect1 id="sql-altertable-notes">
1214-
<title id="sql-altertable-notes-title">Notes</title>
1211+
<refsect1 id="sql-altertable-notes" xreflabel="Notes">
1212+
<title>Notes</title>
12151213

12161214
<para>
12171215
The key word <literal>COLUMN</literal> is noise and can be omitted.

‎doc/src/sgml/ref/create_aggregate.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -434,8 +434,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
434434
This option specifies whether the final function is a pure function
435435
that does not modify its arguments. <literal>READ_ONLY</literal> indicates
436436
it does not; the other two values indicate that it may change the
437-
transition state value. See <xref linkend="sql-createaggregate-notes"
438-
endterm="sql-createaggregate-notes-title"/> below for more detail. The
437+
transition state value. See <xref linkend="sql-createaggregate-notes"/>
438+
below for more detail. The
439439
default is <literal>READ_ONLY</literal>, except for ordered-set aggregates,
440440
for which the default is <literal>READ_WRITE</literal>.
441441
</para>
@@ -664,8 +664,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
664664
</para>
665665
</refsect1>
666666

667-
<refsect1 id="sql-createaggregate-notes">
668-
<title id="sql-createaggregate-notes-title">Notes</title>
667+
<refsect1 id="sql-createaggregate-notes" xreflabel="Notes">
668+
<title>Notes</title>
669669

670670
<para>
671671
In parameters that specify support function names, you can write

‎doc/src/sgml/ref/create_index.sgml

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -126,8 +126,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
126126
updates, or deletes on the table; whereas a standard index build
127127
locks out writes (but not reads) on the table until it's done.
128128
There are several caveats to be aware of when using this option
129-
&mdash; see <xref linkend="sql-createindex-concurrently"
130-
endterm="sql-createindex-concurrently-title"/>.
129+
&mdash; see <xref linkend="sql-createindex-concurrently"/> below.
131130
</para>
132131
<para>
133132
For temporary tables, <command>CREATE INDEX</command> is always
@@ -337,7 +336,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
337336
<listitem>
338337
<para>
339338
The name of an index-method-specific storage parameter. See
340-
<xref linkend="sql-createindex-storage-parameters" endterm="sql-createindex-storage-parameters-title"/>
339+
<xref linkend="sql-createindex-storage-parameters"/> below
341340
for details.
342341
</para>
343342
</listitem>
@@ -366,8 +365,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
366365

367366
</variablelist>
368367

369-
<refsect2 id="sql-createindex-storage-parameters">
370-
<title id="sql-createindex-storage-parameters-title">Index Storage Parameters</title>
368+
<refsect2 id="sql-createindex-storage-parameters" xreflabel="Index Storage Parameters">
369+
<title>Index Storage Parameters</title>
371370

372371
<para>
373372
The optional <literal>WITH</literal> clause specifies <firstterm>storage
@@ -559,8 +558,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
559558
</variablelist>
560559
</refsect2>
561560

562-
<refsect2 id="sql-createindex-concurrently">
563-
<title id="sql-createindex-concurrently-title">Building Indexes Concurrently</title>
561+
<refsect2 id="sql-createindex-concurrently" xreflabel="Building Indexes Concurrently">
562+
<title>Building Indexes Concurrently</title>
564563

565564
<indexterm zone="sql-createindex-concurrently">
566565
<primary>index</primary>
@@ -688,7 +687,7 @@ Indexes:
688687
</para>
689688

690689
<para>
691-
An <firstterm>operator class</firstterm> with its optional parameters
690+
An <firstterm>operator class</firstterm> with optional parameters
692691
can be specified for each column of an index.
693692
The operator class identifies the operators to be
694693
used by the index for that column. For example, a B-tree index on

‎doc/src/sgml/ref/create_materialized_view.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,8 +106,9 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] <replaceable>table_name</replaceable>
106106
<listitem>
107107
<para>
108108
This clause specifies optional storage parameters for the new
109-
materialized view; see <xref linkend="sql-createtable-storage-parameters"
110-
endterm="sql-createtable-storage-parameters-title"/> for more
109+
materialized view; see
110+
<xref linkend="sql-createtable-storage-parameters"/> in the
111+
<xref linkend="sql-createtable"/> documentation for more
111112
information. All parameters supported for <literal>CREATE
112113
TABLE</literal> are also supported for <literal>CREATE MATERIALIZED
113114
VIEW</literal>.

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

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -192,8 +192,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
192192
can be written before <literal>TEMPORARY</literal> or <literal>TEMP</literal>.
193193
This presently makes no difference in <productname>PostgreSQL</productname>
194194
and is deprecated; see
195-
<xref linkend="sql-createtable-compatibility"
196-
endterm="sql-createtable-compatibility-title"/>.
195+
<xref linkend="sql-createtable-compatibility"/> below.
197196
</para>
198197
</listitem>
199198
</varlistentry>
@@ -1201,8 +1200,7 @@ WITH ( MODULUS <replaceable class="parameter">numeric_literal</replaceable>, REM
12011200
<listitem>
12021201
<para>
12031202
This clause specifies optional storage parameters for a table or index;
1204-
see <xref linkend="sql-createtable-storage-parameters"
1205-
endterm="sql-createtable-storage-parameters-title"/> for more
1203+
see <xref linkend="sql-createtable-storage-parameters"/> below for more
12061204
information. For backward-compatibility the <literal>WITH</literal>
12071205
clause for a table can also include <literal>OIDS=FALSE</literal> to
12081206
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
13021300

13031301
</variablelist>
13041302

1305-
<refsect2 id="sql-createtable-storage-parameters">
1306-
<title id="sql-createtable-storage-parameters-title">Storage Parameters</title>
1303+
<refsect2 id="sql-createtable-storage-parameters" xreflabel="Storage Parameters">
1304+
<title>Storage Parameters</title>
13071305

13081306
<indexterm zone="sql-createtable-storage-parameters">
13091307
<primary>storage parameters</primary>
@@ -2063,8 +2061,8 @@ CREATE TABLE cities_partdef
20632061
</programlisting></para>
20642062
</refsect1>
20652063

2066-
<refsect1 id="sql-createtable-compatibility">
2067-
<title id="sql-createtable-compatibility-title">Compatibility</title>
2064+
<refsect1 id="sql-createtable-compatibility" xreflabel="Compatibility">
2065+
<title>Compatibility</title>
20682066

20692067
<para>
20702068
The <command>CREATE TABLE</command> command conforms to the

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
140140
<listitem>
141141
<para>
142142
This clause specifies optional storage parameters for the new table;
143-
see <xref linkend="sql-createtable-storage-parameters"
144-
endterm="sql-createtable-storage-parameters-title"/> for more
143+
see <xref linkend="sql-createtable-storage-parameters"/> in the
144+
<xref linkend="sql-createtable"/> documentation for more
145145
information. For backward-compatibility the <literal>WITH</literal>
146146
clause for a table can also include <literal>OIDS=FALSE</literal> to
147147
specify that rows of the new table should contain no OIDs (object

‎doc/src/sgml/ref/declare.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -99,8 +99,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
9999
<literal>NO SCROLL</literal> specifies that the cursor cannot be
100100
used to retrieve rows in a nonsequential fashion. The default is to
101101
allow scrolling in some cases; this is not the same as specifying
102-
<literal>SCROLL</literal>. See <xref linkend="sql-declare-notes"
103-
endterm="sql-declare-notes-title"/> for details.
102+
<literal>SCROLL</literal>. See <xref linkend="sql-declare-notes"/>
103+
below for details.
104104
</para>
105105
</listitem>
106106
</varlistentry>
@@ -139,8 +139,8 @@ DECLARE <replaceable class="parameter">name</replaceable> [ BINARY ] [ INSENSITI
139139
</para>
140140
</refsect1>
141141

142-
<refsect1 id="sql-declare-notes">
143-
<title id="sql-declare-notes-title">Notes</title>
142+
<refsect1 id="sql-declare-notes" xreflabel="Notes">
143+
<title>Notes</title>
144144

145145
<para>
146146
Normal cursors return data in text format, the same as a

‎doc/src/sgml/ref/delete.sgml

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

‎doc/src/sgml/ref/execute.sgml

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -94,9 +94,8 @@ EXECUTE <replaceable class="parameter">name</replaceable> [ ( <replaceable class
9494
<refsect1>
9595
<title>Examples</title>
9696
<para>
97-
Examples are given in the <xref linkend="sql-prepare-examples"
98-
endterm="sql-prepare-examples-title"/> section of the <xref
99-
linkend="sql-prepare"/> documentation.
97+
Examples are given in <xref linkend="sql-prepare-examples"/>
98+
in the <xref linkend="sql-prepare"/> documentation.
10099
</para>
101100
</refsect1>
102101

‎doc/src/sgml/ref/insert.sgml

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,7 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
7777
<para>
7878
<literal>ON CONFLICT</literal> can be used to specify an alternative
7979
action to raising a unique constraint or exclusion constraint
80-
violation error. (See <xref linkend="sql-on-conflict"
81-
endterm="sql-on-conflict-title"/> below.)
80+
violation error. (See <xref linkend="sql-on-conflict"/> below.)
8281
</para>
8382

8483
<para>
@@ -128,8 +127,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
128127
<refsect1>
129128
<title>Parameters</title>
130129

131-
<refsect2 id="sql-inserting-params">
132-
<title id="sql-inserting-params-title">Inserting</title>
130+
<refsect2>
131+
<title>Inserting</title>
133132

134133
<para>
135134
This section covers parameters that may be used when only
@@ -315,8 +314,8 @@ INSERT INTO <replaceable class="parameter">table_name</replaceable> [ AS <replac
315314
</variablelist>
316315
</refsect2>
317316

318-
<refsect2 id="sql-on-conflict">
319-
<title id="sql-on-conflict-title"><literal>ON CONFLICT</literal> Clause</title>
317+
<refsect2 id="sql-on-conflict" xreflabel="ON CONFLICT Clause">
318+
<title><literal>ON CONFLICT</literal> Clause</title>
320319
<indexterm zone="sql-insert">
321320
<primary>UPSERT</primary>
322321
</indexterm>

‎doc/src/sgml/ref/lock.sgml

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -202,9 +202,8 @@ LOCK [ TABLE ] [ ONLY ] <replaceable class="parameter">name</replaceable> [ * ]
202202
<command>LOCK TABLE</command> is concerned, differing only in the rules
203203
about which modes conflict with which. For information on how to
204204
acquire an actual row-level lock, see <xref linkend="locking-rows"/>
205-
and the <xref linkend="sql-for-update-share"
206-
endterm="sql-for-update-share-title"/> in the <command>SELECT</command>
207-
reference documentation.
205+
and <xref linkend="sql-for-update-share"/>
206+
in the <xref linkend="sql-select"/> documentation.
208207
</para>
209208
</refsect1>
210209

0 commit comments

Comments
 (0)