From: Tom Lane <tgl@sss.pgh.pa.us>
To: Jonathan S. Katz <jkatz@postgresql.org>
Cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>
Cc: Bruce Momjian <bruce@momjian.us>
Cc: Alvaro Herrera <alvherre@2ndquadrant.com>
Cc: Robert Haas <robertmhaas@gmail.com>
Cc: Steven Pousty <steve.pousty@gmail.com>
Cc: Pavel Stehule <pavel.stehule@gmail.com>
Cc: Isaac Morland <isaac.morland@gmail.com>
Cc: Pierre Giraud <pierre.giraud@dalibo.com>
Cc: PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Poll: are people okay with function/operator table redesign?
Date: Mon, 04 May 2020 18:39:30 -0400
Message-ID: <4460.1588631970@sss.pgh.pa.us> (raw)
In-Reply-To: <251a3aa4-c59b-4d16-d515-7e2252579431@postgresql.org>
References: <20200423174343.GA16996@alvherre.pgsql>
<19233.1587665407@sss.pgh.pa.us>
<5561.1587922854@sss.pgh.pa.us>
<13e5e408-bc59-e8ca-44f3-28a981b4fc7d@postgresql.org>
<a47ea348-b9a0-02b7-5bcb-7a32143dd16f@postgresql.org>
<11211.1587951842@sss.pgh.pa.us>
<58de9544-be5b-f325-b5cc-cce4e2dda7d9@postgresql.org>
<5651.1587991781@sss.pgh.pa.us>
<b998a672-2525-1cba-ac64-b292f495919e@postgresql.org>
<30469.1588087170@sss.pgh.pa.us>
<8682.1588202983@sss.pgh.pa.us>
<4894cde4-148d-f0cc-d6d8-182a46f13e1b@postgresql.org>
<06f6b32d-a4cc-3723-5bc1-00fa674df961@postgresql.org>
<11106.1588205727@sss.pgh.pa.us>
<1c5ca197-f7f2-0300-46ce-4652c7f81d48@postgresql.org>
<ab7803b4-f985-cf3d-267f-38b7311ca917@postgresql.org>
<18310.1588214299@sss.pgh.pa.us>
<c5f34a44-ccb9-c59e-ee5a-c8d97980df15@postgresql.org>
<20585.1588217180@sss.pgh.pa.us>
<b1f89d14-cd7f-e43d-964e-9fb04e209b72@postgresql.org>
<751.1588627321@sss.pgh.pa.us>
<251a3aa4-c59b-4d16-d515-7e2252579431@postgresql.org>
"Jonathan S. Katz" <jkatz@postgresql.org> writes:
> On 5/4/20 5:22 PM, Tom Lane wrote:
>> I've now completed updating chapter 9 for the new layout,
>> and the results are visible at
>> https://www.postgresql.org/docs/devel/functions.html> This is already much better. I've skimmed through a few of the pages, I
> can say that the aggregates page[1] is WAY easier to read. Yay!
Thanks!
>> * After experimenting with a few different ways to handle functions with
>> multiple OUT parameters, I settled on doing it like this:
>> <function>pg_partition_tree</function> ( <type>regclass</type> )
>> <returnvalue>setof record</returnvalue>
>> ( <parameter>relid</parameter> <type>regclass</type>,
>> <parameter>parentrelid</parameter> <type>regclass</type>,
>> <parameter>isleaf</parameter> <type>boolean</type>,
>> <parameter>level</parameter> <type>integer</type> )
>>
>> This looks nice and I think it's much more intelligible than other
>> things I tried --- in particular, including the OUT parameters in
>> the function signature seems to me to be mostly confusing. But,
>> once again, it's abusing the concept that <returnvalue> contains
>> the result type. Ideally the output-column list would be inside
>> the <returnvalue> environment, but DocBook won't allow that
>> because of the <type> tags.
> It does look better, but things look a bit smushed together on the pgweb
> front.
Yeah. There's less smushing of function signatures when building the
docs without STYLE=website, so there's something specific to the
website style. I think you'd mentioned that we were intentionally
crimping the space and/or font size within tables? Maybe that could
get un-done now. I hadn't bothered to worry about such details until
we had a reasonable sample of cases to look at, but now would be a
good time.
Another rendering oddity that I'd not bothered to chase down is
the appearance of <itemizedlist> environments within table cells.
We have a few of those now as a result of migration of material
that had been out-of-line into the table cells; one example is
in json_populate_record, about halfway down this page:
https://www.postgresql.org/docs/devel/functions-json.html
The text of the list items seems to be getting indented to the
same extent as a not-in-a-table <itemizedlist> list does ---
but the bullets aren't indented nearly as much, making for
weird spacing. (There's a short <itemizedlist> at the top of
the same page that you can compare to.)
The same weird spacing is visible in a non STYLE=website build,
so I think this might be less a CSS issue and more a DocBook
issue. On the other hand, it looks fine in the PDF build.
So I'm not sure where to look for the cause.
regards, tom lane
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-hackers@postgresql.org
Cc: tgl@sss.pgh.pa.us, jkatz@postgresql.org, peter.eisentraut@2ndquadrant.com, bruce@momjian.us, alvherre@2ndquadrant.com, robertmhaas@gmail.com, steve.pousty@gmail.com, pavel.stehule@gmail.com, isaac.morland@gmail.com, pierre.giraud@dalibo.com, pgsql-hackers@lists.postgresql.org
Subject: Re: Poll: are people okay with function/operator table redesign?
In-Reply-To: <4460.1588631970@sss.pgh.pa.us>
* 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