public inbox for [email protected]help / color / mirror / Atom feed
[PATCH] add link to domain data types section from locale documentation 11+ messages / 4 participants [nested] [flat]
* [PATCH] add link to domain data types section from locale documentation @ 2021-03-30 19:46 Anton Voloshin <[email protected]> 0 siblings, 2 replies; 11+ messages in thread From: Anton Voloshin @ 2021-03-30 19:46 UTC (permalink / raw) To: [email protected] 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 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 Attachments: [text/plain] collation-domains-link.patch (795B, 2-collation-domains-link.patch) download | inline diff: 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-03-31 09:48 Laurenz Albe <[email protected]> parent: Anton Voloshin <[email protected]> 1 sibling, 1 reply; 11+ messages in thread From: Laurenz Albe @ 2021-03-31 09:48 UTC (permalink / raw) To: Anton Voloshin <[email protected]>; [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-04-01 06:54 Anton Voloshin <[email protected]> parent: Laurenz Albe <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Anton Voloshin @ 2021-04-01 06:54 UTC (permalink / raw) To: [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-04-01 07:46 Laurenz Albe <[email protected]> parent: Anton Voloshin <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Laurenz Albe @ 2021-04-01 07:46 UTC (permalink / raw) To: Anton Voloshin <[email protected]>; [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-04-01 08:00 Anton Voloshin <[email protected]> parent: Laurenz Albe <[email protected]> 0 siblings, 0 replies; 11+ messages in thread From: Anton Voloshin @ 2021-04-01 08:00 UTC (permalink / raw) To: Laurenz Albe <[email protected]>; [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-04-01 08:29 Jürgen Purtz <[email protected]> parent: Anton Voloshin <[email protected]> 1 sibling, 1 reply; 11+ messages in thread From: Jürgen Purtz @ 2021-04-01 08:29 UTC (permalink / raw) To: [email protected] 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 Attachments: [text/x-patch] collation-domains-link-02.patch (1.6K, 2-collation-domains-link-02.patch) download | inline diff: 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> ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-04-01 08:45 Anton Voloshin <[email protected]> parent: Jürgen Purtz <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Anton Voloshin @ 2021-04-01 08:45 UTC (permalink / raw) To: [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-05-27 07:45 Laurenz Albe <[email protected]> parent: Anton Voloshin <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Laurenz Albe @ 2021-05-27 07:45 UTC (permalink / raw) To: Anton Voloshin <[email protected]>; [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-07-23 21:07 Jürgen Purtz <[email protected]> parent: Laurenz Albe <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Jürgen Purtz @ 2021-07-23 21:07 UTC (permalink / raw) To: Laurenz Albe <[email protected]>; Anton Voloshin <[email protected]>; [email protected] 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 Attachments: [text/x-patch] collation-domains-link-03.patch (7.6K, 2-collation-domains-link-03.patch) download | inline diff: diff --git a/doc/src/sgml/charset.sgml b/doc/src/sgml/charset.sgml index 98df74d0e1..8434bf6ba4 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 <glossterm linkend="glossary-domain-sql">domain</glossterm> 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/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml index 641e69c5e9..f5b60ea612 100644 --- a/doc/src/sgml/earthdistance.sgml +++ b/doc/src/sgml/earthdistance.sgml @@ -50,7 +50,8 @@ <para> Data is stored in cubes that are points (both corners are the same) using 3 coordinates representing the x, y, and z distance from the center of the - Earth. A domain <type>earth</type> over <type>cube</type> is provided, which + Earth. A <glossterm linkend="glossary-domain-sql">domain</glossterm> <type>earth</type> + over <type>cube</type> is provided, which includes constraint checks that the value meets these restrictions and is reasonably close to the actual surface of the Earth. </para> diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index c8d0440e80..0c1176fa07 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -389,9 +389,7 @@ <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>. + or in attributes of a <glossterm linkend="glossary-domain-sql">domain</glossterm>. </para> <para> For more information, see @@ -508,6 +506,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> diff --git a/doc/src/sgml/information_schema.sgml b/doc/src/sgml/information_schema.sgml index 4100198252..13de037b8e 100644 --- a/doc/src/sgml/information_schema.sgml +++ b/doc/src/sgml/information_schema.sgml @@ -912,8 +912,8 @@ <para> The view <literal>check_constraints</literal> contains all check - constraints, either defined on a table or on a domain, that are - owned by a currently enabled role. (The owner of the table or + constraints, either defined on a table or on a <glossterm linkend="glossary-domain-sql">domain</glossterm>, + that are owned by a currently enabled role. (The owner of the table or domain is the owner of the constraint.) </para> @@ -1199,7 +1199,8 @@ <para> The view <literal>column_domain_usage</literal> identifies all - columns (of a table or a view) that make use of some domain defined + columns (of a table or a view) that make use of some + <glossterm linkend="glossary-domain-sql">domain</glossterm> defined in the current database and owned by a currently enabled role. </para> @@ -2307,7 +2308,8 @@ data type descriptors that the current user has access to, by way of being the owner of the described object or having some privilege for it. A data type descriptor is generated whenever a data type - is used in the definition of a table column, a domain, or a + is used in the definition of a table column, a + <glossterm linkend="glossary-domain-sql">domain</glossterm>, or a function (as parameter or return type) and stores some information about how the data type is used in that instance (for example, the declared maximum length, if applicable). Each data type @@ -2393,7 +2395,8 @@ <para> The view <literal>domain_constraints</literal> contains all constraints - belonging to domains defined in the current database. Only those domains + belonging to <glossterm linkend="glossary-domain-sql">domains</glossterm> + defined in the current database. Only those domains are shown that the current user has access to (by way of being the owner or having some privilege). </para> @@ -2445,7 +2448,8 @@ <structfield>domain_catalog</structfield> <type>sql_identifier</type> </para> <para> - Name of the database that contains the domain (always the current database) + Name of the database that contains the <glossterm linkend="glossary-domain-sql">domain</glossterm> + (always the current database) </para></entry> </row> @@ -2493,7 +2497,8 @@ <title><literal>domain_udt_usage</literal></title> <para> - The view <literal>domain_udt_usage</literal> identifies all domains + The view <literal>domain_udt_usage</literal> identifies all + <glossterm linkend="glossary-domain-sql">domains</glossterm> that are based on data types owned by a currently enabled role. Note that in <productname>PostgreSQL</productname>, built-in data types behave like user-defined types, so they are included here as @@ -2577,7 +2582,8 @@ <title><literal>domains</literal></title> <para> - The view <literal>domains</literal> contains all domains defined in the + The view <literal>domains</literal> contains all + <glossterm linkend="glossary-domain-sql">domains</glossterm> defined in the current database. Only those domains are shown that the current user has access to (by way of being the owner or having some privilege). </para> diff --git a/doc/src/sgml/lo.sgml b/doc/src/sgml/lo.sgml index 0a4f2e4449..d77e39ac76 100644 --- a/doc/src/sgml/lo.sgml +++ b/doc/src/sgml/lo.sgml @@ -55,7 +55,8 @@ <para> The module also provides a data type <type>lo</type>, which is really just - a domain of the <type>oid</type> type. This is useful for differentiating + a <glossterm linkend="glossary-domain-sql">domain</glossterm> of the <type>oid</type> type. + This is useful for differentiating database columns that hold large object references from those that are OIDs of other things. You don't have to use the <type>lo</type> type to use the trigger, but it may be convenient to use it to keep track of which diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index a6f4f6709c..222baf9619 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -84,7 +84,8 @@ CREATE TABLE inventory_item ( restriction of the current implementation: since no constraints are associated with a composite type, the constraints shown in the table definition <emphasis>do not apply</emphasis> to values of the composite type - outside the table. (To work around this, create a domain over the composite + outside the table. (To work around this, create a + <glossterm linkend="glossary-domain-sql">domain</glossterm> over the composite type, and apply the desired constraints as <literal>CHECK</literal> constraints of the domain.) </para> ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-07-30 03:58 Laurenz Albe <[email protected]> parent: Jürgen Purtz <[email protected]> 0 siblings, 1 reply; 11+ messages in thread From: Laurenz Albe @ 2021-07-30 03:58 UTC (permalink / raw) To: Jürgen Purtz <[email protected]>; Anton Voloshin <[email protected]>; [email protected] 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
* Re: [PATCH] add link to domain data types section from locale documentation @ 2021-07-30 19:05 Tom Lane <[email protected]> parent: Laurenz Albe <[email protected]> 0 siblings, 0 replies; 11+ messages in thread From: Tom Lane @ 2021-07-30 19:05 UTC (permalink / raw) To: Laurenz Albe <[email protected]>; +Cc: Jürgen Purtz <[email protected]>; Anton Voloshin <[email protected]>; [email protected] Laurenz Albe <[email protected]> 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 ^ permalink raw reply [nested|flat] 11+ messages in thread
end of thread, other threads:[~2021-07-30 19:05 UTC | newest] Thread overview: 11+ messages (download: mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2021-03-30 19:46 [PATCH] add link to domain data types section from locale documentation Anton Voloshin <[email protected]> 2021-03-31 09:48 ` Laurenz Albe <[email protected]> 2021-04-01 06:54 ` Anton Voloshin <[email protected]> 2021-04-01 07:46 ` Laurenz Albe <[email protected]> 2021-04-01 08:00 ` Anton Voloshin <[email protected]> 2021-04-01 08:29 ` Jürgen Purtz <[email protected]> 2021-04-01 08:45 ` Anton Voloshin <[email protected]> 2021-05-27 07:45 ` Laurenz Albe <[email protected]> 2021-07-23 21:07 ` Jürgen Purtz <[email protected]> 2021-07-30 03:58 ` Laurenz Albe <[email protected]> 2021-07-30 19:05 ` Tom Lane <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox