Re: three small improvements for "Composite Types" page
On 12/04/2024 23:44, David G. Johnston wrote: I'd much prefer to leave "different kind" alone and turn the immediately following, first-on-the-page, instance of CREATE TYPE into a link. Good, I'm fine with that too. 2. make first mention of CREATE TABLE a link [...] > I'm not all that convinced of that particular usefulness but also don't see it hurting either. Thanks. I do think it's useful when one reads this page separately (not as a part of sequential read-through). 3. Simplify CREATE TABLE example to make it self-sufficient [...] Agreed. Thanks. I've updated the patches correspondingly. -- Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ruFrom dddf7ee4a9a22515c327434b7db2c0293301b257 Mon Sep 17 00:00:00 2001 From: Anton Voloshin Date: Fri, 12 Apr 2024 22:49:17 +0300 Subject: [PATCH 1/3] Composite Types: clarify "different kind" by linking to a "create type" page --- doc/src/sgml/rowtypes.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index bbeac84d46a..049e90e9c68 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -40,7 +40,7 @@ CREATE TYPE inventory_item AS ( field names and types can be specified; no constraints (such as NOT NULL) can presently be included. Note that the AS keyword is essential; without it, the system will think a different kind - of CREATE TYPE command is meant, and you will get odd syntax + of command is meant, and you will get odd syntax errors. -- 2.43.2 From def3f7ccb55b44e63b2a9fffa88ba4d3c545e553 Mon Sep 17 00:00:00 2001 From: Anton Voloshin Date: Fri, 12 Apr 2024 22:56:18 +0300 Subject: [PATCH 2/3] Composite Types: make first mention of CREATE TABLE a link --- doc/src/sgml/rowtypes.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index 049e90e9c68..a409b292795 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -36,7 +36,7 @@ CREATE TYPE inventory_item AS ( price numeric ); - The syntax is comparable to CREATE TABLE, except that only + The syntax is comparable to , except that only field names and types can be specified; no constraints (such as NOT NULL) can presently be included. Note that the AS keyword is essential; without it, the system will think a different kind -- 2.43.2 From bbda6a20a387cd6b1379b760de0e215851e638a9 Mon Sep 17 00:00:00 2001 From: Anton Voloshin Date: Fri, 12 Apr 2024 22:58:45 +0300 Subject: [PATCH 3/3] Composite Types: simplify CREATE TABLE example to make it self-sufficient --- doc/src/sgml/rowtypes.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index a409b292795..b6063b30c31 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -74,7 +74,7 @@ SELECT price_extension(item, 10) FROM on_hand; CREATE TABLE inventory_item ( nametext, -supplier_id integer REFERENCES suppliers, +supplier_id integer, price numeric CHECK (price > 0) ); -- 2.43.2
three small improvements for "Composite Types" page
Hello, While reading "Composite Types" manual page I've noticed that it is somewhat hard to follow by trying out given examples. I suggest three small changes which would make this page a little easier to follow for me: 1. Clarify "different kind" by adding a link to a section of "create type" page > Note that the AS keyword is essential; without it, the system will think a different kind of CREATE TYPE command is meant, and you will get odd syntax errors. Here there is no link to CREATE TYPE, so it's not so easy to go there to see what is that "different kind" of CREATE TYPE. I suggest to add an anchor for the "Base Types" section there and link the words "different kind" there. 2. make first mention of CREATE TABLE a link > The syntax is comparable to CREATE TABLE, except ... It would be useful if this CREATE TABLE (first on this page) would become a link. 3. Simplify CREATE TABLE example to make it self-sufficient One of the examples on the same "Composite Types" page is an example of CREATE TABLE: CREATE TABLE inventory_item ( nametext, supplier_id integer REFERENCES suppliers, price numeric CHECK (price > 0) ); This example is not self-sufficient: it requires one to have "suppliers" table with specific column to work as given. This table is actively used in examples below, like SELECT * FROM inventory_item c ORDER BY c; and many others, so I think it's important to make this example easy to reproduce. It seems to me that loosing "REFERENCES suppliers", while loses something a bit interesting, adds something more important: simplicity for the newcomers. So I suggest removing this part. Please see attached patches as an example of these three changes. Any comments? Do you think this is an improvement? -- Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ruFrom df2a1b5cb323d639bcf75fac6799b89b40dec972 Mon Sep 17 00:00:00 2001 From: Anton Voloshin Date: Fri, 12 Apr 2024 22:49:17 +0300 Subject: [PATCH 1/3] clarify "different kind" by adding a link to a section of "create type" page --- doc/src/sgml/ref/create_type.sgml | 2 +- doc/src/sgml/rowtypes.sgml| 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml index 994dfc65268..b975531864b 100644 --- a/doc/src/sgml/ref/create_type.sgml +++ b/doc/src/sgml/ref/create_type.sgml @@ -188,7 +188,7 @@ CREATE TYPE name - + Base Types diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index bbeac84d46a..9d658a70c41 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -39,7 +39,8 @@ CREATE TYPE inventory_item AS ( The syntax is comparable to CREATE TABLE, except that only field names and types can be specified; no constraints (such as NOT NULL) can presently be included. Note that the AS keyword - is essential; without it, the system will think a different kind + is essential; without it, the system will think a different kind of CREATE TYPE command is meant, and you will get odd syntax errors. -- 2.43.2 From 18ba7e3b722d707442bca2288f1338f5803f396a Mon Sep 17 00:00:00 2001 From: Anton Voloshin Date: Fri, 12 Apr 2024 22:56:18 +0300 Subject: [PATCH 2/3] composite types: make first mention of CREATE TABLE a link --- doc/src/sgml/rowtypes.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index 9d658a70c41..e6ae26a0446 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -36,7 +36,7 @@ CREATE TYPE inventory_item AS ( price numeric ); - The syntax is comparable to CREATE TABLE, except that only + The syntax is comparable to , except that only field names and types can be specified; no constraints (such as NOT NULL) can presently be included. Note that the AS keyword is essential; without it, the system will think a From 38d8dfca22cdb18fc5c9c538fc0433141e8d89ab Mon Sep 17 00:00:00 2001 From: Anton Voloshin Date: Fri, 12 Apr 2024 22:58:45 +0300 Subject: [PATCH 3/3] Composite Types: simplify CREATE TABLE example to make it self-sufficient --- doc/src/sgml/rowtypes.sgml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/sgml/rowtypes.sgml b/doc/src/sgml/rowtypes.sgml index e6ae26a0446..732cc2d7a6e 100644 --- a/doc/src/sgml/rowtypes.sgml +++ b/doc/src/sgml/rowtypes.sgml @@ -75,7 +75,7 @@ SELECT price_extension(item, 10) FROM on_hand; CREATE TABLE inventory_item ( nametext, -supplier_id integer REFERENCES suppliers, +supplier_id integer, price numeric CHECK (price > 0) ); -- 2.43.2
nested tags in glossary entries in html docs
Hello, In REL_13_STABLE and above, generated HTML have a broken HTML: nested href="..."> tags for all links to glossary. Somehow, this results in duplicated tags on the https://www.postgresql.org/docs/ Found by tab-navigating https://www.postgresql.org/docs/16/rowtypes.html where we see (spacing added to avoid line wraps): ... create a href="glossary.html#GLOSSARY-DOMAIN"href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain over the composite type ... So, empty , and then the real . This resulted in stopping twice on the "domain" link (right before, and then on the "domain" word itself) while tab-navigating. If I am to "make html" docs from the source (in REL_13_STABLE..master), I see nested 's instead: create a class="glossterm">href="glossary.html#GLOSSARY-DOMAIN" title="Domain">domain over the composite type I guess docs are processed additionally before getting to https://www.postgresql.org/docs/ (html sanitizer/beautifier?), in passing fixing nested 's, but producing duplicated 's instead. It seems to affect all glossary links: after "make html", grep '' doc/src/sgml/html/*.html results in 254 to 329 matches (in versions 13 to master). REL_12_STABLE is not affected: glossary was only introduced in 13. It seems to have been introduced in commit 347d2b07fcc250680f75b5f89ba49d4805782c6b Author: Alvaro Herrera Date: Fri Apr 3 19:23:20 2020 Add a glossary to the documentation Not sure about how to fix this (don't really know docbook). -- Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ru
operator @@ is not supported by path; doc says otherwise
Hello, The documentation for 13 and 14 says in "Geometric Functions and Operators" https://www.postgresql.org/docs/14/functions-geometry.html: > @@ geometric_type → point > Computes the center point. Available for box, lseg, path, polygon, circle. > @@ box '(2,2),(0,0)' → (1,1) However, apparently, this operator does not work for path: > $ psql > psql (14.1) > Type "help" for help. > > postgres=# SELECT @@ path '[(0,0),(0,1)]'; > ERROR: function "path_center" not implemented > postgres=# Same for a closed path: > postgres=# SELECT @@ path '((0,0),(0,1))'; > ERROR: function "path_center" not implemented Quick tests show that other types listed (box, lseg, polygon, circle) are supported, so only the path is extra. This sentence in the documentation came from 791090bd775b (REL_13_STABLE and later). What slightly confuses me is that path_center has been listed in src/include/catalog/pg_operator.dat and pg_proc.dat (and pg_operator.h/pg_proc.h before that) since 3c2d74d2a (1997!), but since a3d284485 (2018) we have a regression test ensuring that "function "path_center" not implemented". The easiest fix is, obviously, removing 'path' from the list in the documentation. Or, if that would be an actual improvement, I could submit a patch to support a path_center as well. Not sure if there is any actual need for that, though: I found this by just goofing around, not because I actually needed to calculate the center for some path. Also, converting to polygon might be a workaround for those who might need that feature. Please let me know if implementing path_center would be a useful addition. P.S. I've sent a report though a submit web form on a documentation web site two days ago, but, apparently, that email was not delivered to this list. Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ru
broken link to "SELinux guide" from sepgsql
Hello, on https://www.postgresql.org/docs/current/sepgsql.html the "SELinux User's and Administrator's Guide" link to https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/html/SELinux_Users_and_Administrators_Guide/ is broken, leads to 404. Proper URI would be, apparently, https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/index -- Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ru
Re: [PATCH] fix ICU explorer link in locale documentation
On 29/09/2021 17:13, Laurenz Albe wrote: I had a look at that and tried to build the software from source. It requires you to build ICU, and even then it failed to build for me. The build documentation is not very detailed. So I think we should not link to that. I noticed that two more external links have moved. Attached is a patch that fixes those links and removes the link to the locale explorer. +1 from me on both changes. We have to remove the locale explorer link, unfortunately. -- Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ru
Re: [PATCH] fix ICU explorer link in locale documentation
On 18/05/2021 03:46, Magnus Hagander wrote: https://icu4c-demos.unicode.org/icu-bin/locexp generates a 404 for me now. This might be something temporary though, because AFAICT it's where you end up when you follow the links from the ICU git repo... Yes, same 404 for me. This error has been reported on icu-issues mailing list on April 13th [1] and the reply from Stephan Pakebusch was: This demo has been out of date (by several releases) and is being updated for ICU 69. In the meantime there was an issue with this particular demo. We’re looking into the problem you noted. I’m not sure if there’s a tracking issue for this specific, but you can follow the development on https://github.com/unicode-org/icu-demos So I guess the https://icu4c-demos.unicode.org/icu-bin/locexp link is still the proper one, and eventually it will be fixed. Anyway, the old link, https://ssl.icu-project.org/icu-bin/locexp, if one goes through "wrong domain in certificate" errors, still redirects to the same https://icu4c-demos.unicode.org/icu-bin/locexp I believe changing link in Postgres' docs is better than keeping the old one, even though they are currently both 404 one way or another. At least it would save people following that link from scary "Warning: Potential Security Risk Ahead" messages before properly 404-ing. [1] https://sourceforge.net/p/icu/mailman/icu-support/thread/CAD%2BuSKi%3DQeLWiivJmaFBHPg-tH9PjRriTOXxi9t2NQGr3VONww%40mail.gmail.com/#msg37261067 -- Anton Voloshin Postgres Professional, The Russian Postgres Company https://postgrespro.ru
[PATCH] fix ICU explorer link in locale documentation
Hello, Existing Postgres documentation states in doc/src/sgml/charset.sgml: The https://ssl.icu-project.org/icu-bin/locexp";>ICU Locale Explorer can be used to check the details of a particular locale definition. But the link is broken (SSL certificate does not include ssl.icu-project.org as allowed name). Correct link is, I believe, https://icu4c-demos.unicode.org/icu-bin/locexp Attached patch fixes the broken link. -- 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 300a0d83d4..46d19ae39d 100644 --- a/doc/src/sgml/charset.sgml +++ b/doc/src/sgml/charset.sgml @@ -842,7 +842,7 @@ CREATE COLLATION german (provider = libc, locale = 'de_DE'); subtag) can be found in the https://github.com/unicode-org/cldr/blob/master/common/bcp47/collation.xml";>CLDR repository. -The https://ssl.icu-project.org/icu-bin/locexp";>ICU Locale +The https://icu4c-demos.unicode.org/icu-bin/locexp";>ICU Locale Explorer can be used to check the details of a particular locale definition. The examples using the k* subtags require at least ICU version 54.
Re: [PATCH] add link to domain data types section from locale documentation
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
Re: [PATCH] add link to domain data types section from locale documentation
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
Re: [PATCH] add link to domain data types section from locale documentation
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
[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 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 text, varchar, and char. User-defined base types can also be marked collatable, and of course -a domain over a collatable data type is collatable.) If the +a domain 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
