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/sectorThe 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.comThe usefulness of a cup is in its emptiness, Bruce Lee
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EnterpriseDB https://enterprisedb.comThe 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).
Import Notes
Reply to msg id not found: 20200625184153.GF12490@momjian.us
We have a glossary page as of Postgres 13[1]https://www.postgresql.org/docs/13/glossary.html; 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.comThe 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