Re: Another modest proposal for docs formatting: catalog descriptions

=?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.

regards, tom lane