Subject: [PATCH] add link to domain data types section from locale documentation

From: Anton Voloshin <[email-masked]>
Date: Tue, 30 Mar 2021 22:46:34 +0300

Hello.

While browsing character set collation documentation [1]
I've found myself a bit puzzled by unfamiliar terminology:
 > of course a domain over a collatable data type is collatable

Of course, it only takes a search or two to find out the exact
meaning of "domain" in this context, but I think it would be useful
to make this word a link to the relevant section as a help for less 
experienced users like myself.

I've attached a patch that does that. Please let me know whether this 
fix is desirable and correct (I'm new to Postgres) and if there is a 
better way of suggesting an improvement for the documentation.

[1] https://www.postgresql.org/docs/current/collation.html

-- 
Anton Voloshin
Postgres Professional: https://www.postgrespro.com
Russian Postgres Company
diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 1b00e543a6..300a0d83d4 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 <link linkend="domains">domain</link> 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

---

From: Laurenz Albe <[email-masked]>
Date: Wed, 31 Mar 2021 11:48:48 +0200

> [1] https://www.postgresql.org/docs/current/collation.html

+1

Yours,
Laurenz Albe

---

From: Anton Voloshin <[email-masked]>
Date: Thu, 1 Apr 2021 09:54:27 +0300

>> better way of suggesting an improvement for the documentation.

Thanks! Should I do something to ensure this doc patch getting committed 
to Postgres? Or will it be picked up from my [1] original email by some 
committer without any further efforts from my side?

[1] 
https://www.postgresql.org/message-id/2ea65bdf-1380-f088-02bd-ff1a31ed265c%40postgrespro.ru

---

From: Laurenz Albe <[email-masked]>
Date: Thu, 01 Apr 2021 09:46:10 +0200

> committer without any further efforts from my side?

The committers are currently busy with the commitfest.

You could add it to the next commitfest so that it does not get forgotten.

Yours,
Laurenz Albe

---

From: Anton Voloshin <[email-masked]>
Date: Thu, 1 Apr 2021 11:00:38 +0300

> You could add it to the next commitfest so that it does not get forgotten.

Thanks. Added for 2021-07 commitfest:
https://commitfest.postgresql.org/33/3056/

---

From: Jürgen Purtz <[email-masked]>
Date: Thu, 1 Apr 2021 10:29:19 +0200

> [1] https://www.postgresql.org/docs/current/collation.html
It's likely that the term "domain" within an SQL context confuse some 
people. An additional remark in the glossary concerning the SQL and IP 
meaning may be helpful.

--

Jürgen Purtz

diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml
index 1b00e543a6..300a0d83d4 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 <link linkend="domains">domain</link> 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/glossary.sgml b/doc/src/sgml/glossary.sgml
index 41f3e5ee86..a7a0e35ac5 100644
--- a/doc/src/sgml/glossary.sgml
+++ b/doc/src/sgml/glossary.sgml
@@ -508,6 +508,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>

---

From: Anton Voloshin <[email-masked]>
Date: Thu, 1 Apr 2021 11:45:50 +0300

> people. An additional remark in the glossary concerning the SQL and IP 

Nice touch, thanks!

---

From: Laurenz Albe <[email-masked]>
Date: Thu, 27 May 2021 09:45:27 +0200

> > people. An additional remark in the glossary concerning the SQL and IP 

I have had a look at the patch.

The addition to the glossary is good.

I spotted this in "src/sgml/glossary.sgml":

  <glossentry id="glossary-constraint">
   <glossterm>Constraint</glossterm>
   <glossdef>
    <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>.
    </para>
    <para>
     For more information, see
     <xref linkend="ddl-constraints"/>.
    </para>
   </glossdef>
  </glossentry>

You should add a link to the new "domain" entry from there.
I think the comment should be removed.

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

---

From: Jürgen Purtz <[email-masked]>
Date: Fri, 23 Jul 2021 23:07:54 +0200

> This selection is a bit arbitrary, I admit.

Done at the proposed pages - and a few more.

--

Jürgen Purtz

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>

---

From: Laurenz Albe <[email-masked]>
Date: Fri, 30 Jul 2021 05:58:57 +0200

> Done at the proposed pages - and a few more.

Looks good to me - changed to "ready for committer".

Yours,
Laurenz Albe

---

From: Tom Lane <[email-masked]>
Date: Fri, 30 Jul 2021 15:05:08 -0400

> Looks good to me - changed to "ready for committer".

Pushed with a bit of editorialization:

* I removed the glossary entry for "Domain (Internet)".  AFAICS we
have not been making entries for non-SQL usages of terms: you won't
find anything about physics under "Atomic", nor anything about
flatware under "Fork", nor anything about the postal service under
"Postmaster".  I don't think this is mere laziness; it could be
actively confusing to do so, since someone looking up "domain" from
elsewhere in the docs might be unsure which definition is meant.
Even in the places where the patch provides an exact link, there's
no certainty that a display tool will render the page in such a way
that it's impossible to misidentify which entry was linked to.

* I also added a bit more detail to the glossary entry, so that
people wouldn't have to go read the referenced section to come
away with a reasonable mental model of what a domain is.

* I thought the changes in information_schema.sgml were pretty
haphazard.  There are 115 references to "domain" in that file
by my count, and there seemed little rationale behind the half
dozen you'd chosen to link-ify.  I cut it down to just linking
from the section for the "domains" view, which seemed like
someplace that someone would look first if they were unsure
what this was about.

			regards, tom lane