Message-ID: <3b80ddf5a978bf084401e61288210d2fa3e75f37.camel@cybertec.at>
Subject: Re: [PATCH] add link to domain data types section from locale
 documentation
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Anton Voloshin <a.voloshin@postgrespro.ru>,
	pgsql-docs@lists.postgresql.org
Date: Thu, 27 May 2021 09:45:27 +0200
In-Reply-To: <3a0dff3f-9e24-eee2-ee9e-b643b626e7b8@postgrespro.ru>
References: <2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru>
	 <511121ea-613a-6600-b252-5cebaaa3bccf@purtz.de>
	 <3a0dff3f-9e24-eee2-ee9e-b643b626e7b8@postgrespro.ru>
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.36.5 (3.36.5-2.fc32) 
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Archived-At: 
 <https://www.postgresql.org/message-id/3b80ddf5a978bf084401e61288210d2fa3e75f37.camel%40cybertec.at>
Precedence: bulk

On Thu, 2021-04-01 at 11:45 +0300, Anton Voloshin wrote:
> On 01.04.2021 11:29, Jürgen Purtz wrote:
> > 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.
> 
> Nice touch, thanks!

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