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

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

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

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

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