Subject: Re: [PATCH] add link to domain data types section from locale
 documentation
To: pgsql-docs@lists.postgresql.org
References: <2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru>
From: =?UTF-8?Q?J=c3=bcrgen_Purtz?= <juergen@purtz.de>
Message-ID: <511121ea-613a-6600-b252-5cebaaa3bccf@purtz.de>
Date: Thu, 1 Apr 2021 10:29:19 +0200
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.7.1
MIME-Version: 1.0
In-Reply-To: <2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru>
Content-Type: multipart/mixed;
 boundary="------------67DE22238B6CE2697DD4B7A8"
Content-Language: en-US
Archived-At: 
 <https://www.postgresql.org/message-id/511121ea-613a-6600-b252-5cebaaa3bccf%40purtz.de>
Precedence: bulk

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

On 30.03.21 21:46, Anton Voloshin wrote:
> 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
>
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


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

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>

--------------67DE22238B6CE2697DD4B7A8--