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

On Tue, 2021-03-30 at 22:46 +0300, Anton Voloshin wrote:

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

+1

Yours,
Laurenz Albe

On 31.03.2021 12:48, Laurenz Albe wrote:

On Tue, 2021-03-30 at 22:46 +0300, Anton Voloshin wrote:

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

Thanks! Should I do something to ensure this doc patch getting committed
to Postgres? Or will it be picked up from my [1]/messages/by-id/2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru original email by some
committer without any further efforts from my side?

[1]: /messages/by-id/2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru
/messages/by-id/2ea65bdf-1380-f088-02bd-ff1a31ed265c@postgrespro.ru

--
Anton Voloshin
Postgres Professional: https://www.postgrespro.com
Russian Postgres Company

On Thu, 2021-04-01 at 09:54 +0300, Anton Voloshin wrote:

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?

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

On 01.04.2021 10:46, Laurenz Albe wrote:

The committers are currently busy with the commitfest.

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/

--
Anton Voloshin
Postgres Professional: https://www.postgrespro.com
Russian Postgres Company

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

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!

--
Anton Voloshin
Postgres Professional: https://www.postgrespro.com
Russian Postgres Company

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

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

On Fri, 2021-07-23 at 23:07 +0200, Jürgen Purtz wrote:

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.

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

Yours,
Laurenz Albe

Laurenz Albe <laurenz.albe@cybertec.at> writes:

On Fri, 2021-07-23 at 23:07 +0200, Jürgen Purtz wrote:

Done at the proposed pages - and a few more.

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