Re: [PATCH] Missing links between system catalog documentation pages
On 2020-09-03 17:40, Dagfinn Ilmari Mannsåker wrote: I just noticed that both this and the command link patch modified the same sentence about CREATE DATABASE and pg_database, so those changes seem to have been lost in the merge. Attached is a follow-up patch that adds them both. I think in those cases I would leave off the link. The mentions there are just examples of the relationship between a catalog and a command. It doesn't mean you are meant to look up the specific catalog and command. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: [PATCH] Missing links between system catalog documentation pages
Hi Peter, Peter Eisentraut writes: > On 2020-06-21 19:49, Dagfinn Ilmari Mannsåker wrote: >> There were only three cases of multiple mentions of the same table in a >> single paragraph, I've removed them in the attached patch. >> >> I've also added a second patch that makes the SQL commands links. There >> were some cases of the same commands being mentioned in the descriptions >> of multiple columns in the same table, but I've left those in place, >> since that feels less disruptive than in prose. > > Committed after some rebasing and tweaking. Thanks! I just noticed that both this and the command link patch modified the same sentence about CREATE DATABASE and pg_database, so those changes seem to have been lost in the merge. Attached is a follow-up patch that adds them both. - ilmari -- "The surreality of the universe tends towards a maximum" -- Skud's Law "Never formulate a law or axiom that you're not prepared to live with the consequences of." -- Skud's Meta-Law >From d043e64c925a21d42bfd28e6c4ca2e44e4b4d356 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= Date: Sun, 24 May 2020 21:48:29 +0100 Subject: [PATCH] Add two more missing command and catalog cross-links The two earlier doc patches both modified this paragraph, so these two changes appear to have been lost while resolving the conflict. --- doc/src/sgml/catalogs.sgml | 15 --- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 508bea3bc6..6f2e0d19dc 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -14,13 +14,14 @@ tables. You can drop and recreate the tables, add columns, insert and update values, and severely mess up your system that way. Normally, one should not change the system catalogs by hand, there - are normally SQL commands to do that. (For example, CREATE - DATABASE inserts a row into the - pg_database catalog — and actually - creates the database on disk.) There are some exceptions for - particularly esoteric operations, but many of those have been made - available as SQL commands over time, and so the need for direct manipulation - of the system catalogs is ever decreasing. + are normally SQL commands to do that. (For example, inserts a row into the pg_database + catalog — and actually creates the database on disk.) There + are some exceptions for particularly esoteric operations, but many + of those have been made available as SQL commands over time, and so + the need for direct manipulation of the system catalogs is ever + decreasing. -- 2.27.0
Re: [PATCH] Missing links between system catalog documentation pages
On 2020-06-21 19:49, Dagfinn Ilmari Mannsåker wrote: There were only three cases of multiple mentions of the same table in a single paragraph, I've removed them in the attached patch. I've also added a second patch that makes the SQL commands links. There were some cases of the same commands being mentioned in the descriptions of multiple columns in the same table, but I've left those in place, since that feels less disruptive than in prose. Committed after some rebasing and tweaking. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: [PATCH] Missing links between system catalog documentation pages
Hello Tom, I didn't think there was much point in linkifying both in that case, and other similar situations. The point is that the user reads a sentence, attempts to jump but sometimes can't, because the is not the first occurrence. I'd go for all mentions of another relation should be link. That has not been our practice up to now, eg in comparable cases in discussions of GUC variables, only the first reference is xref-ified. I think it could be kind of annoying to make every reference a link, both for regular readers (the link decoration is too bold in most browsers) Hmmm. That looks like an underlying CSS issue, not that links are intrinsically bad. I find it annoying that the same thing appears differently from one line to the next. It seems I'm the only one who likes things to be uniform, though. and for users of screen-reader software. I do not know about those, and what constraints it puts on markup. -- Fabien.
Re: [PATCH] Missing links between system catalog documentation pages
Alvaro Herrera writes: > On 2020-Jun-21, Tom Lane wrote: > >> That has not been our practice up to now, eg in comparable cases in >> discussions of GUC variables, only the first reference is xref-ified. >> I think it could be kind of annoying to make every reference a link, >> both for regular readers (the link decoration is too bold in most >> browsers) and for users of screen-reader software. > > In the glossary I also changed things so that only the first reference > of a term in another term's definition is linked; my experience reading > the originals as submitted (which did link them all at some point) is > that the extra links are very distracting, bad for readability. So +1 > for not adding links to every single mention. There were only three cases of multiple mentions of the same table in a single paragraph, I've removed them in the attached patch. I've also added a second patch that makes the SQL commands links. There were some cases of the same commands being mentioned in the descriptions of multiple columns in the same table, but I've left those in place, since that feels less disruptive than in prose. >> There is a fair question as to how far apart two references should >> be before we both of them. But I think that distance >> does need to be more than zero, and probably more than one para. > > Nod. I tend to agree. - ilmari -- "A disappointingly low fraction of the human race is, at any given time, on fire." - Stig Sandbeck Mathisen >From 165c4aa4613d572a0547a2f2d01dcf06dfa93a24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= Date: Sun, 24 May 2020 21:48:29 +0100 Subject: [PATCH v3 1/2] Add missing cross-links in system catalog documentation This makes the first mention of a system catalog or view in each paragraph in the system system catalog and view documentation pages hyperlinks, for easier navigation. Also linkify the first mention of pg_hba.conf in pg_hba_file_rules, as that's more specific and easier to spot than the link to the client authentication chapter at the bottom. --- doc/src/sgml/catalogs.sgml | 140 - 1 file changed, 77 insertions(+), 63 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 700271fd40..47d78d2ff8 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -16,7 +16,8 @@ Normally, one should not change the system catalogs by hand, there are normally SQL commands to do that. (For example, CREATE DATABASE inserts a row into the - pg_database catalog — and actually + pg_database + catalog — and actually creates the database on disk.) There are some exceptions for particularly esoteric operations, but many of those have been made available as SQL commands over time, and so the need for direct manipulation @@ -381,9 +382,10 @@ sum, count, and max. Each entry in pg_aggregate is an extension of an entry - in pg_proc. The pg_proc - entry carries the aggregate's name, input and output data types, and - other information that is similar to ordinary functions. + in pg_proc. + The pg_proc entry carries the aggregate's name, + input and output data types, and other information that is similar to + ordinary functions. @@ -407,7 +409,7 @@ (references pg_proc.oid) - pg_proc OID of the aggregate function + OID of the aggregate function @@ -902,7 +904,7 @@ catalog structure for performance reasons). Also, amoplefttype and amoprighttype must match the oprleft and oprright fields of the - referenced pg_operator entry. + referenced pg_operator entry. @@ -1099,7 +1101,8 @@ table columns. There will be exactly one pg_attribute row for every column in every table in the database. (There will also be attribute entries for - indexes, and indeed all objects that have pg_class + indexes, and indeed all objects that have + pg_class entries.) @@ -1270,7 +1273,7 @@ This column has a default expression or generation expression, in which case there will be a corresponding entry in the - pg_attrdef catalog that actually defines the + pg_attrdef catalog that actually defines the expression. (Check attgenerated to determine whether this is a default or a generation expression.) @@ -1402,7 +1405,7 @@ In a dropped column's pg_attribute entry, atttypid is reset to zero, but attlen and the other fields copied from - pg_type are still valid. This arrangement is needed + pg_type are still valid. This arrangement is needed to cope with the situation where the dropped column's data type was later dropped, and so there is no pg_type row anymore. attlen and the other fields can be used @@ -1835,14 +1838,16 @@ The catalog pg_class catalogs tables and most - everything else that has columns or is
Re: [PATCH] Missing links between system catalog documentation pages
On 2020-Jun-21, Tom Lane wrote: > That has not been our practice up to now, eg in comparable cases in > discussions of GUC variables, only the first reference is xref-ified. > I think it could be kind of annoying to make every reference a link, > both for regular readers (the link decoration is too bold in most > browsers) and for users of screen-reader software. In the glossary I also changed things so that only the first reference of a term in another term's definition is linked; my experience reading the originals as submitted (which did link them all at some point) is that the extra links are very distracting, bad for readability. So +1 for not adding links to every single mention. > There is a fair question as to how far apart two references should > be before we both of them. But I think that distance > does need to be more than zero, and probably more than one para. Nod. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: [PATCH] Missing links between system catalog documentation pages
Fabien COELHO writes: >> I didn't think there was much point in linkifying both in that case, and >> other similar situations. > The point is that the user reads a sentence, attempts to jump but > sometimes can't, because the is not the first occurrence. I'd go for all > mentions of another relation should be link. That has not been our practice up to now, eg in comparable cases in discussions of GUC variables, only the first reference is xref-ified. I think it could be kind of annoying to make every reference a link, both for regular readers (the link decoration is too bold in most browsers) and for users of screen-reader software. There is a fair question as to how far apart two references should be before we both of them. But I think that distance does need to be more than zero, and probably more than one para. regards, tom lane
Re: [PATCH] Missing links between system catalog documentation pages
Hi Fabien, Fabien COELHO writes: >> It's the first mention in the introductory paragraph of _each_ catalog >> table/view page, not the first mention in the entire catalogs.sgml file. >> E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html >> has two mentions of pg_proc one word apart: >> >> Each entry in pg_aggregate is an extension of an entry in pg_proc. The >> pg_proc entry carries the aggregate's name, … >> >> I didn't think there was much point in linkifying both in that case, and >> other similar situations. > > The point is that the user reads a sentence, attempts to jump but > sometimes can't, because the is not the first occurrence. I'd go for all > mentions of another relation should be link. Okay, I'll make them all links, except the pg_aggregate aggfnoid column, which I've changed from "pg_proc OID of the aggregate function" to just "OID of the agregate function", since pg_proc is linked immediately prior in the "references" section, and we generally don't mention the catalog table again in similar cases elsehwere. > Alse, ISTM you missed some, maybe you could consider adding them? eg > pg_database in the very first paragraph of the file, pg_attrdef in > pg_attribute description, quite a few in pg_class… Yes, I only looked at the intro paragraphs of the per-catalog pages, not the overview section nor the text after the column tables. I've gone through them all now and linked them. Updated patch attached. - ilmari -- "A disappointingly low fraction of the human race is, at any given time, on fire." - Stig Sandbeck Mathisen >From b2940b93f5ed17c0e739d6ed0c9411a44bd87428 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dagfinn=20Ilmari=20Manns=C3=A5ker?= Date: Sun, 24 May 2020 21:48:29 +0100 Subject: [PATCH v2 1/2] Add missing cross-links in system catalog documentation This makes all mentions of other system catalogs and views in the system system catalog and view documentation pages hyperlinks, for easier navigation. Also linkify the first mention of pg_hba.conf in pg_hba_file_rules, as that's more specific and easier to spot than the link to the client authentication chapter at the bottom. --- doc/src/sgml/catalogs.sgml | 142 - 1 file changed, 78 insertions(+), 64 deletions(-) diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 700271fd40..051fa7d361 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -16,7 +16,8 @@ Normally, one should not change the system catalogs by hand, there are normally SQL commands to do that. (For example, CREATE DATABASE inserts a row into the - pg_database catalog — and actually + pg_database + catalog — and actually creates the database on disk.) There are some exceptions for particularly esoteric operations, but many of those have been made available as SQL commands over time, and so the need for direct manipulation @@ -381,9 +382,10 @@ sum, count, and max. Each entry in pg_aggregate is an extension of an entry - in pg_proc. The pg_proc - entry carries the aggregate's name, input and output data types, and - other information that is similar to ordinary functions. + in pg_proc. + The pg_proc entry carries the aggregate's name, + input and output data types, and other information that is similar to + ordinary functions. @@ -407,7 +409,7 @@ (references pg_proc.oid) - pg_proc OID of the aggregate function + OID of the aggregate function @@ -902,7 +904,7 @@ catalog structure for performance reasons). Also, amoplefttype and amoprighttype must match the oprleft and oprright fields of the - referenced pg_operator entry. + referenced pg_operator entry. @@ -1099,7 +1101,8 @@ table columns. There will be exactly one pg_attribute row for every column in every table in the database. (There will also be attribute entries for - indexes, and indeed all objects that have pg_class + indexes, and indeed all objects that have + pg_class entries.) @@ -1270,7 +1273,7 @@ This column has a default expression or generation expression, in which case there will be a corresponding entry in the - pg_attrdef catalog that actually defines the + pg_attrdef catalog that actually defines the expression. (Check attgenerated to determine whether this is a default or a generation expression.) @@ -1402,9 +1405,9 @@ In a dropped column's pg_attribute entry, atttypid is reset to zero, but attlen and the other fields copied from - pg_type are still valid. This arrangement is needed + pg_type are still valid. This arrangement is needed to cope with the situation where the dropped column's data type was - later dropped, and so there is no pg_type row anymore. + later dropped, and so there is no pg_type row anymore. attlen and
Re: [PATCH] Missing links between system catalog documentation pages
Hello Dagfinn, The attached patch applies cleanly, doc generation is ok. I'm ok with adding such links systematically. makes the first mention of another system catalog or view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier navigation. Why only the first mention? It seems unlikely that I would ever read such chapter linearly, and even so that I would want to jump especially on the first occurrence but not on others, so ISTM that it should be done all mentions? It's the first mention in the introductory paragraph of _each_ catalog table/view page, not the first mention in the entire catalogs.sgml file. E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html has two mentions of pg_proc one word apart: Each entry in pg_aggregate is an extension of an entry in pg_proc. The pg_proc entry carries the aggregate's name, … I didn't think there was much point in linkifying both in that case, and other similar situations. The point is that the user reads a sentence, attempts to jump but sometimes can't, because the is not the first occurrence. I'd go for all mentions of another relation should be link. Alse, ISTM you missed some, maybe you could consider adding them? eg pg_database in the very first paragraph of the file, pg_attrdef in pg_attribute description, quite a few in pg_class… -- Fabien.
Re: [PATCH] Missing links between system catalog documentation pages
Fabien COELHO writes: > Hello Dagfinn, > >>> The attached patch makes the first mention of another system catalog or >>> view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier >>> navigation. > > Why only the first mention? It seems unlikely that I would ever read > such chapter linearly, and even so that I would want to jump especially > on the first occurrence but not on others, so ISTM that it should be > done all mentions? It's the first mention in the introductory paragraph of _each_ catalog table/view page, not the first mention in the entire catalogs.sgml file. E.g. https://www.postgresql.org/docs/current/catalog-pg-aggregate.html has two mentions of pg_proc one word apart: Each entry in pg_aggregate is an extension of an entry in pg_proc. The pg_proc entry carries the aggregate's name, … I didn't think there was much point in linkifying both in that case, and other similar situations. - ilmari -- "A disappointingly low fraction of the human race is, at any given time, on fire." - Stig Sandbeck Mathisen
Re: [PATCH] Missing links between system catalog documentation pages
Hello Dagfinn, The attached patch makes the first mention of another system catalog or view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier navigation. Why only the first mention? It seems unlikely that I would ever read such chapter linearly, and even so that I would want to jump especially on the first occurrence but not on others, so ISTM that it should be done all mentions? -- Fabien.
Re: [PATCH] Missing links between system catalog documentation pages
ilm...@ilmari.org (Dagfinn Ilmari Mannsåker) writes: > ilm...@ilmari.org (Dagfinn Ilmari Mannsåker) writes: > >> The attached patch makes the first mention of another system catalog or >> view (as well as pg_hba.conf in pg_hba_file_lines) a link, for easier >> navigation. > > bump... Added to the current commitfest: https://commitfest.postgresql.org/28/2599/ - ilmari -- - Twitter seems more influential [than blogs] in the 'gets reported in the mainstream press' sense at least. - Matt McLeod - That'd be because the content of a tweet is easier to condense down to a mainstream media article. - Calle Dybedahl
