Subject: Re: Another modest proposal for docs formatting: catalog descriptions
To: Tom Lane <tgl@sss.pgh.pa.us>, Fabien COELHO <coelho@cri.ensmp.fr>
Cc: pgsql-docs@lists.postgresql.org,
 PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
References: <12984.1588643549@sss.pgh.pa.us>
 <alpine.DEB.2.22.394.2005050743340.175044@pseudo>
 <20976.1588688873@sss.pgh.pa.us> <1014.1588722172@sss.pgh.pa.us>
From: "Jonathan S. Katz" <jkatz@postgresql.org>
Autocrypt: addr=jkatz@postgresql.org; keydata=
 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 FmEC
Message-ID: <f0b8986a-c195-d047-f549-63172ed9e1a0@postgresql.org>
Date: Tue, 5 May 2020 20:27:46 -0400
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:68.0)
 Gecko/20100101 Thunderbird/68.7.0
MIME-Version: 1.0
In-Reply-To: <1014.1588722172@sss.pgh.pa.us>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="MjCklAlHlR4FpKxooeeYRrhogmIrJn03C"
Precedence: bulk

This is an OpenPGP/MIME signed message (RFC 4880 and 3156)
--MjCklAlHlR4FpKxooeeYRrhogmIrJn03C
Content-Type: multipart/mixed; boundary="3Xi24XIovGBUzxHoZQ4EZCYbPzqnRhV4U"

--3Xi24XIovGBUzxHoZQ4EZCYbPzqnRhV4U
Content-Type: text/plain; charset=windows-1252
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

On 5/5/20 7:42 PM, Tom Lane wrote:
> Here's a really quick-n-dirty prototype patch that just converts the
> pg_aggregate table to the proposed style, plus a screenshot for those
> who don't feel like actually building the docs with the patch.

Not opposed to building the docs, but the screenshot expedites things ;)

> Looking at the results, it seems like we could really use a bit more
> horizontal space between the column names and data types, and perhaps
> also between the types and the (references) annotations.  Other than
> that it looks decent.  I don't know what's the cleanest way to add
> some space there --- I'd rather not have the SGML text do it explicitly=
=2E

If each element (i.e. column name, data type) is wrapped in a HTML
element with its own class (e.g. a span) it's fairly easy to add that
space with CSS. I'm not sure the ramifications for the PDFs though.

> There's room for complaint that this takes up more vertical space than
> the old way, assuming you have a reasonably wide window.  I'm not
> terribly bothered by that, but maybe someone else will be?  I'm incline=
d
> to think that that's well worth the benefit that we won't feel compelle=
d
> to keep column descriptions short.

I think for reference materials, vertical space is acceptable. It seems
to be the "mobile way" of doing things, since people are scrolling down.

(And unlike the mailing lists, we don't need to keep the font small ;)

Anyway, +1

> BTW, this being just a test hack, I repurposed the "func_table_entry" a=
nd
> "func_signature" style marker roles.  If we do this for real then of
> course we'd want to use different roles, even if they happen to mark up=

> the same for now.

Agreed.

Thanks,

Jonathan


--3Xi24XIovGBUzxHoZQ4EZCYbPzqnRhV4U--

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

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

iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl6yBIIACgkQ8QSccp8c
ZSe7PQ/+MrFkLQNGOVIF8IxBE6+XNj3Kx1g3UWARvU/Mrc885FILiIQXWGcQbv7K
ZYKP/Pl2jluEWpwv2NBWZdHl49dG0Mb2+UrFPe1EmTfZAlUdQq/Gf8iJG8/VNAiS
YWGMvRvWuQfVDz6DepB0q1YQAriXLzZSGo2TF8JYsOeH8BwpoTDasxJIICUQfC+p
Z54Xy3a/GHqbMf3qOq3Bd6ccLAL9cchO2zPPzKMXXXG5wCVeOXmEL6KaL+CxbIAL
wkZ8NifVvPI5vcTDB8VVKqgU0STzsmL/jn8Q5C3inIt/bvWWPXWA/s044XzhSw6a
k4qCc1c9xzYsIYLqbOw9dBkAwbQ2ZNx7tBNAYLTOKGyqmVv49aFvRFuC3eVFbApl
2PRWQmB/0qu6LsMbCPjvNTZwJITWsSMLwHTRsX7CoimG17+GsFIAVyKvDPXhQkzy
t/MP8cnv2ZkYw1V+rHWrydFvF41oKsOPud3yr/u+K3aRvSfjec/1MpdBxWttvRwJ
zh7+4M+HFSqBXMnk9EyZjdniwN/l3iH+MCQ4VeuVuha5ZhlqhxCQmOfVQ3Xkemui
kcE9xXPZiPyRPSBJUZ0NN8febqspI+4DazdlFpZIRCKbhzoyChayBqdUePIFQCmW
OdKDxSzBdPXxxam4ZYz4jVcTi1TIgIxcTTSGB2qvcpzGqgdcRrY=
=tzfv
-----END PGP SIGNATURE-----

--MjCklAlHlR4FpKxooeeYRrhogmIrJn03C--