pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedPlease add a link to [BRIN] physical block ranges of a table
9+ messages / 5 participants
[nested] [flat]
* Please add a link to [BRIN] physical block ranges of a table
@ 2020-06-24 17:13 PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 9+ messages in thread
From: PG Doc comments form @ 2020-06-24 17:13 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: steve.pousty@gmail.com
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!
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
@ 2020-06-25 14:10 ` Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
0 siblings, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2020-06-25 14:10 UTC (permalink / raw)
To: steve.pousty@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
@ 2020-06-25 14:17 ` Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 9+ messages in thread
From: Dave Cramer @ 2020-06-25 14:17 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: steve.pousty@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
@ 2020-06-25 14:43 ` Bruce Momjian <bruce@momjian.us>
2020-06-25 18:47 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2020-06-25 14:43 UTC (permalink / raw)
To: Dave Cramer <davecramer@postgres.rocks>; +Cc: steve.pousty@gmail.com; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
@ 2020-06-25 18:47 ` Steven Pousty <steve.pousty@gmail.com>
2020-06-25 19:12 ` Re: Please add a link to [BRIN] physical block ranges of a table Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 1 reply; 9+ messages in thread
From: Steven Pousty @ 2020-06-25 18:47 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: pgsql-docs@lists.postgresql.org
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).
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 18:47 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
@ 2020-06-25 19:12 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-25 19:25 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
0 siblings, 1 reply; 9+ messages in thread
From: Alvaro Herrera @ 2020-06-25 19:12 UTC (permalink / raw)
To: Steven Pousty <steve.pousty@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 18:47 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
2020-06-25 19:12 ` Re: Please add a link to [BRIN] physical block ranges of a table Alvaro Herrera <alvherre@2ndquadrant.com>
@ 2020-06-25 19:25 ` Bruce Momjian <bruce@momjian.us>
2020-06-25 19:32 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
0 siblings, 1 reply; 9+ messages in thread
From: Bruce Momjian @ 2020-06-25 19:25 UTC (permalink / raw)
To: Alvaro Herrera <alvherre@2ndquadrant.com>; +Cc: Steven Pousty <steve.pousty@gmail.com>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 18:47 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
2020-06-25 19:12 ` Re: Please add a link to [BRIN] physical block ranges of a table Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-25 19:25 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
@ 2020-06-25 19:32 ` Steven Pousty <steve.pousty@gmail.com>
2020-06-25 20:02 ` Re: Please add a link to [BRIN] physical block ranges of a table Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 1 reply; 9+ messages in thread
From: Steven Pousty @ 2020-06-25 19:32 UTC (permalink / raw)
To: Bruce Momjian <bruce@momjian.us>; +Cc: Alvaro Herrera <alvherre@2ndquadrant.com>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
* Re: Please add a link to [BRIN] physical block ranges of a table
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Re: Please add a link to [BRIN] physical block ranges of a table Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 18:47 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
2020-06-25 19:12 ` Re: Please add a link to [BRIN] physical block ranges of a table Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-25 19:25 ` Re: Please add a link to [BRIN] physical block ranges of a table Bruce Momjian <bruce@momjian.us>
2020-06-25 19:32 ` Re: Please add a link to [BRIN] physical block ranges of a table Steven Pousty <steve.pousty@gmail.com>
@ 2020-06-25 20:02 ` Alvaro Herrera <alvherre@2ndquadrant.com>
0 siblings, 0 replies; 9+ messages in thread
From: Alvaro Herrera @ 2020-06-25 20:02 UTC (permalink / raw)
To: Steven Pousty <steve.pousty@gmail.com>; +Cc: Bruce Momjian <bruce@momjian.us>; pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 9+ messages in thread
end of thread, other threads:[~2020-06-25 20:02 UTC | newest]
Thread overview: 9+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-06-24 17:13 Please add a link to [BRIN] physical block ranges of a table PG Doc comments form <noreply@postgresql.org>
2020-06-25 14:10 ` Bruce Momjian <bruce@momjian.us>
2020-06-25 14:17 ` Dave Cramer <davecramer@postgres.rocks>
2020-06-25 14:43 ` Bruce Momjian <bruce@momjian.us>
2020-06-25 18:47 ` Steven Pousty <steve.pousty@gmail.com>
2020-06-25 19:12 ` Alvaro Herrera <alvherre@2ndquadrant.com>
2020-06-25 19:25 ` Bruce Momjian <bruce@momjian.us>
2020-06-25 19:32 ` Steven Pousty <steve.pousty@gmail.com>
2020-06-25 20:02 ` Alvaro Herrera <alvherre@2ndquadrant.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox