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
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>
