From: Jonathan S. Katz <jkatz@postgresql.org>
To: Tom Lane <tgl@sss.pgh.pa.us>
To: Fabien COELHO <coelho@cri.ensmp.fr>
Cc: pgsql-docs@lists.postgresql.org, PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
Date: Tue, 5 May 2020 20:27:46 -0400
Message-ID: <f0b8986a-c195-d047-f549-63172ed9e1a0@postgresql.org> (raw)
In-Reply-To: <1014.1588722172@sss.pgh.pa.us>
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>
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.
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 inclined
> to think that that's well worth the benefit that we won't feel compelled
> 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" and
> "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
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, coelho@cri.ensmp.fr, pgsql-hackers@lists.postgresql.org
Subject: Re: Another modest proposal for docs formatting: catalog descriptions
In-Reply-To: <f0b8986a-c195-d047-f549-63172ed9e1a0@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