Re: wrong output column title in example
> On 21 Jun 2020, at 21:07, Erik Rijkers wrote: > > On 2020-06-21 18:21, PG Doc comments form wrote: >> The following documentation comment has been logged on the website: >> Page: https://www.postgresql.org/docs/12/arrays.html >> Description: >> In the last code block in "8.15.5. Searching in Arrays", the column title in >> the output is "array_positions" for both examples, but it should be >> "array_position" for the second example. > > Here is a doc fix/patch. While clearly in nitpicking territory, this isn't entirelty right either as the number of dashes needs to be updated to reflect the attr name. Looking it, the output also has incorrect indentation and lacks the "(1 row)" stanza which we tend to include when showing psql output as . The attached fixes these things too. cheers ./daniel array_position.diff Description: Binary data
Please add a link to [BRIN] physical block ranges of a table
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/indexes-types.html Description: Can you please add a link to an explanation for physical block ranges of a table under the BRIN index. This is not explained in the index and might be confusing to new users. Thanks!
listing roles
The following documentation comment has been logged on the website: Page: https://www.postgresql.org/docs/12/user-manag.html Description: Thank you for perfect documentation. I am missing in chapter 21 (Database roles) a section about *listing roles* both as psql commands and selects to catalogue or pg functions. E.g. to answer question like What roles is CURRENT_USER member of?
Re: Please add a link to [BRIN] physical block ranges of a table
On Wed, Jun 24, 2020 at 05:13:05PM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/indexes-types.html > Description: > > Can you please add a link to an explanation for physical block ranges of a > table under the BRIN index. This is not explained in the index and might be > confusing to new users. > Thanks! Uh, I am confused. The last sentence of that page says: The BRIN operator classes included in the standard distribution are documented in Table 67.1. For more information see Chapter 67. Did you want a link earlier in the section? -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: Please add a link to [BRIN] physical block ranges of a table
On Thu, 25 Jun 2020 at 10:10, Bruce Momjian wrote: > On Wed, Jun 24, 2020 at 05:13:05PM +, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > > > Page: https://www.postgresql.org/docs/12/indexes-types.html > > Description: > > > > Can you please add a link to an explanation for physical block ranges > of a > > table under the BRIN index. This is not explained in the index and might > be > > confusing to new users. > > Thanks! > > Uh, I am confused. The last sentence of that page says: > > The BRIN operator classes included in the standard distribution are > documented in Table 67.1. For more information see Chapter 67. > > > Did you want a link earlier in the section? > Is there a way to make it a clickable link ? Dave
Re: Please add a link to [BRIN] physical block ranges of a table
On Thu, Jun 25, 2020 at 10:17:56AM -0400, Dave Cramer wrote: > > > On Thu, 25 Jun 2020 at 10:10, Bruce Momjian wrote: > > On Wed, Jun 24, 2020 at 05:13:05PM +, PG Doc comments form wrote: > > The following documentation comment has been logged on the website: > > > > Page: https://www.postgresql.org/docs/12/indexes-types.html > > Description: > > > > Can you please add a link to an explanation for physical block ranges > of > a > > table under the BRIN index. This is not explained in the index and might > be > > confusing to new users. > > Thanks! > > Uh, I am confused. The last sentence of that page says: > > The BRIN operator classes included in the standard distribution > are > documented in Table 67.1. For more information see Chapter 67. > > > Did you want a link earlier in the section? > > > Is there a way to make it a clickable link ? Uh, if I am here: https://www.postgresql.org/docs/12/indexes-types.html and I click on the text "Chapter 67." in the sentence: For more information see Chapter 67. it takes me to Chapter 67. Is that what you want? You want "physical block ranges" to be clickable? -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: listing roles
On Wed, Jun 24, 2020 at 05:33:00PM +, PG Doc comments form wrote: > The following documentation comment has been logged on the website: > > Page: https://www.postgresql.org/docs/12/user-manag.html > Description: > > Thank you for perfect documentation. > I am missing in chapter 21 (Database roles) a section about *listing roles* > both as psql commands and selects to catalogue or pg functions. E.g. to > answer question like What roles is CURRENT_USER member of? Well, we _could_ sprinkle psql backslash commands in all the places that reference backslash command features, but that would make the text awkward. psql \du does show you want you wanted. -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: wrong output column title in example
Daniel Gustafsson writes: > On 21 Jun 2020, at 21:07, Erik Rijkers wrote: >> Here is a doc fix/patch. > While clearly in nitpicking territory, this isn't entirelty right either as > the > number of dashes needs to be updated to reflect the attr name. Looking it, > the > output also has incorrect indentation and lacks the "(1 row)" stanza which we > tend to include when showing psql output as . The attached > fixes these things too. Pushed to HEAD and v13. (The error seems old, but it's also so trivial that it didn't seem worth pushing further back.) regards, tom lane
Re: Please add a link to [BRIN] physical block ranges of a table
On Thu, Jun 25, 2020 at 11:41 AM Bruce Momjian wrote: > On Thu, Jun 25, 2020 at 11:39:46AM -0700, Steven Pousty wrote: > > A journey of a thousand miles can start with one step :D > > Yeah, but we have to have consistency. We would need to get approval to > do it in all relevent places, and get someone to do the work. > > --- > > > > > > On Thu, Jun 25, 2020 at 8:45 AM Bruce Momjian wrote: > > > > On Thu, Jun 25, 2020 at 08:37:15AM -0700, Steven Pousty wrote: > > > I was hoping we could turn the words "physical block range" into a > link > > to > > > something like this. > > > https://datacadamia.com/io/drive/sector > > > > > > The idea is to give inexperienced readers access directly to the > > information at > > > the time of reading. > > > > Got it. I do that very often in my blog entries, but we don't do it > > much in the Postgres documentation --- not sure why, but if we did, > we > > would have to do it in a lot more places than just here. > > > > -- > > Bruce Momjian https://momjian.us > > EnterpriseDB https://enterprisedb.com > > > > The usefulness of a cup is in its emptiness, Bruce Lee > > > > > > -- > Bruce Momjian https://momjian.us > EnterpriseDB https://enterprisedb.com > > The usefulness of a cup is in its emptiness, Bruce Lee > > Sorry I forgot to reply all in my original thread. Really, we would have to do all the places at once or slowly add over time. I feel like if it has to be all the places at once we can never make some changes to fix the doc. We have too large of a corpus of doc to try something like this all at once without some herculean effort (or a dedicated doc team).
Re: Please add a link to [BRIN] physical block ranges of a table
We have a glossary page as of Postgres 13[1]; since it's new, links to it have not yet percolated to the rest of the docs, but that should start happening in the pg14 cycle. You're welcome to submit a patch that adds the term you want to link as well as a patch that turns the text you want into a link to that term. A thing I would really like to do is turn the terms in the acronyms section into links to the glossary section, where those terms can be properly defined and where the links can appear. For example now that we have the term "transactions per second" we could add it to acronyms. [1] https://www.postgresql.org/docs/13/glossary.html -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Please add a link to [BRIN] physical block ranges of a table
On Thu, Jun 25, 2020 at 03:12:44PM -0400, Alvaro Herrera wrote: > We have a glossary page as of Postgres 13[1]; since it's new, links to it > have not yet percolated to the rest of the docs, but that should start > happening in the pg14 cycle. > > You're welcome to submit a patch that adds the term you want to link as > well as a patch that turns the text you want into a link to that term. > > A thing I would really like to do is turn the terms in the acronyms > section into links to the glossary section, where those terms can be > properly defined and where the links can appear. For example now that > we have the term "transactions per second" we could add it to acronyms. Yes, this is a great direction to go in! -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
Re: Please add a link to [BRIN] physical block ranges of a table
On Thu, Jun 25, 2020 at 12:25 PM Bruce Momjian wrote: > On Thu, Jun 25, 2020 at 03:12:44PM -0400, Alvaro Herrera wrote: > > We have a glossary page as of Postgres 13[1]; since it's new, links to it > > have not yet percolated to the rest of the docs, but that should start > > happening in the pg14 cycle. > > > > You're welcome to submit a patch that adds the term you want to link as > > well as a patch that turns the text you want into a link to that term. > > > > A thing I would really like to do is turn the terms in the acronyms > > section into links to the glossary section, where those terms can be > > properly defined and where the links can appear. For example now that > > we have the term "transactions per second" we could add it to acronyms. > > Yes, this is a great direction to go in! > > -- > Bruce Momjian https://momjian.us > EnterpriseDB https://enterprisedb.com > > The usefulness of a cup is in its emptiness, Bruce Lee > > I like the direction as well as long as each of the items in the glossary has an anchor and you can link to it from the rest of the documents. The reader, if they are confused by the term, should be able to go get a quick definition without having to remember there is a glossary and then search for the term. I think you actually said that but I want to confirm. If so then you would like me to: 1. Add the text " physical block range " to acronym page 2. Make it anchor so I can link to it directly 3. Add the definition, which can include links to external sites 4. Then turn the link on the original page to the anchor I created for Physical block range. Is that the correct flow? Will this require me building all the docs on my machine? Thanks Steve
Re: Please add a link to [BRIN] physical block ranges of a table
On 2020-Jun-25, Steven Pousty wrote: > I like the direction as well as long as each of the items in the glossary > has an anchor and you can link to it from the rest of the documents. It has. > The reader, if they are confused by the term, should be able to go get > a quick definition without having to remember there is a glossary and > then search for the term. I cannot help people with incurable ADHD, so I hope your readers can achieve clicking a page, reading the definition they're interested in, and going back to whatever page they were reading originally. If they're too easily distracted reading the rest of the glossary, they may never return to the original page anyway. > I think you actually said that but I want to confirm. If so then you would > like me to: > 1. Add the text " physical block range " to acronym page Yes. > 2. Make it anchor so I can link to it directly If you follow the neighboring terms layout, this should be painless. > 3. Add the definition, which can include links to external sites Yes. What external sites are you thinking of, particularly to define the BRIN terms? > 4. Then turn the link on the original page to the anchor I created for > Physical block range. Yes. > Is that the correct flow? Will this require me building all the docs on my > machine? I think the chances of people editing the DocBook sources with zero mistakes without a way to compile them is very close to zero, so yes. -- Álvaro Herrerahttps://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: Not using suppress_redundant_updates_trigger in sql-createtrigger.html#examples
On Tue, Jun 16, 2020 at 02:02:20PM -0400, Tom Lane wrote: > Bruce Momjian writes: > > OK, I didn't think there was enough desire to put it its own paragraph, > > but I like the idea of mentioning all of the trigger functions; patch > > attached. > > This one WFM. Patch applied to all supported versions. -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
