Horton

Thread

Commits

  1. Doc: add a glossary entry for "domain".

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

    Anton Voloshin <a.voloshin@postgrespro.ru> — 2021-03-30T19:46:34Z

    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

  2. Re: [PATCH] add link to domain data types section from locale documentation

    Laurenz Albe <laurenz.albe@cybertec.at> — 2021-03-31T09:48:48Z

    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

  3. Re: [PATCH] add link to domain data types section from locale documentation

    Anton Voloshin <a.voloshin@postgrespro.ru> — 2021-04-01T06:54:27Z

    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

  4. Re: [PATCH] add link to domain data types section from locale documentation

    Laurenz Albe <laurenz.albe@cybertec.at> — 2021-04-01T07:46:10Z

    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

  5. Re: [PATCH] add link to domain data types section from locale documentation

    Anton Voloshin <a.voloshin@postgrespro.ru> — 2021-04-01T08:00:38Z

    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

  6. Re: [PATCH] add link to domain data types section from locale documentation

    Jürgen Purtz <juergen@purtz.de> — 2021-04-01T08:29:19Z

    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

  7. Re: [PATCH] add link to domain data types section from locale documentation

    Anton Voloshin <a.voloshin@postgrespro.ru> — 2021-04-01T08:45:50Z

    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

  8. Re: [PATCH] add link to domain data types section from locale documentation

    Laurenz Albe <laurenz.albe@cybertec.at> — 2021-05-27T07:45:27Z

    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

  9. Re: [PATCH] add link to domain data types section from locale documentation

    Jürgen Purtz <juergen@purtz.de> — 2021-07-23T21:07:54Z

    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

  10. Re: [PATCH] add link to domain data types section from locale documentation

    Laurenz Albe <laurenz.albe@cybertec.at> — 2021-07-30T03:58:57Z

    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

  11. Re: [PATCH] add link to domain data types section from locale documentation

    Tom Lane <tgl@sss.pgh.pa.us> — 2021-07-30T19:05:08Z

    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