From: Tom Lane <tgl@sss.pgh.pa.us>
To: "Jonathan S. Katz" <jkatz@postgresql.org>
cc: Peter Eisentraut <peter.eisentraut@2ndquadrant.com>,
        Bruce Momjian <bruce@momjian.us>,
        Alvaro Herrera <alvherre@2ndquadrant.com>,
        Robert Haas <robertmhaas@gmail.com>,
        Steven Pousty <steve.pousty@gmail.com>,
        Pavel Stehule <pavel.stehule@gmail.com>,
        Isaac Morland <isaac.morland@gmail.com>,
        Pierre Giraud <pierre.giraud@dalibo.com>,
        PostgreSQL Developers <pgsql-hackers@lists.postgresql.org>
Subject: Re: Poll: are people okay with function/operator table redesign?
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>
Comments: In-reply-to "Jonathan S. Katz" <jkatz@postgresql.org>
	message dated "Mon, 04 May 2020 17:38:55 -0400"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <4459.1588631970.1@sss.pgh.pa.us>
Date: Mon, 04 May 2020 18:39:30 -0400
Message-ID: <4460.1588631970@sss.pgh.pa.us>
Precedence: bulk

"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