Обсуждение: 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!
On Wed, Jun 24, 2020 at 05:13:05PM +0000, 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 <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
On Thu, 25 Jun 2020 at 10:10, Bruce Momjian <bruce@momjian.us> wrote:
On Wed, Jun 24, 2020 at 05:13:05PM +0000, 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
On Thu, Jun 25, 2020 at 10:17:56AM -0400, Dave Cramer wrote: > > > On Thu, 25 Jun 2020 at 10:10, Bruce Momjian <bruce@momjian.us> wrote: > > On Wed, Jun 24, 2020 at 05:13:05PM +0000, 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 <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
On Thu, Jun 25, 2020 at 11:41 AM Bruce Momjian <bruce@momjian.us> 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 <bruce@momjian.us> 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 <bruce@momjian.us> https://momjian.us
> EnterpriseDB https://enterprisedb.com
>
> The usefulness of a cup is in its emptiness, Bruce Lee
>
>
--
Bruce Momjian <bruce@momjian.us> 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).
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 Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
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 <bruce@momjian.us> https://momjian.us EnterpriseDB https://enterprisedb.com The usefulness of a cup is in its emptiness, Bruce Lee
On Thu, Jun 25, 2020 at 12:25 PM Bruce Momjian <bruce@momjian.us> 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 <bruce@momjian.us> 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
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 Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services