Re: Another modest proposal for docs formatting: catalog descriptions

From: "Jonathan S(dot) Katz" <jkatz(at)postgresql(dot)org>
To: Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Josef Šimánek <josef(dot)simanek(at)gmail(dot)com>
Cc: pgsql-docs(at)lists(dot)postgresql(dot)org, pgsql-hackers(at)lists(dot)postgresql(dot)org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
Date: 2020-06-01 23:17:17
Message-ID: 12e922b7-b3ef-0e63-60b5-dc50bc1450f6@postgresql.org
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs pgsql-hackers

On 6/1/20 6:57 PM, Tom Lane wrote:
> =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?= <josef(dot)simanek(at)gmail(dot)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

In response to

Browse pgsql-docs by date

  From Date Subject
Next Message Fujii Masao 2020-06-02 05:25:02 Re: wal_init_zero and wal_recycle
Previous Message Tom Lane 2020-06-01 22:57:55 Re: Another modest proposal for docs formatting: catalog descriptions

Browse pgsql-hackers by date

  From Date Subject
Next Message Etsuro Fujita 2020-06-02 00:02:10 Re: [POC] Fast COPY FROM command for the table with foreign partitions
Previous Message Tom Lane 2020-06-01 22:57:55 Re: Another modest proposal for docs formatting: catalog descriptions