Doc: fix "Unresolved ID reference" warnings, clean up man page cross-refs.
authorTom Lane
Mon, 11 May 2020 18:15:49 +0000 (14:15 -0400)
committerTom Lane
Mon, 11 May 2020 18:15:55 +0000 (14:15 -0400)
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 
rendering exactly so, by using a  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.   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  constructs.
We can put the IDs on 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

26 files changed:
doc/src/sgml/config.sgml
doc/src/sgml/func.sgml
doc/src/sgml/indices.sgml
doc/src/sgml/maintenance.sgml
doc/src/sgml/queries.sgml
doc/src/sgml/ref/alter_collation.sgml
doc/src/sgml/ref/alter_table.sgml
doc/src/sgml/ref/create_aggregate.sgml
doc/src/sgml/ref/create_index.sgml
doc/src/sgml/ref/create_materialized_view.sgml
doc/src/sgml/ref/create_table.sgml
doc/src/sgml/ref/create_table_as.sgml
doc/src/sgml/ref/declare.sgml
doc/src/sgml/ref/delete.sgml
doc/src/sgml/ref/execute.sgml
doc/src/sgml/ref/insert.sgml
doc/src/sgml/ref/lock.sgml
doc/src/sgml/ref/pg_dump.sgml
doc/src/sgml/ref/pg_dumpall.sgml
doc/src/sgml/ref/postgres-ref.sgml
doc/src/sgml/ref/prepare.sgml
doc/src/sgml/ref/psql-ref.sgml
doc/src/sgml/ref/reindex.sgml
doc/src/sgml/ref/select.sgml
doc/src/sgml/ref/update.sgml
doc/src/sgml/ref/values.sgml

index 3aea1763b48ad4fe6b5067ca550708a8675daf7f..9f2a4a2470e3a9316209f3ade7984f60b21c31a0 100644 (file)
@@ -7301,8 +7301,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       These settings control the behavior of the autovacuum
       feature.  Refer to  for more information.
       Note that many of these settings can be overridden on a per-table
-      basis; see 
-      endterm="sql-createtable-storage-parameters-title"/>.
+      basis; see .
      
 
     
index d9b3598977f4dff4fb8204067ab6adffca5e49f0..7c06afd3eafcb68d67faad526c17b17674d7ed78 100644 (file)
@@ -4355,9 +4355,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
       
      
 
-      id="function-encode">
+     
       
-       
+        id="function-encode">
         encode
        
        encode ( bytes bytea,
@@ -4377,9 +4377,9 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
       
      
 
-      id="function-decode">
+     
       
-       
+        id="function-decode">
         decode
        
        decode ( string text,
index 1be209a2fe72ef963cc08b7be277f7d6c8e97bb2..98d7a238de7bb6da4e1835bd2f5e49a1312b910f 100644 (file)
@@ -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 
-   endterm="sql-createindex-concurrently-title"/>.
+   for more information see .
   
 
   
index a0e0f34c25f9026d9c07b67976671baaba152b69..39075ea8f33d9d8230707291cdf7510ddb76f47e 100644 (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
     postgresql.conf, but it is possible to override them
     (and many other autovacuum control parameters) on a per-table basis; see
-    
-    endterm="sql-createtable-storage-parameters-title"/> for more information.
+     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  for more details on
index 22252556be22178da83d081a273395ef26c9df05..572e9682733a7d188bb7aa9dedb49dc782ed0190 100644 (file)
@@ -110,7 +110,7 @@ SELECT random();
    The <literal>FROM</literal> Clause
 
    
-    The <xref linkend="sql-from" endterm="sql-from-title"/> derives a
+    The <link linkend="sql-from">FROM clause derives a
     table from one or more other tables given in a comma-separated
     table reference list.
 
@@ -907,8 +907,8 @@ WHERE pname IS NULL;
    
 
    
-    The syntax of the <xref linkend="sql-where"
-    endterm="sql-where-title"/> is
+    The syntax of the <link linkend="sql-where">WHERE
+    clause is
 
 WHERE search_condition
 
@@ -1014,7 +1014,7 @@ SELECT select_list
 
 
    
-    The <xref linkend="sql-groupby" endterm="sql-groupby-title"/> is
+    The <link linkend="sql-groupby">GROUP BY 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
index 4cfcb42251f00d5fd97d7d4bcf1bbe76aaecdd7e..56f94627c673eee8ac5a127cc74389b85c0999c9 100644 (file)
@@ -93,16 +93,15 @@ ALTER COLLATION name SET SCHEMA new_sche
     
      
       Update the collation's version.
-      See 
-      endterm="sql-altercollation-notes-title"/> below.
+      See  below.
      
     
    
   
  
 
-   id="sql-altercollation-notes-title">Notes
 xreflabel="Notes">
+  Notes
 
   
    When using collations provided by the ICU library, the ICU-specific version
index 6563bd5ab213025162affd385324f59e809c4b33..cbfb4828e5060776fce9ca212880fe2ee13b6e9e 100644 (file)
@@ -405,8 +405,7 @@ WITH ( MODULUS numeric_literal, REM
       database will not assume that the constraint holds for all rows in
       the table, until it is validated by using the VALIDATE
       CONSTRAINT option.
-      See 
-      endterm="sql-altertable-notes-title"/> below for more information
+      See  below for more information
       about using the NOT VALID option.
      
 
@@ -504,9 +503,8 @@ WITH ( MODULUS numeric_literal, REM
       previously created as NOT VALID, 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 
-      endterm="sql-altertable-notes-title"/> below for an explanation of the
-      usefulness of this command.)
+      (See  below for an explanation
+      of the usefulness of this command.)
      
     
    
@@ -708,8 +706,8 @@ WITH ( MODULUS numeric_literal, REM
     
      
       This form changes one or more storage parameters for the table.  See
-      
-      endterm="sql-createtable-storage-parameters-title"/>
+      /> in the
+       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 numeric_literal, REM
     
  
 
-   id="sql-altertable-notes-title">Notes
 xreflabel="Notes">
+  Notes
 
    
     The key word COLUMN is noise and can be omitted.
index 644657dd5efd54b9562a3e86acfcd9169b3cae8a..811e288ec1efb91609aa0de6f5f9969568d017fa 100644 (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
       that does not modify its arguments.  READ_ONLY indicates
       it does not; the other two values indicate that it may change the
-      transition state value.  See 
-      endterm="sql-createaggregate-notes-title"/> below for more detail.  The
+      transition state value.  See />
+      below for more detail.  The
       default is READ_ONLY, except for ordered-set aggregates,
       for which the default is READ_WRITE.
      
@@ -664,8 +664,8 @@ SELECT col FROM tab ORDER BY col USING sortop LIMIT 1;
   
  
 
-   id="sql-createaggregate-notes-title">Notes
 xreflabel="Notes">
+  Notes
 
    
     In parameters that specify support function names, you can write
index aaf087e2e3279e76317bd211ee29d98e494b526b..ff87b2d28fca4e6f26e0bcf14d2f315ac6afffa3 100644 (file)
@@ -126,8 +126,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] 
         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
-        — see 
-        endterm="sql-createindex-concurrently-title"/>.
+        — see  below.
        
        
         For temporary tables, CREATE INDEX is always
@@ -337,7 +336,7 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] 
       
        
         The name of an index-method-specific storage parameter.  See
-         endterm="sql-createindex-storage-parameters-title"/>
+        /> below
         for details.
        
       
@@ -366,8 +365,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] 
 
     
 
-  
-    id="sql-createindex-storage-parameters-title">Index Storage Parameters
+   xreflabel="Index Storage Parameters">
+   Index Storage Parameters
 
    
     The optional WITH clause specifies storage
@@ -559,8 +558,8 @@ CREATE [ UNIQUE ] INDEX [ CONCURRENTLY ] [ [ IF NOT EXISTS ] 
    
   
 
-  
-    id="sql-createindex-concurrently-title">Building Indexes Concurrently
+   xreflabel="Building Indexes Concurrently">
+   Building Indexes Concurrently
 
    
    index
@@ -688,7 +687,7 @@ Indexes:
   
 
   
-   An operator class with its optional parameters 
+   An operator class 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
index ec8847ed406c99b1b35f61ebe896edc4d5a008c7..de9f17655c63203bc5cb87e7a1187cad96a26a58 100644 (file)
@@ -106,8 +106,9 @@ CREATE MATERIALIZED VIEW [ IF NOT EXISTS ] table_name
     
      
       This clause specifies optional storage parameters for the new
-      materialized view; see 
-      endterm="sql-createtable-storage-parameters-title"/> for more
+      materialized view; see
+       in the
+       documentation for more
       information.  All parameters supported for CREATE
       TABLE are also supported for CREATE MATERIALIZED
       VIEW.
index c49c770dd0379eaa2678daecfdad3d9ddf0630f4..849f7e931fa5475cc0b415a6b8fdf322f2357929 100644 (file)
@@ -192,8 +192,7 @@ WITH ( MODULUS numeric_literal, REM
       can be written before TEMPORARY or TEMP.
       This presently makes no difference in PostgreSQL
       and is deprecated; see
-      
-      endterm="sql-createtable-compatibility-title"/>.
+       below.
      
     
    
@@ -1201,8 +1200,7 @@ WITH ( MODULUS numeric_literal, REM
     
      
       This clause specifies optional storage parameters for a table or index;
-      see 
-      endterm="sql-createtable-storage-parameters-title"/> for more
+      see  below for more
       information.  For backward-compatibility the WITH
       clause for a table can also include OIDS=FALSE to
       specify that rows of the new table should not contain OIDs (object
@@ -1302,8 +1300,8 @@ WITH ( MODULUS numeric_literal, REM
 
   
 
-  
-    id="sql-createtable-storage-parameters-title">Storage Parameters
+   xreflabel="Storage Parameters">
+   Storage Parameters
 
  
   storage parameters
@@ -2063,8 +2061,8 @@ CREATE TABLE cities_partdef
 
  
 
-   id="sql-createtable-compatibility-title">Compatibility
 xreflabel="Compatibility">
+  Compatibility
 
   
    The CREATE TABLE command conforms to the
index 56d06838f1620d03d9473bd7539d0a07b860a46a..a4640929cfba6c2d59ff11507109cfebae9646fe 100644 (file)
@@ -140,8 +140,8 @@ CREATE [ [ GLOBAL | LOCAL ] { TEMPORARY | TEMP } | UNLOGGED ] TABLE [ IF NOT EXI
     
      
       This clause specifies optional storage parameters for the new table;
-      see 
-      endterm="sql-createtable-storage-parameters-title"/> for more
+      see /> in the
+       documentation for more
       information.   For backward-compatibility the WITH
       clause for a table can also include OIDS=FALSE to
       specify that rows of the new table should contain no OIDs (object
index 34ca9df2437d17a0b91369fdd18570a06524a049..d6177dcd9c44ed2cfab5ffb7caccda82ee5e97a7 100644 (file)
@@ -99,8 +99,8 @@ DECLARE name [ BINARY ] [ INSENSITI
       NO SCROLL specifies that the cursor cannot be
       used to retrieve rows in a nonsequential fashion.  The default is to
       allow scrolling in some cases; this is not the same as specifying
-      SCROLL. See 
-      endterm="sql-declare-notes-title"/> for details.
+      SCROLL. See />
+      below for details.
      
     
    
@@ -139,8 +139,8 @@ DECLARE name [ BINARY ] [ INSENSITI
   
  
 
-   id="sql-declare-notes-title">Notes
 xreflabel="Notes">
+  Notes
 
   
    Normal cursors return data in text format, the same as a
index 08fb032b50569d08dcf60f689ce04b5766c8642a..ec3c40df2ea9dcfbbd4f78a62bfb82a48cab6028 100644 (file)
@@ -122,8 +122,8 @@ DELETE FROM [ ONLY ] table_name [ *
      
       A table expression allowing columns from other tables to appear
       in the WHERE condition.  This uses the same
-      syntax as the <xref linkend="sql-from" endterm="sql-from-title"/>
-      of a SELECT statement; for example, an alias
+      syntax as the <link linkend="sql-from">FROM>
+      clause of a SELECT statement; for example, an alias
       for the table name can be specified.  Do not repeat the target
       table as a from_item
       unless you wish to set up a self-join (in which case it must appear
index aab1f4b7e0828fe6e32111382cc031381efb46d8..1d887f3d179a1529047124f06a538387c166fb54 100644 (file)
@@ -94,9 +94,8 @@ EXECUTE name [ ( 
  
   Examples
   
-    Examples are given in the 
-    endterm="sql-prepare-examples-title"/> section of the 
-    linkend="sql-prepare"/> documentation.
+    Examples are given in 
+    in the  documentation.
    
  
 
index a6cec6b02ea9bd1c791c7c681f2abe539ad56ccc..2973b72b8159b83080053d5fa2dcc3b929a7d163 100644 (file)
@@ -77,8 +77,7 @@ INSERT INTO table_name [ AS 
   
    ON CONFLICT can be used to specify an alternative
    action to raising a unique constraint or exclusion constraint
-   violation error. (See 
-   endterm="sql-on-conflict-title"/> below.)
+   violation error. (See  below.)
   
 
   
@@ -128,8 +127,8 @@ INSERT INTO table_name [ AS 
  
   Parameters
 
-   id="sql-inserting-params">
-    id="sql-inserting-params-title">Inserting
+  
+   Inserting
 
    
     This section covers parameters that may be used when only
@@ -315,8 +314,8 @@ INSERT INTO table_name [ AS 
     
   
 
-  
-    id="sql-on-conflict-title">ON CONFLICT Clause
+   xreflabel="ON CONFLICT Clause">
+   <literal>ON CONFLICT</literal> Clause
    
     UPSERT
    
index a225cea63b2afeb4beb0b5abbbb79ac7143a0540..0c4688603d9f9c251b7540390f0b5aee579f8b74 100644 (file)
@@ -202,9 +202,8 @@ LOCK [ TABLE ] [ ONLY ] name [ * ]
    LOCK TABLE is concerned, differing only in the rules
    about which modes conflict with which. For information on how to
    acquire an actual row-level lock, see 
-   and the 
-   endterm="sql-for-update-share-title"/> in the SELECT
-   reference documentation.
+   and 
+   in the  documentation.
   
  
 
index a9bc39716576acf1f8fe7ce0741a460e6b1df8d7..197b5c0d70e30afb2708008841d31a33f79e986a 100644 (file)
@@ -387,12 +387,12 @@ PostgreSQL documentation
         selected by writing multiple  switches.  The
         pattern parameter is
         interpreted as a pattern according to the same rules used by
-        psql's \d commands (see 
-        linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
+        psql's \d commands
+        (see  below),
         so multiple schemas can also be selected by writing wildcard characters
         in the pattern.  When using wildcards, be careful to quote the pattern
         if needed to prevent the shell from expanding the wildcards;  see
-         endterm="pg-dump-examples-title"/>.
+        /> below.
        
 
        
@@ -524,12 +524,12 @@ PostgreSQL documentation
         can be selected by writing multiple  switches.  The
         pattern parameter is
         interpreted as a pattern according to the same rules used by
-        psql's \d commands (see 
-        linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
+        psql's \d commands
+        (see  below),
         so multiple tables can also be selected by writing wildcard characters
         in the pattern.  When using wildcards, be careful to quote the pattern
         if needed to prevent the shell from expanding the wildcards;  see
-         endterm="pg-dump-examples-title"/>.
+        /> below.
        
 
        
@@ -777,12 +777,12 @@ PostgreSQL documentation
          switches.
         Also, the foreignserver parameter is
         interpreted as a pattern according to the same rules used by
-        psql's \d commands (see 
-        linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
+        psql's \d commands
+        (see  below),
         so multiple foreign servers can also be selected by writing wildcard characters
         in the pattern.  When using wildcards, be careful to quote the pattern
         if needed to prevent the shell from expanding the wildcards; see
-         endterm="pg-dump-examples-title"/>.
+        /> below.
         The only exception is that an empty pattern is disallowed.
        
 
@@ -1367,8 +1367,8 @@ CREATE DATABASE foo WITH TEMPLATE template0;
   
  
 
-   id="pg-dump-examples-title">Examples
 xreflabel="Examples">
+  Examples
 
   
    To dump a database called mydb into a SQL-script file:
@@ -1477,8 +1477,7 @@ CREATE DATABASE foo WITH TEMPLATE template0;
   
    To specify an upper-case or mixed-case name in  and related
    switches, you need to double-quote the name; else it will be folded to
-   lower case (see 
-   linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>).  But
+   lower case (see  below).  But
    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
    like
index f0859896c547a3c06b1e53e5feffd533dbecbbc3..40ca31bfdfe605b06375bfc6896cfb8db10cd244 100644 (file)
@@ -310,8 +310,7 @@ PostgreSQL documentation
         pattern parameter is
         interpreted as a pattern according to the same rules used by
         psql's \d
-        commands (see 
-        linkend="app-psql-patterns" endterm="app-psql-patterns-title"/>),
+        commands (see  below),
         so multiple databases can also be excluded by writing wildcard
         characters in the pattern.  When using wildcards, be careful to
         quote the pattern if needed to prevent shell wildcard expansion.
index 1a4b7c7825d540a3b2b60c83818694ee98f41fa8..5e5794bc90d8bb59f7117ecc6803b8bc6f8e2996 100644 (file)
@@ -530,8 +530,7 @@ PostgreSQL documentation
 
     
      The following options only apply to the single-user mode
-     (see 
-     endterm="app-postgres-single-user-title"/>).
+     (see  below).
     
 
     
@@ -753,8 +752,8 @@ PostgreSQL documentation
   
  
 
-   id="app-postgres-single-user-title">Single-User Mode
 xreflabel="Single-User Mode">
+  Single-User Mode
 
    
     To start a single-user mode server, use a command like
index 4e5e96a4014d09c29f135fdfe92bc2bddc0f1fc6..5ec86aee10d30192e7686951ed7fab85afa2dc64 100644 (file)
@@ -208,8 +208,8 @@ EXPLAIN EXECUTE name(parameter_values
   
  
 
-   id="sql-prepare-examples-title">Examples
 xreflabel="Examples">
+  Examples
   
    Create a prepared statement for an INSERT
    statement, and then execute it:
index de303c8814465444c5054c0c1e9064ba019eed1e..07bf272a201636e6fd16fcab0c003e4cb712fbcd 100644 (file)
@@ -809,7 +809,7 @@ testdb=>
     If an unquoted colon (:) followed by a
     psql variable name appears within an argument, it is
     replaced by the variable's value, as described in 
-    linkend="app-psql-interpolation" endterm="app-psql-interpolation-title"/>.
+    linkend="app-psql-interpolation"/> below.
     The forms :'variable_name' and
     :"variable_name" described there
     work as well.
@@ -1163,8 +1163,7 @@ testdb=>
         also shown.  For foreign tables, the associated foreign
         server is shown as well.
         (Matching the pattern is defined in
-        
-        below.)
+         below.)
         
 
         
@@ -1946,9 +1945,8 @@ testdb=>
 
         
         
-        See under 
-        endterm="app-psql-environment-title"/> for how to configure and
-        customize your editor.
+        See , below, for how to
+        configure and customize your editor.
         
         
         
@@ -2022,9 +2020,8 @@ Tue Oct 26 21:40:57 CEST 1999
 
         
         
-        See under 
-        endterm="app-psql-environment-title"/> for how to configure and
-        customize your editor.
+        See , below, for how to
+        configure and customize your editor.
         
         
         
@@ -2230,8 +2227,8 @@ CREATE INDEX
         
         
          Sends the current query buffer to the server and stores the
-         query's output into psql variables (see 
-         linkend="app-psql-variables" endterm="app-psql-variables-title"/>).
+         query's output into psql variables
+         (see  below).
          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
          column.  For example:
@@ -3078,8 +3075,7 @@ lo_import 152801
 
         
         Illustrations of how these different formats look can be seen in
-        the 
-        endterm="app-psql-examples-title"/> section.
+        , below.
         
 
         
@@ -3163,9 +3159,7 @@ lo_import 152801
 
         
         Valid variable names can contain letters, digits, and
-        underscores. See the section 
-        linkend="app-psql-variables"
-        endterm="app-psql-variables-title"/> below for details.
+        underscores. See  below for details.
         Variable names are case-sensitive.
         
 
@@ -3173,8 +3167,7 @@ lo_import 152801
         Certain variables are special, in that they
         control psql's behavior or are
         automatically set to reflect connection state.  These variables are
-        documented in 
-        endterm="app-psql-variables-title"/>, below.
+        documented in , below.
         
 
         
@@ -3318,8 +3311,7 @@ testdb=> \setenv LESS -imx4F
         Most variables that control psql's behavior
         cannot be unset; instead, an \unset command is interpreted
         as setting them to their default values.
-        See 
-        endterm="app-psql-variables-title"/>, below.
+        See  below.
         
         
       
@@ -3489,8 +3481,8 @@ select 1\; select 2\; select 3;
     
   
 
-  
-    id="app-psql-patterns-title">Patterns
+   xreflabel="Patterns">
+   Patterns
 
    
     patterns
@@ -3582,8 +3574,8 @@ select 1\; select 2\; select 3;
  
   Advanced Features
 
-   
-     id="app-psql-variables-title">Variables
+    xreflabel="Variables">
+    Variables
 
     
     psql provides variable substitution
@@ -3607,8 +3599,7 @@ testdb=> \echo :foo
 bar
 
     This works in both regular SQL commands and meta-commands; there is
-    more detail in 
-    endterm="app-psql-interpolation-title"/>, below.
+    more detail in , below.
     
 
     
@@ -4016,8 +4007,7 @@ bar
         
         These specify what the prompts psql
         issues should look like. See 
-        linkend="app-psql-prompting"
-        endterm="app-psql-prompting-title"/> below.
+        linkend="app-psql-prompting"/> below.
         
         
       
@@ -4151,8 +4141,8 @@ bar
 
    
 
-   
-     id="app-psql-interpolation-title">SQL Interpolation
+    xreflabel="SQL Interpolation">
+    <acronym>SQL</acronym> Interpolation
 
     
     A key feature of psql
@@ -4236,8 +4226,8 @@ testdb=> INSERT INTO my_table VALUES (:'content');
 
    
 
-   
-     id="app-psql-prompting-title">Prompting
+    xreflabel="Prompting">
+    Prompting
 
     
     The prompts psql issues can be customized
@@ -4393,9 +4383,8 @@ testdb=> INSERT INTO my_table VALUES (:'content');
         
         
         The value of the psql variable
-        name. See the
-        section 
-        endterm="app-psql-variables-title"/> for details.
+        name. See
+        , above, for details.
         
         
       
@@ -4492,8 +4481,8 @@ $endif
  
 
 
-   id="app-psql-environment-title">Environment
 xreflabel="Environment">
+  Environment
 
   
 
@@ -4798,8 +4787,8 @@ PSQL_EDITOR_LINENUMBER_ARG='--line '
  
 
 
-   id="app-psql-examples-title">Examples
 xreflabel="Examples">
+  Examples
 
   
   The first example shows how to spread a command over several lines of
index c54a7c420d426e6d277b0457d4db56d13a5fd064..aac5d5be23f4f381a30e25d641ee391302fce677 100644 (file)
@@ -163,8 +163,7 @@ REINDEX [ ( option [, ...] ) ] { IN
       updates, or deletes on the table; whereas a standard index rebuild
       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
-      — see 
-      endterm="sql-reindex-concurrently-title"/>.
+      — see  below.
      
      
       For temporary tables, REINDEX is always
@@ -264,8 +263,8 @@ REINDEX [ ( option [, ...] ) ] { IN
    Each individual partition can be reindexed separately instead.
   
 
-  
-    id="sql-reindex-concurrently-title">Rebuilding Indexes Concurrently
+   xreflabel="Rebuilding Indexes Concurrently">
+   Rebuilding Indexes Concurrently
 
    
     index
index 91388151ad40858f09b159219df4c68a73fe9a2b..475281dd7be61b520f0acf858340e1cccff4f1e1 100644 (file)
@@ -95,7 +95,7 @@ TABLE [ ONLY ] table_name [ * ]
       that is referenced more than once in FROM is
       computed only once,
       unless specified otherwise with NOT MATERIALIZED.
-      (See  endterm="sql-with-title"/> below.)
+      (See  below.)
      
     
 
@@ -105,7 +105,7 @@ TABLE [ ONLY ] table_name [ * ]
       (Each element in the FROM list is a real or
       virtual table.)  If more than one element is specified in the
       FROM list, they are cross-joined together.
-      (See  endterm="sql-from-title"/> below.)
+      (See  below.)
      
     
 
@@ -113,8 +113,7 @@ TABLE [ ONLY ] table_name [ * ]
      
       If the WHERE clause is specified, all rows
       that do not satisfy the condition are eliminated from the
-      output.  (See 
-      endterm="sql-where-title"/> below.)
+      output.  (See  below.)
      
     
 
@@ -126,8 +125,8 @@ TABLE [ ONLY ] table_name [ * ]
       values, and the results of aggregate functions are computed.
       If the HAVING clause is present, it
       eliminates groups that do not satisfy the given condition.  (See
-       endterm="sql-groupby-title"/> and
-       endterm="sql-having-title"/> below.)
+       and
+       below.)
      
     
 
@@ -135,9 +134,7 @@ TABLE [ ONLY ] table_name [ * ]
      
       The actual output rows are computed using the
       SELECT output expressions for each selected
-      row or row group.  (See
-      
-      below.)
+      row or row group.  (See  below.)
      
     
 
@@ -146,8 +143,7 @@ TABLE [ ONLY ] table_name [ * ]
       result.  SELECT DISTINCT ON eliminates rows that
       match on all the specified expressions.  SELECT ALL
       (the default) will return all candidate rows, including
-      duplicates.  (See 
-      endterm="sql-distinct-title"/> below.)
+      duplicates.  (See  below.)
      
     
 
@@ -168,9 +164,8 @@ TABLE [ ONLY ] table_name [ * ]
       eliminating duplicate rows.  Notice that DISTINCT is
       the default behavior here, even though ALL is
       the default for SELECT itself.  (See
-      
-      linkend="sql-intersect" endterm="sql-intersect-title"/>, and
-       below.)
+      , and
+       below.)
      
     
 
@@ -180,7 +175,7 @@ TABLE [ ONLY ] table_name [ * ]
       returned rows are sorted in the specified order.  If
       ORDER BY is not given, the rows are returned
       in whatever order the system finds fastest to produce.  (See
-       endterm="sql-orderby-title"/> below.)
+       below.)
      
     
 
@@ -189,7 +184,7 @@ TABLE [ ONLY ] table_name [ * ]
       If the LIMIT (or FETCH FIRST) or OFFSET
       clause is specified, the SELECT statement
       only returns a subset of the result rows. (See 
-      linkend="sql-limit" endterm="sql-limit-title"/> below.)
+      linkend="sql-limit"/> below.)
      
     
 
@@ -199,8 +194,8 @@ TABLE [ ONLY ] table_name [ * ]
       or FOR KEY SHARE
       is specified, the
       SELECT statement locks the selected rows
-      against concurrent updates.  (See 
-      endterm="sql-for-update-share-title"/> below.)
+      against concurrent updates.  (See />
+      below.)
      
     
    
@@ -219,8 +214,8 @@ TABLE [ ONLY ] table_name [ * ]
  
   Parameters
 
-  
-    id="sql-with-title">WITH Clause
+   xreflabel="WITH Clause">
+   <literal>WITH</literal> Clause
 
    
     The WITH clause allows you to specify one or more
@@ -336,8 +331,8 @@ TABLE [ ONLY ] table_name [ * ]
    
   
 
-  
-    id="sql-from-title">FROM Clause
+   xreflabel="FROM Clause">
+   <literal>FROM</literal> Clause
 
    
     The FROM clause specifies one or more source
@@ -707,8 +702,8 @@ TABLE [ ONLY ] table_name [ * ]
    
   
 
-  
-    id="sql-where-title">WHERE Clause
+   xreflabel="WHERE Clause">
+   <literal>WHERE</literal> Clause
 
    
     The optional WHERE clause has the general form
@@ -724,8 +719,8 @@ WHERE condition
    
   
 
-  
-    id="sql-groupby-title">GROUP BY Clause
+   xreflabel="GROUP BY Clause">
+   <literal>GROUP BY</literal> Clause
 
    
     The optional GROUP BY clause has the general form
@@ -798,8 +793,8 @@ GROUP BY grouping_element [, ...]
    
   
 
-  
-    id="sql-having-title">HAVING Clause
+   xreflabel="HAVING Clause">
+   <literal>HAVING</literal> Clause
 
    
     The optional HAVING clause has the general form
@@ -841,8 +836,8 @@ HAVING condition
    
   
 
-  
-    id="sql-window-title">WINDOW Clause
+   xreflabel="WINDOW Clause">
+   <literal>WINDOW</literal> Clause
 
    
     The optional WINDOW clause has the general form
@@ -874,8 +869,8 @@ WINDOW window_name AS ( 
 
    
     The elements of the PARTITION BY list are interpreted in
-    much the same fashion as elements of a
-    , except that
+    much the same fashion as elements of a 
+    linkend="sql-groupby">GROUP BY clause, except that
     they are always simple expressions and never the name or number of an
     output column.
     Another difference is that these expressions can contain aggregate
@@ -886,8 +881,8 @@ WINDOW window_name AS ( 
 
    
     Similarly, the elements of the ORDER BY list are interpreted
-    in much the same fashion as elements of an
-    , except that
+    in much the same fashion as elements of a statement-level 
+    linkend="sql-orderby">ORDER BY clause, except that
     the expressions are always taken as simple expressions and never the name
     or number of an output column.
    
@@ -1011,8 +1006,9 @@ EXCLUDE NO OTHERS
    
     The purpose of a WINDOW clause is to specify the
     behavior of window functions appearing in the query's
-     or
-    .  These functions
+    SELECT list or
+    ORDER BY clause.
+    These functions
     can reference the WINDOW clause entries by name
     in their OVER clauses.  A WINDOW clause
     entry does not have to be referenced anywhere, however; if it is not
@@ -1038,8 +1034,8 @@ EXCLUDE NO OTHERS
    
   
 
-  
-    id="sql-select-list-title">SELECT List
+   xreflabel="SELECT List">
+   <command>SELECT</command> List
 
    
     The SELECT list (between the key words
@@ -1119,8 +1115,8 @@ EXCLUDE NO OTHERS
    
   
 
-  
-    id="sql-distinct-title">DISTINCT Clause
+   xreflabel="DISTINCT Clause">
+   <literal>DISTINCT</literal> Clause
 
    
     If SELECT DISTINCT is specified, all duplicate rows are
@@ -1164,8 +1160,8 @@ SELECT DISTINCT ON (location) location, time, report
    
   
 
-  
-    id="sql-union-title">UNION Clause
+   xreflabel="UNION Clause">
+   <literal>UNION</literal> Clause
 
    
     The UNION clause has this general form:
@@ -1217,8 +1213,8 @@ SELECT DISTINCT ON (location) location, time, report
    
   
 
-  
-    id="sql-intersect-title">INTERSECT Clause
+   xreflabel="INTERSECT Clause">
+   <literal>INTERSECT</literal> Clause
 
    
     The INTERSECT clause has this general form:
@@ -1265,8 +1261,8 @@ SELECT DISTINCT ON (location) location, time, report
    
   
 
-  
-    id="sql-except-title">EXCEPT Clause
+   xreflabel="EXCEPT Clause">
+   <literal>EXCEPT</literal> Clause
 
    
     The EXCEPT clause has this general form:
@@ -1309,8 +1305,8 @@ SELECT DISTINCT ON (location) location, time, report
    
   
 
-  
-    id="sql-orderby-title">ORDER BY Clause
+   xreflabel="ORDER BY Clause">
+   <literal>ORDER BY</literal> Clause
 
    
     The optional ORDER BY clause has this general form:
@@ -1407,8 +1403,8 @@ SELECT name FROM distributors ORDER BY code;
    
   
 
-  
-    id="sql-limit-title">LIMIT Clause
+   xreflabel="LIMIT Clause">
+   <literal>LIMIT</literal> Clause
 
    
     The LIMIT clause consists of two independent
@@ -1492,8 +1488,8 @@ FETCH { FIRST | NEXT } [ count ] {
    
   
 
-  
-    id="sql-for-update-share-title">The Locking Clause
+   xreflabel="The Locking Clause">
+   The Locking Clause
 
    
     FOR UPDATEFOR NO KEY UPDATEFOR SHARE
@@ -2086,7 +2082,7 @@ SELECT distributors.* WHERE distributors.name = 'Westward';
     used by MySQL.  The SQL:2008 standard
     has introduced the clauses OFFSET ... FETCH {FIRST|NEXT}
     ... for the same functionality, as shown above
-    in  endterm="sql-limit-title"/>.  This
+    in .  This
     syntax is also used by IBM DB2.
     (Applications written for Oracle
     frequently use a workaround involving the automatically
index f2891a3b0a72b06eb127b8219e18fa31b976c5a3..3fa54e5f703b0c55bb237649a03a3746d98e12f4 100644 (file)
@@ -172,8 +172,9 @@ UPDATE [ ONLY ] table_name [ * ] [
      
       A table expression allowing columns from other tables to appear in
       the WHERE condition and update expressions. This
-      uses the same syntax as the 
-      endterm="sql-from-title"/> of a SELECT statement;
+      uses the same syntax as the 
+      linkend="sql-from">FROM clause of
+      a SELECT statement;
       for example, an alias for the table name can be specified.  Do not
       repeat the target table as a from_item
       unless you intend a self-join (in which case it must appear with
index 849220b12064359cf825e32c8d8a6dcb0a626590..d3a3aaff1408a2c35062abfe892359c832e36c49 100644 (file)
@@ -85,7 +85,8 @@ VALUES ( expression [, ...] ) [, ..
       rows.  This expression can refer to the columns of the
       VALUES result as column1column2,
       etc.  For more details see
-      .
+      
+      in the  documentation.
      
     
    
@@ -95,7 +96,8 @@ VALUES ( expression [, ...] ) [, ..
     
      
       A sorting operator.  For details see
-      .
+      
+      in the  documentation.
      
     
    
@@ -105,7 +107,8 @@ VALUES ( expression [, ...] ) [, ..
     
      
       The maximum number of rows to return.  For details see
-      .
+      
+      in the  documentation.
      
     
    
@@ -115,8 +118,8 @@ VALUES ( expression [, ...] ) [, ..
     
      
       The number of rows to skip before starting to return rows.
-      For details see
-      .
+      For details see 
+      in the  documentation.