Subject: Re: [PATCH] add link to domain data types section from locale
 documentation
To: Laurenz Albe <laurenz.albe@cybertec.at>,
 Anton Voloshin <a.voloshin@postgrespro.ru>, pgsql-docs@lists.postgresql.org
References: <2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru>
 <511121ea-613a-6600-b252-5cebaaa3bccf@purtz.de>
 <3a0dff3f-9e24-eee2-ee9e-b643b626e7b8@postgrespro.ru>
 <3b80ddf5a978bf084401e61288210d2fa3e75f37.camel@cybertec.at>
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Message-ID: <be790e45-bb85-360c-c8a5-1fbcef234f62@purtz.de>
Date: Fri, 23 Jul 2021 23:07:54 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.11.0
MIME-Version: 1.0
In-Reply-To: <3b80ddf5a978bf084401e61288210d2fa3e75f37.camel@cybertec.at>
Content-Type: multipart/mixed;
 boundary="------------77C28163DE6CD58F19051E6D"
Content-Language: en-US
Archived-At: 
 <https://www.postgresql.org/message-id/be790e45-bb85-360c-c8a5-1fbcef234f62%40purtz.de>
Precedence: bulk

This is a multi-part message in MIME format.
--------------77C28163DE6CD58F19051E6D
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 8bit

On 27.05.21 09:45, Laurenz Albe wrote:
> I like the new link from "src/sgml/charset.sgml", but I think that
> there are a few other places in the documentation that are likely to be
> read by people who don't know about SQL domains and could benefit from such
> a link:
>
> - src/sgml/earthdistance.sgml
>
> - src/sgml/lo.sgml
>
> - src/sgml/information_schema.sgml (the entries about "check_constraints",
>    "column_domain_usage", "data_type_privileges", "domain_constraints",
>    "domain_catalog", "domain_udt_usage", "domains" and the description below
>    "columns")
>
> This selection is a bit arbitrary, I admit.
>
> Yours,
> Laurenz Albe

Done at the proposed pages - and a few more.

--

Jürgen Purtz


--------------77C28163DE6CD58F19051E6D
Content-Type: text/x-patch; charset=UTF-8;
 name="collation-domains-link-03.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
 filename="collation-domains-link-03.patch"

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 98df74d0e1..8434bf6ba4 100644
--- a/doc/src/sgml/charset.sgml
+++ b/doc/src/sgml/charset.sgml
@@ -346,7 +346,8 @@ initdb --locale=sv_SE
     collation.  (The built-in collatable data types are
     <type>text</type>, <type>varchar</type>, and <type>char</type>.
     User-defined base types can also be marked collatable, and of course
-    a domain over a collatable data type is collatable.)  If the
+    a <glossterm linkend="glossary-domain-sql">domain</glossterm> over a
+    collatable data type is collatable.)  If the
     expression is a column reference, the collation of the expression is the
     defined collation of the column.  If the expression is a constant, the
     collation is the default collation of the data type of the
diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml
index 641e69c5e9..f5b60ea612 100644
--- a/doc/src/sgml/earthdistance.sgml
+++ b/doc/src/sgml/earthdistance.sgml
@@ -50,7 +50,8 @@
   <para>
    Data is stored in cubes that are points (both corners are the same) using 3
    coordinates representing the x, y, and z distance from the center of the
-   Earth.  A domain <type>earth</type> over <type>cube</type> is provided, which
+   Earth.  A <glossterm linkend="glossary-domain-sql">domain</glossterm> <type>earth</type>
+   over <type>cube</type> is provided, which
    includes constraint checks that the value meets these restrictions and
    is reasonably close to the actual surface of the Earth.
   </para>
diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml
index c8d0440e80..0c1176fa07 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -389,9 +389,7 @@
     <para>
      A restriction on the values of data allowed within a
      <glossterm linkend="glossary-table">table</glossterm>,
-     or in attributes of a
-     <!-- XXX Should have term "domain". Need term "type" for that. -->
-     <firstterm>domain</firstterm>.
+     or in attributes of a <glossterm linkend="glossary-domain-sql">domain</glossterm>.
     </para>
     <para>
      For more information, see
@@ -508,6 +506,27 @@
    </glossdef>
   </glossentry>
 
+  <glossentry id="glossary-domain-internet">
+   <glossterm>Domain (Internet)</glossterm>
+   <glossdef>
+    <para>
+     A realm to administer certain Internet resources.
+    </para>
+   </glossdef>
+  </glossentry>
+
+  <glossentry id="glossary-domain-sql">
+   <glossterm>Domain (SQL)</glossterm>
+   <glossdef>
+    <para>
+     A user-defined data type that is based on another underlying data type.
+    </para>
+    <para>
+     For more information, see <xref linkend="domains"/>.
+    </para>
+   </glossdef>
+  </glossentry>
+
   <glossentry id="glossary-durability">
    <glossterm>Durability</glossterm>
    <glossdef>
diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml
index 4100198252..13de037b8e 100644
--- a/doc/src/sgml/information_schema.sgml
+++ b/doc/src/sgml/information_schema.sgml
@@ -912,8 +912,8 @@
 
   <para>
    The view <literal>check_constraints</literal> contains all check
-   constraints, either defined on a table or on a domain, that are
-   owned by a currently enabled role.  (The owner of the table or
+   constraints, either defined on a table or on a <glossterm linkend="glossary-domain-sql">domain</glossterm>,
+   that are owned by a currently enabled role.  (The owner of the table or
    domain is the owner of the constraint.)
   </para>
 
@@ -1199,7 +1199,8 @@
 
   <para>
    The view <literal>column_domain_usage</literal> identifies all
-   columns (of a table or a view) that make use of some domain defined
+   columns (of a table or a view) that make use of some
+   <glossterm linkend="glossary-domain-sql">domain</glossterm> defined
    in the current database and owned by a currently enabled role.
   </para>
 
@@ -2307,7 +2308,8 @@
    data type descriptors that the current user has access to, by way
    of being the owner of the described object or having some privilege
    for it.  A data type descriptor is generated whenever a data type
-   is used in the definition of a table column, a domain, or a
+   is used in the definition of a table column, a
+   <glossterm linkend="glossary-domain-sql">domain</glossterm>, or a
    function (as parameter or return type) and stores some information
    about how the data type is used in that instance (for example, the
    declared maximum length, if applicable).  Each data type
@@ -2393,7 +2395,8 @@
 
   <para>
    The view <literal>domain_constraints</literal> contains all constraints
-   belonging to domains defined in the current database.  Only those domains
+   belonging to <glossterm linkend="glossary-domain-sql">domains</glossterm>
+   defined in the current database.  Only those domains
    are shown that the current user has access to (by way of being the owner or
    having some privilege).
   </para>
@@ -2445,7 +2448,8 @@
        <structfield>domain_catalog</structfield> <type>sql_identifier</type>
       </para>
       <para>
-       Name of the database that contains the domain (always the current database)
+       Name of the database that contains the <glossterm linkend="glossary-domain-sql">domain</glossterm>
+       (always the current database)
       </para></entry>
      </row>
 
@@ -2493,7 +2497,8 @@
   <title><literal>domain_udt_usage</literal></title>
 
   <para>
-   The view <literal>domain_udt_usage</literal> identifies all domains
+   The view <literal>domain_udt_usage</literal> identifies all
+   <glossterm linkend="glossary-domain-sql">domains</glossterm>
    that are based on data types owned by a currently enabled role.
    Note that in <productname>PostgreSQL</productname>, built-in data
    types behave like user-defined types, so they are included here as
@@ -2577,7 +2582,8 @@
   <title><literal>domains</literal></title>
 
   <para>
-   The view <literal>domains</literal> contains all domains defined in the
+   The view <literal>domains</literal> contains all
+   <glossterm linkend="glossary-domain-sql">domains</glossterm> defined in the
    current database.  Only those domains are shown that the current user has
    access to (by way of being the owner or having some privilege).
   </para>
diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml
index 0a4f2e4449..d77e39ac76 100644
--- a/doc/src/sgml/lo.sgml
+++ b/doc/src/sgml/lo.sgml
@@ -55,7 +55,8 @@
 
   <para>
    The module also provides a data type <type>lo</type>, which is really just
-   a domain of the <type>oid</type> type.  This is useful for differentiating
+   a <glossterm linkend="glossary-domain-sql">domain</glossterm> of the <type>oid</type> type.
+   This is useful for differentiating
    database columns that hold large object references from those that are
    OIDs of other things.  You don't have to use the <type>lo</type> type to
    use the trigger, but it may be convenient to use it to keep track of which
diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml
index a6f4f6709c..222baf9619 100644
--- a/doc/src/sgml/rowtypes.sgml
+++ b/doc/src/sgml/rowtypes.sgml
@@ -84,7 +84,8 @@ CREATE TABLE inventory_item (
   restriction of the current implementation: since no constraints are
   associated with a composite type, the constraints shown in the table
   definition <emphasis>do not apply</emphasis> to values of the composite type
-  outside the table.  (To work around this, create a domain over the composite
+  outside the table.  (To work around this, create a
+  <glossterm linkend="glossary-domain-sql">domain</glossterm> over the composite
   type, and apply the desired constraints as <literal>CHECK</literal>
   constraints of the domain.)
  </para>

--------------77C28163DE6CD58F19051E6D--