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
