From: Jonathan S. Katz <jkatz@postgresql.org>
To: Tom Lane <tgl@sss.pgh.pa.us>
To: Josef Šimánek <josef.simanek@gmail.com>
Cc: pgsql-docs@lists.postgresql.org
Cc: pgsql-hackers@lists.postgresql.org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
Date: Mon, 1 Jun 2020 19:17:17 -0400
Message-ID: <12e922b7-b3ef-0e63-60b5-dc50bc1450f6@postgresql.org> (raw)
In-Reply-To: <506028.1591052275@sss.pgh.pa.us>
References: <12984.1588643549@sss.pgh.pa.us>
<CAFp7QwqrKAc+pwLG+zssu1MAi9yaO93+gNm4MLR=43FLtdeDGA@mail.gmail.com>
<506028.1591052275@sss.pgh.pa.us>
On 6/1/20 6:57 PM, Tom Lane wrote:
> =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef.simanek@gmail.com> writes:
>> I have spotted this change recently at progress monitoring devel docs (
>> https://www.postgresql.org/docs/devel/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING).
>> Current version seems a little chaotic since there are multiple tables on
>> the same page with 2 mixed layouts. Older layout (for example v12 one -
>> https://www.postgresql.org/docs/12/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING)
>> is much easier to read for me.
>
>> Is this final change? I do not see any problem on this (progress
>> monitoring) page in old layout. Is there any example of problematic page?
>> Maybe there's a different way to solve this. For example instead of
>> in-lining long text as a column description, it should be possible to link
>> to detailed description in custom paragraph or table. See description
>> column at table 27.22. at progress monitoring page for column "phase" for
>> similar approach.
>
> I'm not planning on revisiting that work, no. And converting every
> table/view description table into two (or more?) tables sure doesn't
> sound like an improvement.
>
> Perhaps there's a case for reformatting the phase-description tables
> in the progress monitoring section to look more like the view tables.
> (I hadn't paid much attention to them, since they weren't causing PDF
> rendering problems.) On the other hand, you could argue that it's
> good that they don't look like the view tables, since the info they
> are presenting is fundamentally different. I don't honestly see much
> wrong with the way it is now.
I think it looks fine. +1 for leaving it.
Jonathan
Attachments:
signature.asc (application/pgp-signature, 832B) download
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: jkatz@postgresql.org, tgl@sss.pgh.pa.us, josef.simanek@gmail.com, pgsql-docs@lists.postgresql.org, pgsql-hackers@lists.postgresql.org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-Reply-To: <12e922b7-b3ef-0e63-60b5-dc50bc1450f6@postgresql.org>
* 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