Date: Thu, 25 Jun 2020 16:02:12 -0400
From: Alvaro Herrera <alvherre@2ndquadrant.com>
To: Steven Pousty <steve.pousty@gmail.com>
Cc: Bruce Momjian <bruce@momjian.us>, pgsql-docs@lists.postgresql.org
Subject: Re: Please add a link to [BRIN] physical block ranges of a table
Message-ID: <20200625200212.GA1570@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: 
 <CAKmB1PENqVmuZPyUAx5O5L-h90ExKSn4N1PuHf1tn_1upUnZrw@mail.gmail.com>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

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