Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1jXTuS-0008GM-HT
	for pgsql-hackers@arkaria.postgresql.org; Sat, 09 May 2020 18:09:12 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-hackers-owner+archive@lists.postgresql.org>)
	id 1jXTuR-0002mo-8M
	for pgsql-hackers@arkaria.postgresql.org; Sat, 09 May 2020 18:09:11 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jXTuR-0002mc-10; Sat, 09 May 2020 18:09:11 +0000
Received: from sss.pgh.pa.us ([66.207.139.130])
	by magus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <tgl@sss.pgh.pa.us>)
	id 1jXTuO-0005dJ-Ma; Sat, 09 May 2020 18:09:10 +0000
Received: from sss1.sss.pgh.pa.us (localhost [127.0.0.1])
	by sss.pgh.pa.us (8.14.4/8.14.4) with ESMTP id 049I91xd003358;
	Sat, 9 May 2020 14:09:01 -0400
From: Tom Lane <tgl@sss.pgh.pa.us>
To: Fabien COELHO <coelho@cri.ensmp.fr>
cc: "Jonathan S. Katz" <jkatz@postgresql.org>,
        Alvaro Herrera <alvherre@2ndquadrant.com>,
        pgsql-docs@lists.postgresql.org,
        PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-reply-to: <alpine.DEB.2.22.394.2005091912200.914063@pseudo>
References: <20200506213810.GA29168@alvherre.pgsql>
 <14800.1588805800@sss.pgh.pa.us> <23610.1588978416@sss.pgh.pa.us>
 <alpine.DEB.2.22.394.2005090847090.914063@pseudo>
 <4521.1589038464@sss.pgh.pa.us>
 <alpine.DEB.2.22.394.2005091912200.914063@pseudo>
Comments: In-reply-to Fabien COELHO <coelho@cri.ensmp.fr>
	message dated "Sat, 09 May 2020 19:30:11 +0200"
MIME-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-ID: <3356.1589047741.1@sss.pgh.pa.us>
Content-Transfer-Encoding: 8bit
Date: Sat, 09 May 2020 14:09:01 -0400
Message-ID: <3357.1589047741@sss.pgh.pa.us>
List-Id: <pgsql-hackers.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-hackers@lists.postgresql.org>
List-Owner: <mailto:pgsql-hackers-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-hackers>
Precedence: bulk

Fabien COELHO <coelho@cri.ensmp.fr> writes:
> Possibly. I'm a little at odds with Type not being above types, but far on 
> the left, so that you cannot really "see" that it is about the format, 

Yeah, agreed.  We can adjust the space in the header independently of
what's in the table entries, so it'd be possible to put more space
between "Column" and "Type" ... but I'm not sure if that would fix it.

> If I can suggest more adjustements, maybe the description margin is a too 
> much, I'd propose reduce it to about 3 chars wide. Obviously any aesthetic 
> opinion is by definition subjective and prone to differ from one person to 
> the next…

This is more Jonathan's department than mine, but I personally prefer more
indentation to less --- you want the column names to stick out so you can
find them.  Anyway, the present indentation is (it looks like) the same
as we are using in <variablelist>s, which this layout is based on.

			regards, tom lane