Subject: Re: Poll: are people okay with function/operator table redesign?
To: Tom Lane <tgl@sss.pgh.pa.us>
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>
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>
From: "Jonathan S. Katz" <jkatz@postgresql.org>
Autocrypt: addr=jkatz@postgresql.org; keydata=
 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 FmEC
Message-ID: <251a3aa4-c59b-4d16-d515-7e2252579431@postgresql.org>
Date: Mon, 4 May 2020 17:38:55 -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: <751.1588627321@sss.pgh.pa.us>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="L0wYzlSuRqSoUw4mmTM704ecFYf0Y46cL"
Precedence: bulk

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

--9fANfF5BG0qZEsgFbjTrDX1eyOrMVRdtG
Content-Type: text/plain; charset=utf-8
Content-Language: en-US
Content-Transfer-Encoding: quoted-printable

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=20
> https://www.postgresql.org/docs/devel/functions.html
> There is more to do --- for instance, various contrib modules
> have function/operator tables that should be synced with this
> design.  But this seemed like a good place to pause and reflect.

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!

>=20
> After working through the whole chapter, the only aspect of the
> new markup that really doesn't seem to work so well is the use
> of <returnvalue> for function result types and example results.
> While I don't think that that's broken in concept, DocBook has
> restrictions on the contents of <returnvalue> that are problematic:
>=20
> * It won't let you put any verbatim-layout environment, such
> as <programlisting>, inside <returnvalue>.  This is an issue for
> examples for set-returning functions in particular.  I've done
> those like this:
>=20
>        <para>
>         <literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal>=

>         <returnvalue></returnvalue>
> <programlisting>
>  {bar}
>  {baz}
> </programlisting>
>         (2 rows in result)
>        </para>
>=20
> where the empty <returnvalue> environment is just serving to generate a=

> right arrow.  It looks all right, but it's hardly semantically-based
> markup.

We could apply some CSS on the pgweb front perhaps to help distinguish
at least the results? For the above example, it would be great to
capture the program listing + "2 rows in result" output and format them
similarly, though it appears the "(2 rows in result)" is in its own block=
=2E

Anyway, likely not that hard to apply some CSS and make it appear a bit
more distinguished, if that's the general idea.

> * <returnvalue> is also quite sticky about inserting other sorts
> of font-changing environments inside it.  As an example, it'll let
> you include <replaceable> but not <type>, which seems pretty weird
> to me.  This is problematic in some places where it's desirable to
> have text rather than just a type name, for example
>=20
>         <function>stddev</function> ( <replaceable>numeric_type</replac=
eable> )
>         <returnvalue></returnvalue> <type>double precision</type>
>         for <type>real</type> or <type>double precision</type>,
>         otherwise <type>numeric</type>
>=20
> Now I could have done this example by spelling out all six varieties of=

> stddev() separately, and maybe I should've, but it seemed overly bulky
> that way.  So again <returnvalue> is just generating the right arrow.
>=20
> * After experimenting with a few different ways to handle functions wit=
h
> multiple OUT parameters, I settled on doing it like this:
>=20
>         <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> )
>=20
> 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. It seems like there's enough structure where one can make some
not-too-zany CSS rules to put a bit more space between elements, but
perhaps wait to hear the decision on the rest of the structural questions=
=2E

> So at this point I'm tempted to abandon <returnvalue> and go back
> to using a custom entity to generate the right arrow, so that
> the markup would just look like, say,
>=20
>         <function>stddev</function> ( <replaceable>numeric_type</replac=
eable> )
>         &returns; <type>double precision</type>
>         for <type>real</type> or <type>double precision</type>,
>         otherwise <type>numeric</type>
>=20
> Does anyone have a preference on that, or a better alternative?

As long as we can properly style without zany CSS rules, I'm +0 :)

Jonathan

[1] https://www.postgresql.org/docs/devel/functions-aggregate.html


--9fANfF5BG0qZEsgFbjTrDX1eyOrMVRdtG--

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

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

iQIzBAEBCAAdFiEE+oS2la8r95ogZD/x8QSccp8cZScFAl6wi3AACgkQ8QSccp8c
ZSfJcA//eRePg/ienjFK93PT/UK9KjDP3gRdlwDufdL1KqQsUyQBWPhOiFtjJ/Fu
Z0tE1xUXuS2qb67ghWnB+aPYhQ6fKJ9AH+Ycdf6NMqNV/WiEgRMLUxLqCGORacwQ
lEBDYUYlPdLV+E7a61jI25Dyud6lQoZupAmETBqJHuzkOHJZJIyi6FfS8Rqxy/PH
74B1CBDa/fNo1CwNX+gu2HqjeRt3FD5pK0Gh8tCOhWNIpNyhMmqh7Zt9gQCoYk+Y
T9rOuHMP+Nj3vqORRL1xEX0mRMJxknCbZ8KSx/CF86Zc5lESlgK0u8GC6gPTTej7
etuUjM3eNWYgtKCvgZbdmQKK0/beq/f4yoP7IOX7RIo155FPExQik8ZhItD8PyN3
EFoKbFBZkkX1Ru6Tu+zDxf55tcyzcWz1FtMHWxe7SVEJtQVM6x203833DviGwS5M
APUtJTDrBIdxEwsOWKtEqfQ9XMkEhBti8TbeYTmy/Fmy/9ByL5Acjd/gSvBhB838
qlmn6TMG2SIHD8Ns0LmsH9V3ytXb/mRveYzj2os01i4m8Pzfic4AN15rJ72eN/D/
lOz0HsWxRJuuz8LOuPXY7ewIzIznquo+sDXTwzW2exq/QAdHfK4h9wFMMA8DrKey
7yCdWpX7pyTd7O5FilqEa/CLrMoBDtY4zkwHJRS66sGICjXQ5HQ=
=j8tf
-----END PGP SIGNATURE-----

--L0wYzlSuRqSoUw4mmTM704ecFYf0Y46cL--