Date: Tue, 12 Oct 2021 19:44:19 -0300
From: Alvaro Herrera <alvherre@alvh.no-ip.org>
To: Laurenz Albe <laurenz.albe@cybertec.at>
Cc: rir <rirans@comcast.net>, pgsql-docs@lists.postgresql.org
Subject: Re: small patch
Message-ID: <202110122244.miu4rxify7qg@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <57c6acf0d2936597184f6bc06f434c66eab07f49.camel@cybertec.at>
Archived-At: 
 <https://www.postgresql.org/message-id/202110122244.miu4rxify7qg%40alvherre.pgsql>
Precedence: bulk

On 2021-Oct-08, Laurenz Albe wrote:

> I remain of the opinion that the comments should be
> retained, but we can leave that for somebody else to
> decide.

So I just realized that I added this comment in 8c250f3741f.

The point of this comment is that the list of options to which
"direction" expands is duplicate and needs to be kept in sync.  However,
clearly we have other places in the docs where similar lists are
duplicated and no such comments are kept; see "column_constraint" in
alter_table.sgml and create_table.sgml for an obvious one.  I can't
quite make up my mind about the comment being actually helpful if
somebody adds a new type of contraints to remind them that they also
need to add it to the other place.  What do you think?

I think I side with Laurenz that the comment should be kept, even if
it's just out of inertia.

Maybe a better solution (more convoluted? overengineered?) would be to
define an SGML entity in the first of those pages that uses the list in
such a way so that it expands to that list, and then use that entity in
the other page.  I don't know how that is done, but surely it must be
possible.

-- 
Álvaro Herrera         PostgreSQL Developer  —  https://www.EnterpriseDB.com/
"E pur si muove" (Galileo Galilei)