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

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
> 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!

>
> 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.

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.

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
>
>         <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.

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.

> 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?

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