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 17:22:01 -0400
Message-ID: <751.1588627321@sss.pgh.pa.us> (raw)
In-Reply-To: <b1f89d14-cd7f-e43d-964e-9fb04e209b72@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>
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
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.
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:
* 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:
<para>
<literal>regexp_matches('foobarbequebaz', 'ba.', 'g')</literal>
<returnvalue></returnvalue>
<programlisting>
{bar}
{baz}
</programlisting>
(2 rows in result)
</para>
where the empty <returnvalue> environment is just serving to generate a
right arrow. It looks all right, but it's hardly semantically-based
markup.
* <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
<function>stddev</function> ( <replaceable>numeric_type</replaceable> )
<returnvalue></returnvalue> <type>double precision</type>
for <type>real</type> or <type>double precision</type>,
otherwise <type>numeric</type>
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.
* 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.
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,
<function>stddev</function> ( <replaceable>numeric_type</replaceable> )
&returns; <type>double precision</type>
for <type>real</type> or <type>double precision</type>,
otherwise <type>numeric</type>
Does anyone have a preference on that, or a better alternative?
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: <751.1588627321@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