Re: Poll: are people okay with function/operator table redesign?

"Jonathan S. Katz" <jkatz(at)postgresql(dot)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