From: Fabien COELHO <coelho@cri.ensmp.fr>
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: Jonathan S. Katz <jkatz@postgresql.org>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: pgsql-docs@lists.postgresql.org, PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
Date: Sat, 9 May 2020 19:30:11 +0200 (CEST)
Message-ID: <alpine.DEB.2.22.394.2005091912200.914063@pseudo> (raw)
In-Reply-To: <4521.1589038464@sss.pgh.pa.us>
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>
Hello Tom,
>>> Here's a more fully fleshed out draft for this, with stylesheet
>>> markup to get extra space around the column type names.
>
>> I find this added spacing awkward, espacially as attribute names are
>> always one word anyway. I prefer the non spaced approach.
>
> It's certainly arguable that that look is too heavy-handed. In the
> attached, I knocked down the extra space from 1em to 0.25em, which
> makes it quite a bit subtler --- are you any happier with this?
Yes, definitely.
> BTW, I don't think it's very accurate that "attribute names are
> always one word" --- see the second attachment.
Indeed.
> Here if anything I'm wanting a little more space.
I'm fine with 0.25em which allows some breathing without looking awkward.
Maybe a little more would still be okay, but not much more.
>> If spacing is discussed, should the layout rather try to align type
>> information, eg:
>
> I thought about that, but it seems extremely close to some of the
> earlier function-table layouts that were so widely panned. The SGML
> source would have to be a lot uglier too, probably with explicit use
> of spanspec's on every row.
Hmmm, that's the kind of things I was afraid of.
> It could be done no doubt, but I think people would not see it as an
> improvement.
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,
especially with long attribute names:
Column Type
Description
quite_a_long_attribute and_its_type
...
The horizontal distance between "Type" and "and_its_type" is so wide as to
hide the clue that the former is describing the later. But maybe aligning
would be too ugly.
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…
--
Fabien.
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-docs@postgresql.org
Cc: coelho@cri.ensmp.fr, tgl@sss.pgh.pa.us, jkatz@postgresql.org, alvherre@2ndquadrant.com, 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>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
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