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/[email protected]

Author: tglsfdc

doc/src/sgml/config.sgml

@@ -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>
       feature.  Refer to <xref linkend="autovacuum"/> for more information.
       Note that many of these settings can be overridden on a per-table
-      basis; see <xref linkend="sql-createtable-storage-parameters"
-      endterm="sql-createtable-storage-parameters-title"/>.
+      basis; see <xref linkend="sql-createtable-storage-parameters"/>.
      </para>
 
     <variablelist>

doc/src/sgml/func.sgml

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

doc/src/sgml/indices.sgml

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

doc/src/sgml/maintenance.sgml

@@ -827,8 +827,7 @@ analyze threshold = analyze base threshold + analyze scale factor * number of tu
     The default thresholds and scale factors are taken from
     <filename>postgresql.conf</filename>, but it is possible to override them
     (and many other autovacuum control parameters) on a per-table basis; see
-    <xref linkend="sql-createtable-storage-parameters"
-    endterm="sql-createtable-storage-parameters-title"/> for more information.
+    <xref linkend="sql-createtable-storage-parameters"/> for more information.
     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
     used. See <xref linkend="runtime-config-autovacuum"/> for more details on

doc/src/sgml/queries.sgml

@@ -110,7 +110,7 @@ SELECT random();
    <title>The <literal>FROM</literal> Clause</title>
 
    <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 reference list.
 <synopsis>
@@ -907,8 +907,8 @@ WHERE pname IS NULL;
    </indexterm>
 
    <para>
-    The syntax of the <xref linkend="sql-where"
-    endterm="sql-where-title"/> is
+    The syntax of the <link linkend="sql-where"><literal>WHERE</literal></link>
+    clause is
 <synopsis>
 WHERE <replaceable>search_condition</replaceable>
 </synopsis>
@@ -1014,7 +1014,7 @@ SELECT <replaceable>select_list</replaceable>
 </synopsis>
 
    <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
     values in all the columns listed. The order in which the columns
     are listed does not matter.  The effect is to combine each set

doc/src/sgml/ref/alter_collation.sgml

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

doc/src/sgml/ref/alter_table.sgml

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

doc/src/sgml/ref/create_aggregate.sgml

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

doc/src/sgml/ref/create_index.sgml

@@ -126,8 +126,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
         updates, or deletes on the table; whereas a standard index build
         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
-        &mdash; see <xref linkend="sql-createindex-concurrently"
-        endterm="sql-createindex-concurrently-title"/>.
+        &mdash; see <xref linkend="sql-createindex-concurrently"/> below.
        </para>
        <para>
         For temporary tables, <command>CREATE INDEX</command> is always
@@ -337,7 +336,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
       <listitem>
        <para>
         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.
        </para>
       </listitem>
@@ -366,8 +365,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
 
     </variablelist>
 
-  <refsect2 id="sql-createindex-storage-parameters">
-   <title id="sql-createindex-storage-parameters-title">Index Storage Parameters</title>
+  <refsect2 id="sql-createindex-storage-parameters" xreflabel="Index Storage Parameters">
+   <title>Index Storage Parameters</title>
 
    <para>
     The optional <literal>WITH</literal> clause specifies <firstterm>storage
@@ -559,8 +558,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] <replaceable class=
    </variablelist>
   </refsect2>
 
-  <refsect2 id="sql-createindex-concurrently">
-   <title id="sql-createindex-concurrently-title">Building Indexes Concurrently</title>
+  <refsect2 id="sql-createindex-concurrently" xreflabel="Building Indexes Concurrently">
+   <title>Building Indexes Concurrently</title>
 
    <indexterm zone="sql-createindex-concurrently">
    <primary>index</primary>
@@ -688,7 +687,7 @@ Indexes:
   </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.
    The operator class identifies the operators to be
    used by the index for that column. For example, a B-tree index on

doc/src/sgml/ref/create_materialized_view.sgml

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