Subject: Re: Another modest proposal for docs formatting: catalog descriptions
To: Tom Lane <tgl@sss.pgh.pa.us>, =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?=
 <josef.simanek@gmail.com>
Cc: pgsql-docs@lists.postgresql.org, pgsql-hackers@lists.postgresql.org
References: <12984.1588643549@sss.pgh.pa.us>
 <CAFp7QwqrKAc+pwLG+zssu1MAi9yaO93+gNm4MLR=43FLtdeDGA@mail.gmail.com>
 <506028.1591052275@sss.pgh.pa.us>
From: "Jonathan S. Katz" <jkatz@postgresql.org>
Autocrypt: addr=jkatz@postgresql.org; keydata=
 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 FmEC
Message-ID: <12e922b7-b3ef-0e63-60b5-dc50bc1450f6@postgresql.org>
Date: Mon, 1 Jun 2020 19:17:17 -0400
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:68.0)
 Gecko/20100101 Thunderbird/68.8.1
MIME-Version: 1.0
In-Reply-To: <506028.1591052275@sss.pgh.pa.us>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="rxsE8EHOL5QmqkdCUDDOdVMrpOGbegM1l"
Precedence: bulk

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--rxsE8EHOL5QmqkdCUDDOdVMrpOGbegM1l
Content-Type: multipart/mixed; boundary="B70qxjgHt9AEcFlWATDRQ9K87x1GM41TN";
 protected-headers="v1"
From: "Jonathan S. Katz" <jkatz@postgresql.org>
To: Tom Lane <tgl@sss.pgh.pa.us>, =?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?=
 <josef.simanek@gmail.com>
Cc: pgsql-docs@lists.postgresql.org, pgsql-hackers@lists.postgresql.org
Message-ID: <12e922b7-b3ef-0e63-60b5-dc50bc1450f6@postgresql.org>
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
References: <12984.1588643549@sss.pgh.pa.us>
 <CAFp7QwqrKAc+pwLG+zssu1MAi9yaO93+gNm4MLR=43FLtdeDGA@mail.gmail.com>
 <506028.1591052275@sss.pgh.pa.us>
In-Reply-To: <506028.1591052275@sss.pgh.pa.us>

--B70qxjgHt9AEcFlWATDRQ9K87x1GM41TN
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

On 6/1/20 6:57 PM, Tom Lane wrote:
> =3D?UTF-8?B?Sm9zZWYgxaBpbcOhbmVr?=3D <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-I=
NDEX-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-INDE=
X-PROGRESS-REPORTING)
>> is much easier to read for me.
>=20
>> Is this final change? I do not see any problem on this (progress
>> monitoring) page in old layout. Is there any example of problematic pa=
ge?
>> 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.
>=20
> 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.
>=20
> 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


--B70qxjgHt9AEcFlWATDRQ9K87x1GM41TN--

--rxsE8EHOL5QmqkdCUDDOdVMrpOGbegM1l
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl7VjH0ACgkQ8QSccp8c
ZScZhBAAqqinslGTf1U6QagSus3D8qAqAvcQhjLZilbkFp5/mi8tO4ShZFW6/Gui
d076S+2JtIAv7K1AMtPmR8+SU/cg5z413F1oJOType/LuIO1sHANYxnQT/LFGmbM
b7vQfyLDO59fbOzCWWZOGBHKo/T5zaB33DwBcip+ZpwMTxPDj6XREsalXeEWxINz
Sy43m/pook/IvYBiK6Xtj/4dWtS2/q/nPTL7KAp7TwAVsyEDo9mwbYannShfF1Gq
//p0RSbb9rIIAGlIwW+asAa8iS/EU/HJ8H+tOwQGd7r74mCXtKuZi+0Y6lt1/xBC
9dir8ljZGeP1BN0huHpu/Hs4crd8/XRmUpoFlEgoXwYm98Tec1c0lGMOFKAdscIB
CkUUAc9qR55ZuDIug7kbnzvMV+53/9Y3dCVBjCtOn7sJm7ANyYhCd7qYe7ON/ioQ
dn0WHCLZZTy8CBLLbtHO2eDql25E2ZIXg8aVFmp1sm/jAo86xzLfAwOpybopiUpe
+OU884C9vCCO/jww0oiP6FfyqB4k5d67YAVyL0stG62bPmeR50WyE5qyWTtDHwBe
GmLO1XHxR9aZzEEKj5kExx6y7+aHLdj9vB1xxRXS0+3z63tIMWBhzA1+2guQ2hYA
y0oofDTGbRQG5e9m9Mi4Nh/Pu+xRcLewQngmbd+fh2pkloY2HXA=
=FCWD
-----END PGP SIGNATURE-----

--rxsE8EHOL5QmqkdCUDDOdVMrpOGbegM1l--