Message-ID: <e2d54a1c1cdc80c748dd47f36ff9d6c5e5b75e51.camel@cybertec.at>
Subject: Re: Re[2]: Suggestion for docs, section "4.2.3 Subscripts": bounds
 and base
From: Laurenz Albe <laurenz.albe@cybertec.at>
To: Stefan Schmiedl <s@xss.de>, pgsql-docs@lists.postgresql.org
Date: Mon, 07 Apr 2025 15:16:24 +0200
In-Reply-To: <em751b19af-6abf-4c91-a039-8024c068aed9@c601190c.com>
References: 
	<174370454407.3115968.6902015899222362259@wrigleys.postgresql.org>
	 <488788bd2526cec7eb175741c010cab2fa24fed4.camel@cybertec.at>
	 <em751b19af-6abf-4c91-a039-8024c068aed9@c601190c.com>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
User-Agent: Evolution 3.54.3 (3.54.3-1.fc41) 
MIME-Version: 1.0
Archived-At: 
 <https://www.postgresql.org/message-id/e2d54a1c1cdc80c748dd47f36ff9d6c5e5b75e51.camel%40cybertec.at>
Precedence: bulk

On Mon, 2025-04-07 at 09:07 +0000, Stefan Schmiedl wrote:
> Wearing my documentation writer's hat, I agree that the information given=
 on
> one page need not be repeated on another one, especially if it's already
> cross-referenced.
>=20
> However, with my documentation reader's glasses on, I would have liked to=
 see
> that data there, as it would have allowed me to file subscripts under=C2=
=A0
> "brackets, mostly 1-based,=C2=A0slices [a:b]=C2=A0are closed intervals" a=
nd move on.
>=20
> As it is, I needed to follow the link=C2=A0to the array page, then to the=
 section=C2=A0
> "Accessing", where I encounter=C2=A0"Now, we can run some queries on the =
table",=C2=A0
> which implies that I need to at=C2=A0least scan content somewhere above t=
he current=C2=A0
> point to learn about the=C2=A0table structure. Only then I reach the bit =
about the
> first index.
>=20
> Pages in part I and II (at least, I have not really gone into III and IV)=
 feel like
> they're meant to be read completely from top to bottom, not topical like =
a lookup
> in the excellent Reference where I usually can find answers to my questio=
ns by
> reading a few lines in the description of the option I'm unsure about.
>=20
> As such, I'd have appreciated the additional information as it would have=
 kept
> me in the flow of the page, a flow that its author has worked hard to set=
 up for me.

There is always room for improvement.

It would be great if you could put on both of your hats and come up with
a patch that implements the rather invasive change you are envisioning.
Then we can see if it feels better overall, and we have a concrete basis
for a discussion.

Yours,
Laurenz Albe