Getting our tables to render better in PDF output

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
29 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Getting our tables to render better in PDF output

Tom Lane-2
The crummy formatting of our tables of functions and operators has
been an issue for a long time.  To my mind, there are several things
that need to be addressed:

* The layout is completely unfriendly to function descriptions that
run to more than a few words.

* It's not very practical to have more than one example per function
(or at least, we seldom do so).

* The results look completely awful in PDF format, because of the
narrow effectively-available space, plus the fact that the toolchain
will prefer to overprint following columns instead of breaking text
where there's no whitespace.

In [1], Alvaro suggested that we might be able to improve matters by
taking advantage of DocBook's features for column and row spanning.
I did some concrete experimentation in that line, and attached are
two alternative patches that show a couple of things we might do.
Both patches change tables 9.31 (Date/Time Functions) and 9.33
(Enum Support Functions), which I chose somewhat at random, but of
course there would be a lot more to be done if we choose to go this way.

The first patch uses only one row for each function example, while
the second patch uses two rows (i.e., example and result in separate
table rows).  Otherwise they're the same.

I initially did the enum-support table, and what I tried there included
getting rid of the separate table column for function result type by
writing the functions in the form "func(argtypes) returns resulttype".
(Note that this table failed to specify the result types at all before,
which doesn't seem great.)  The layout idea is

    function name, args, result               description
                                         example     example result

where we can repeat the "example / example result" row if we want more
examples per function.  Alternatively, in the second patch, it's

    function name, args, result          description
                                         example
                                         example result

To my eyes, the first alternative is preferable in HTML, unless maybe you
want to read the manual in a *very* narrow browser window.  But some of
the examples/results still overrun the available space when looking
at it in PDF A4 format.  The second patch fixes that problem, but seems
not very pretty in a normal-width browser window.

When I tried to apply the same idea to the date/time functions table,
it didn't really work well at all, mainly because of a few beasts like
make_interval() --- that caused the left column to be so wide that the
right-hand columns were horrid.  (At least with the toolchain version
I'm using, it seems like the colwidth specifications are respected
rigidly in PDF output but just plain ignored in HTML output.  What
seems to happen in HTML is that earlier columns get their preferred
width and later ones get squeezed.)

So the layout idea that the patches show for that table is

    function name      arg types     result type
                       description
                       example     example result

or

    function name      arg types     result type
                       description
                       example
                       example result

(Even with that, I had to savage make_interval's arg-types list a bit
to keep that column from eating too much space...)

I'm not especially wedded to any of these ideas, but I hope to provoke
some discussion about what we might do in this area.  DocBook tables
aren't the greatest layout tool in the world, but they do have abilities
we're not exploiting.

Even with these changes, the amount of space available for examples
and results in PDF format is pretty tiny.  With examples and results
in the same row, it seems that you can only have a couple of dozen
consecutive non-whitespace characters without running into overwrite
issues, whereas in HTML format the trouble threshold is a good deal
higher.  I wonder if we could improve matters by switching to some
narrower font for <literal> text in PDF?

                        regards, tom lane

[1] https://www.postgresql.org/message-id/20200116184444.GA25792%40alvherre.pgsql


diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ceda48e..385fdc0 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6798,471 +6798,618 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
 
     <table id="functions-datetime-table">
      <title>Date/Time Functions</title>
-     <tgroup cols="5">
+     <tgroup cols="3">
+      <colspec colnum="1" colname="col1" colwidth="1*"/>
+      <colspec colnum="2" colname="col2" colwidth="1*"/>
+      <colspec colnum="3" colname="col3" colwidth="1*"/>
+      <spanspec spanname="func" namest="col1" nameend="col1" align="left"/>
+      <spanspec spanname="args" namest="col2" nameend="col2" align="left"/>
+      <spanspec spanname="result" namest="col3" nameend="col3" align="left"/>
+      <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
+      <spanspec spanname="exresult" namest="col3" nameend="col3" align="left"/>
       <thead>
        <row>
-        <entry>Function</entry>
-        <entry>Return Type</entry>
-        <entry>Description</entry>
-        <entry>Example</entry>
-        <entry>Result</entry>
+        <entry spanname="func" align="center" morerows="2">Function</entry>
+        <entry spanname="args" align="center">Argument Types</entry>
+        <entry spanname="result" align="center">Result Type</entry>
+       </row>
+       <row>
+        <entry spanname="desc" align="center">Description</entry>
+       </row>
+       <row>
+        <entry spanname="example" align="center">Example</entry>
+        <entry spanname="exresult" align="center">Example Result</entry>
        </row>
       </thead>
 
       <tbody>
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>age</primary>
          </indexterm>
-         <literal><function>age(<type>timestamp</type>, <type>timestamp</type>)</function></literal>
+         <function>age</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Subtract arguments, producing a <quote>symbolic</quote> result that
+        <entry spanname="args"><type>timestamp</type>, <type>timestamp</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract arguments, producing a <quote>symbolic</quote> result that
         uses years and months, rather than just days</entry>
-        <entry><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
-        <entry><literal>43 years 9 mons 27 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
+        <entry spanname="exresult"><literal>43 years 9 mons 27 days</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>age(<type>timestamp</type>)</function></literal></entry>
-        <entry><type>interval</type></entry>
-        <entry>Subtract from <function>current_date</function> (at midnight)</entry>
-        <entry><literal>age(timestamp '1957-06-13')</literal></entry>
-        <entry><literal>43 years 8 mons 3 days</literal></entry>
+        <entry spanname="func" morerows="2"><function>age</function></entry>
+        <entry spanname="args"><type>timestamp</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract from <function>current_date</function> (at midnight)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>age(timestamp '1957-06-13')</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>clock_timestamp</primary>
          </indexterm>
-         <literal><function>clock_timestamp()</function></literal>
+         <function>clock_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (changes during statement execution);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (changes during statement execution);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>clock_timestamp()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>current_date</primary>
          </indexterm>
-         <literal><function>current_date</function></literal>
+         <function>current_date</function>
         </entry>
-        <entry><type>date</type></entry>
-        <entry>Current date;
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>date</type></entry>
+       </row>
+       <row>
+         <entry spanname="desc">Current date;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_date</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>current_time</primary>
          </indexterm>
-         <literal><function>current_time</function></literal>
+         <function>current_time</function>
         </entry>
-        <entry><type>time with time zone</type></entry>
-        <entry>Current time of day;
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>time with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current time of day;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_time</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>current_timestamp</primary>
          </indexterm>
-         <literal><function>current_timestamp</function></literal>
+         <function>current_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_timestamp</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>date_part</primary>
          </indexterm>
-         <literal><function>date_part(<type>text</type>, <type>timestamp</type>)</function></literal>
+         <function>date_part</function>
         </entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield (equivalent to <function>extract</function>);
+        <entry spanname="args"><type>text</type>, <type>timestamp</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield (equivalent to <function>extract</function>);
          see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>20</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
+        <entry spanname="exresult"><literal>20</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_part(<type>text</type>, <type>interval</type>)</function></literal></entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield (equivalent to
+        <entry spanname="func" morerows="2"><function>date_part</function></entry>
+        <entry spanname="args"><type>text</type>, <type>interval</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield (equivalent to
          <function>extract</function>); see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>date_part('month', interval '2 years 3 months')</literal></entry>
-        <entry><literal>3</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_part('month', interval '2 years 3 months')</literal></entry>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>date_trunc</primary>
          </indexterm>
-         <literal><function>date_trunc(<type>text</type>, <type>timestamp</type>)</function></literal>
+         <function>date_trunc</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="args"><type>text</type>, <type>timestamp</type></entry>
+        <entry spanname="result"><type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>2001-02-16 20:00:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
+        <entry spanname="exresult"><literal>2001-02-16 20:00:00</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_trunc(<type>text</type>, <type>timestamp with time zone</type>, <type>text</type>)</function></literal></entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="func" morerows="2"><function>date_trunc</function></entry>
+        <entry spanname="args"><type>text</type>, <type>timestamp with time zone</type>, <type>text</type></entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</literal></entry>
-        <entry><literal>2001-02-16 13:00:00+00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</literal></entry>
+        <entry spanname="exresult"><literal>2001-02-16 13:00:00+00</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_trunc(<type>text</type>, <type>interval</type>)</function></literal></entry>
-        <entry><type>interval</type></entry>
-        <entry>Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="func" morerows="2"><function>date_trunc</function></entry>
+        <entry spanname="args"><type>text</type>, <type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal></entry>
-        <entry><literal>2 days 03:00:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal></entry>
+        <entry spanname="exresult"><literal>2 days 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>extract</primary>
          </indexterm>
-         <literal><function>extract</function>(<parameter>field</parameter> from
-         <type>timestamp</type>)</literal>
+         <function>extract</function>
         </entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield; see <xref linkend="functions-datetime-extract"/>
+        <entry spanname="args"><parameter>field</parameter> <literal>from</literal> <type>timestamp</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield; see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>20</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
+        <entry spanname="exresult"><literal>20</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>extract</function>(<parameter>field</parameter> from
-         <type>interval</type>)</literal></entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield; see <xref linkend="functions-datetime-extract"/>
+        <entry spanname="func" morerows="2"><function>extract</function></entry>
+        <entry spanname="args"><parameter>field</parameter> <literal>from</literal> <type>interval</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield; see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>extract(month from interval '2 years 3 months')</literal></entry>
-        <entry><literal>3</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>extract(month from interval '2 years 3 months')</literal></entry>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>isfinite</primary>
          </indexterm>
-         <literal><function>isfinite(<type>date</type>)</function></literal>
+         <function>isfinite</function>
         </entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite date (not +/-infinity)</entry>
-        <entry><literal>isfinite(date '2001-02-16')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="args"><type>date</type></entry>
+        <entry spanname="result"><type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite date (not +/-infinity)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(date '2001-02-16')</literal></entry>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>isfinite(<type>timestamp</type>)</function></literal></entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite time stamp (not +/-infinity)</entry>
-        <entry><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="func" morerows="2"><function>isfinite</function></entry>
+        <entry spanname="args"><type>timestamp</type></entry>
+        <entry spanname="result"><type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite time stamp (not +/-infinity)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>isfinite(<type>interval</type>)</function></literal></entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite interval</entry>
-        <entry><literal>isfinite(interval '4 hours')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="func" morerows="2"><function>isfinite</function></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite interval</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(interval '4 hours')</literal></entry>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>justify_days</primary>
          </indexterm>
-         <literal><function>justify_days(<type>interval</type>)</function></literal>
+         <function>justify_days</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval so 30-day time periods are represented as months</entry>
-        <entry><literal>justify_days(interval '35 days')</literal></entry>
-        <entry><literal>1 mon 5 days</literal></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval so 30-day time periods are represented as months</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_days(interval '35 days')</literal></entry>
+        <entry spanname="exresult"><literal>1 mon 5 days</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>justify_hours</primary>
          </indexterm>
-         <literal><function>justify_hours(<type>interval</type>)</function></literal>
+         <function>justify_hours</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval so 24-hour time periods are represented as days</entry>
-        <entry><literal>justify_hours(interval '27 hours')</literal></entry>
-        <entry><literal>1 day 03:00:00</literal></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval so 24-hour time periods are represented as days</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_hours(interval '27 hours')</literal></entry>
+        <entry spanname="exresult"><literal>1 day 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>justify_interval</primary>
          </indexterm>
-         <literal><function>justify_interval(<type>interval</type>)</function></literal>
+         <function>justify_interval</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments</entry>
-        <entry><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
-        <entry><literal>29 days 23:00:00</literal></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
+        <entry spanname="exresult"><literal>29 days 23:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>localtime</primary>
          </indexterm>
-         <literal><function>localtime</function></literal>
+         <function>localtime</function>
         </entry>
-        <entry><type>time</type></entry>
-        <entry>Current time of day;
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current time of day;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>localtime</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>localtimestamp</primary>
          </indexterm>
-         <literal><function>localtimestamp</function></literal>
+         <function>localtimestamp</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>localtimestamp</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>make_date</primary>
          </indexterm>
-         <literal>
-            <function>
-             make_date(<parameter>year</parameter> <type>int</type>,
-             <parameter>month</parameter> <type>int</type>,
-             <parameter>day</parameter> <type>int</type>)
-            </function>
-         </literal>
+         <function>make_date</function>
         </entry>
-        <entry><type>date</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type></entry>
+        <entry spanname="result"><type>date</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create date from year, month and day fields
         </entry>
-        <entry><literal>make_date(2013, 7, 15)</literal></entry>
-        <entry><literal>2013-07-15</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_date(2013, 7, 15)</literal></entry>
+        <entry spanname="exresult"><literal>2013-07-15</literal></entry>
        </row>
 
        <row>
-        <entry>
-         <indexterm>
+        <entry spanname="func" morerows="2"><indexterm>
           <primary>make_interval</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_interval(<parameter>years</parameter> <type>int</type> DEFAULT 0,
-           <parameter>months</parameter> <type>int</type> DEFAULT 0,
-           <parameter>weeks</parameter> <type>int</type> DEFAULT 0,
-           <parameter>days</parameter> <type>int</type> DEFAULT 0,
-           <parameter>hours</parameter> <type>int</type> DEFAULT 0,
-           <parameter>mins</parameter> <type>int</type> DEFAULT 0,
-           <parameter>secs</parameter> <type>double precision</type> DEFAULT 0.0)
-          </function>
-         </literal>
+         <function>make_interval</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>
+        <entry spanname="args"><optional> <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>double precision</type>
+         </optional></optional></optional></optional></optional></optional></optional></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create interval from years, months, weeks, days, hours, minutes and
-         seconds fields
+         seconds fields, each of which can default to zero
         </entry>
-        <entry><literal>make_interval(days =&gt; 10)</literal></entry>
-        <entry><literal>10 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_interval(days =&gt; 10)</literal></entry>
+        <entry spanname="exresult"><literal>10 days</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>make_time</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_time(<parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>)
-          </function>
-         </literal>
+         <function>make_time</function>
         </entry>
-        <entry><type>time</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type></entry>
+        <entry spanname="result"><type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create time from hour, minute and seconds fields
         </entry>
-        <entry><literal>make_time(8, 15, 23.5)</literal></entry>
-        <entry><literal>08:15:23.5</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_time(8, 15, 23.5)</literal></entry>
+        <entry spanname="exresult"><literal>08:15:23.5</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>make_timestamp</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_timestamp(<parameter>year</parameter> <type>int</type>,
-           <parameter>month</parameter> <type>int</type>,
-           <parameter>day</parameter> <type>int</type>,
-           <parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>)
-          </function>
-         </literal>
+         <function>make_timestamp</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>,
+         <parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type></entry>
+        <entry spanname="result"><type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create timestamp from year, month, day, hour, minute and seconds fields
         </entry>
-        <entry><literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal></entry>
-        <entry><literal>2013-07-15 08:15:23.5</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal></entry>
+        <entry spanname="exresult"><literal>2013-07-15 08:15:23.5</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>make_timestamptz</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_timestamptz(<parameter>year</parameter> <type>int</type>,
-           <parameter>month</parameter> <type>int</type>,
-           <parameter>day</parameter> <type>int</type>,
-           <parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>,
-           <optional> <parameter>timezone</parameter> <type>text</type> </optional>)
-          </function>
-         </literal>
+         <function>make_timestamptz</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>,
+         <parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type>,
+         <optional> <parameter>timezone</parameter> <type>text</type> </optional></entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create timestamp with time zone from year, month, day, hour, minute
          and seconds fields; if <parameter>timezone</parameter> is not
          specified, the current time zone is used
         </entry>
-        <entry><literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal></entry>
-        <entry><literal>2013-07-15 08:15:23.5+01</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal></entry>
+        <entry spanname="exresult"><literal>2013-07-15 08:15:23.5+01</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>now</primary>
          </indexterm>
-         <literal><function>now()</function></literal>
+         <function>now</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>now()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>statement_timestamp</primary>
          </indexterm>
-         <literal><function>statement_timestamp()</function></literal>
+         <function>statement_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current statement);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current statement);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>statement_timestamp()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>timeofday</primary>
          </indexterm>
-         <literal><function>timeofday()</function></literal>
+         <function>timeofday</function>
         </entry>
-        <entry><type>text</type></entry>
-        <entry>Current date and time
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>text</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time
          (like <function>clock_timestamp</function>, but as a <type>text</type> string);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>timeofday()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>transaction_timestamp</primary>
          </indexterm>
-         <literal><function>transaction_timestamp()</function></literal>
+         <function>transaction_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
        </row>
        <row>
-        <entry>
+        <entry spanname="example"><literal>transaction_timestamp()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
+       </row>
+       <row>
+        <entry spanname="func" morerows="2">
          <indexterm>
           <primary>to_timestamp</primary>
          </indexterm>
-         <literal><function>to_timestamp(<type>double precision</type>)</function></literal>
+         <function>to_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
+        <entry spanname="args"><type>double precision</type></entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
          timestamp</entry>
-        <entry><literal>to_timestamp(1284352323)</literal></entry>
-        <entry><literal>2010-09-13 04:32:03+00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>to_timestamp(1284352323)</literal></entry>
+        <entry spanname="exresult"><literal>2010-09-13 04:32:03+00</literal></entry>
        </row>
       </tbody>
      </tgroup>
@@ -8236,52 +8383,67 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
 
   <table id="functions-enum-table">
     <title>Enum Support Functions</title>
-    <tgroup cols="4">
+    <tgroup cols="3">
+     <colspec colnum="1" colname="col1" colwidth="1*"/>
+     <colspec colnum="2" colname="col2" colwidth="1*"/>
+     <colspec colnum="3" colname="col3" colwidth="1*"/>
+     <spanspec spanname="func" namest="col1" nameend="col1" align="left"/>
+     <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
+     <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
+     <spanspec spanname="exresult" namest="col3" nameend="col3" align="left"/>
      <thead>
       <row>
-       <entry>Function</entry>
-       <entry>Description</entry>
-       <entry>Example</entry>
-       <entry>Example Result</entry>
+       <entry spanname="func" align="center" morerows="1">Function</entry>
+       <entry spanname="desc" align="center">Description</entry>
+      </row>
+      <row>
+       <entry spanname="example" align="center">Example</entry>
+       <entry spanname="exresult" align="center">Result</entry>
       </row>
      </thead>
      <tbody>
       <row>
-       <entry>
+       <entry spanname="func" morerows="1">
          <indexterm>
           <primary>enum_first</primary>
          </indexterm>
-         <literal>enum_first(anyenum)</literal>
+         <literal>enum_first(anyenum) returns anyenum</literal>
        </entry>
-       <entry>Returns the first value of the input enum type</entry>
-       <entry><literal>enum_first(null::rainbow)</literal></entry>
-       <entry><literal>red</literal></entry>
+       <entry spanname="desc">Returns the first value of the input enum type</entry>
       </row>
       <row>
-       <entry>
+       <entry spanname="example"><literal>enum_first(null::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>red</literal></entry>
+      </row>
+      <row>
+       <entry spanname="func" morerows="1">
          <indexterm>
           <primary>enum_last</primary>
          </indexterm>
-         <literal>enum_last(anyenum)</literal>
+         <literal>enum_last(anyenum) returns anyenum</literal>
        </entry>
-       <entry>Returns the last value of the input enum type</entry>
-       <entry><literal>enum_last(null::rainbow)</literal></entry>
-       <entry><literal>purple</literal></entry>
+       <entry spanname="desc">Returns the last value of the input enum type</entry>
       </row>
       <row>
-       <entry>
+       <entry spanname="example"><literal>enum_last(null::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>purple</literal></entry>
+      </row>
+      <row>
+       <entry spanname="func" morerows="1">
          <indexterm>
           <primary>enum_range</primary>
          </indexterm>
-         <literal>enum_range(anyenum)</literal>
+         <literal>enum_range(anyenum) returns anyarray</literal>
        </entry>
-       <entry>Returns all values of the input enum type in an ordered array</entry>
-       <entry><literal>enum_range(null::rainbow)</literal></entry>
-       <entry><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
+       <entry spanname="desc">Returns all values of the input enum type in an ordered array</entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range(null::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
       </row>
       <row>
-       <entry morerows="2"><literal>enum_range(anyenum, anyenum)</literal></entry>
-       <entry morerows="2">
+       <entry spanname="func" morerows="3"><literal>enum_range(anyenum, anyenum) returns anyarray</literal></entry>
+       <entry spanname="desc">
         Returns the range between the two given enum values, as an ordered
         array. The values must be from the same enum type. If the first
         parameter is null, the result will start with the first value of
@@ -8289,16 +8451,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
         If the second parameter is null, the result will end with the last
         value of the enum type.
        </entry>
-       <entry><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
-       <entry><literal>{orange,yellow,green}</literal></entry>
       </row>
       <row>
-       <entry><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
-       <entry><literal>{red,orange,yellow,green}</literal></entry>
+       <entry spanname="example"><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>{orange,yellow,green}</literal></entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>{red,orange,yellow,green}</literal></entry>
       </row>
       <row>
-       <entry><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
-       <entry><literal>{orange,yellow,green,blue,purple}</literal></entry>
+       <entry spanname="example"><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
+       <entry spanname="exresult"><literal>{orange,yellow,green,blue,purple}</literal></entry>
       </row>
      </tbody>
     </tgroup>

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ceda48e..7364294 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -6798,471 +6798,682 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
 
     <table id="functions-datetime-table">
      <title>Date/Time Functions</title>
-     <tgroup cols="5">
+     <tgroup cols="3">
+      <colspec colnum="1" colname="col1" colwidth="1*"/>
+      <colspec colnum="2" colname="col2" colwidth="1*"/>
+      <colspec colnum="3" colname="col3" colwidth="1*"/>
+      <spanspec spanname="func" namest="col1" nameend="col1" align="left"/>
+      <spanspec spanname="args" namest="col2" nameend="col2" align="left"/>
+      <spanspec spanname="result" namest="col3" nameend="col3" align="left"/>
+      <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="example" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="exresult" namest="col2" nameend="col3" align="left"/>
       <thead>
        <row>
-        <entry>Function</entry>
-        <entry>Return Type</entry>
-        <entry>Description</entry>
-        <entry>Example</entry>
-        <entry>Result</entry>
+        <entry spanname="func" align="center" morerows="3">Function</entry>
+        <entry spanname="args" align="center">Argument Types</entry>
+        <entry spanname="result" align="center">Result Type</entry>
+       </row>
+       <row>
+        <entry spanname="desc" align="center">Description</entry>
+       </row>
+       <row>
+        <entry spanname="example" align="center">Example</entry>
+       </row>
+       <row>
+        <entry spanname="exresult" align="center">Example Result</entry>
        </row>
       </thead>
 
       <tbody>
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>age</primary>
          </indexterm>
-         <literal><function>age(<type>timestamp</type>, <type>timestamp</type>)</function></literal>
+         <function>age</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Subtract arguments, producing a <quote>symbolic</quote> result that
+        <entry spanname="args"><type>timestamp</type>, <type>timestamp</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract arguments, producing a <quote>symbolic</quote> result that
         uses years and months, rather than just days</entry>
-        <entry><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
-        <entry><literal>43 years 9 mons 27 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>43 years 9 mons 27 days</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>age(<type>timestamp</type>)</function></literal></entry>
-        <entry><type>interval</type></entry>
-        <entry>Subtract from <function>current_date</function> (at midnight)</entry>
-        <entry><literal>age(timestamp '1957-06-13')</literal></entry>
-        <entry><literal>43 years 8 mons 3 days</literal></entry>
+        <entry spanname="func" morerows="3"><function>age</function></entry>
+        <entry spanname="args"><type>timestamp</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract from <function>current_date</function> (at midnight)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>age(timestamp '1957-06-13')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>clock_timestamp</primary>
          </indexterm>
-         <literal><function>clock_timestamp()</function></literal>
+         <function>clock_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (changes during statement execution);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (changes during statement execution);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>clock_timestamp()</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>current_date</primary>
          </indexterm>
-         <literal><function>current_date</function></literal>
+         <function>current_date</function>
         </entry>
-        <entry><type>date</type></entry>
-        <entry>Current date;
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>date</type></entry>
+       </row>
+       <row>
+         <entry spanname="desc">Current date;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_date</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>current_time</primary>
          </indexterm>
-         <literal><function>current_time</function></literal>
+         <function>current_time</function>
         </entry>
-        <entry><type>time with time zone</type></entry>
-        <entry>Current time of day;
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>time with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current time of day;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_time</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>current_timestamp</primary>
          </indexterm>
-         <literal><function>current_timestamp</function></literal>
+         <function>current_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_timestamp</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>date_part</primary>
          </indexterm>
-         <literal><function>date_part(<type>text</type>, <type>timestamp</type>)</function></literal>
+         <function>date_part</function>
         </entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield (equivalent to <function>extract</function>);
+        <entry spanname="args"><type>text</type>, <type>timestamp</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield (equivalent to <function>extract</function>);
          see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>20</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>20</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_part(<type>text</type>, <type>interval</type>)</function></literal></entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield (equivalent to
+        <entry spanname="func" morerows="3"><function>date_part</function></entry>
+        <entry spanname="args"><type>text</type>, <type>interval</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield (equivalent to
          <function>extract</function>); see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>date_part('month', interval '2 years 3 months')</literal></entry>
-        <entry><literal>3</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_part('month', interval '2 years 3 months')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>date_trunc</primary>
          </indexterm>
-         <literal><function>date_trunc(<type>text</type>, <type>timestamp</type>)</function></literal>
+         <function>date_trunc</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="args"><type>text</type>, <type>timestamp</type></entry>
+        <entry spanname="result"><type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>2001-02-16 20:00:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2001-02-16 20:00:00</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_trunc(<type>text</type>, <type>timestamp with time zone</type>, <type>text</type>)</function></literal></entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="func" morerows="3"><function>date_trunc</function></entry>
+        <entry spanname="args"><type>text</type>, <type>timestamp with time zone</type>, <type>text</type></entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</literal></entry>
-        <entry><literal>2001-02-16 13:00:00+00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2001-02-16 13:00:00+00</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_trunc(<type>text</type>, <type>interval</type>)</function></literal></entry>
-        <entry><type>interval</type></entry>
-        <entry>Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="func" morerows="3"><function>date_trunc</function></entry>
+        <entry spanname="args"><type>text</type>, <type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal></entry>
-        <entry><literal>2 days 03:00:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2 days 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>extract</primary>
          </indexterm>
-         <literal><function>extract</function>(<parameter>field</parameter> from
-         <type>timestamp</type>)</literal>
+         <function>extract</function>
         </entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield; see <xref linkend="functions-datetime-extract"/>
+        <entry spanname="args"><parameter>field</parameter> <literal>from</literal> <type>timestamp</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield; see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>20</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>20</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>extract</function>(<parameter>field</parameter> from
-         <type>interval</type>)</literal></entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield; see <xref linkend="functions-datetime-extract"/>
+        <entry spanname="func" morerows="3"><function>extract</function></entry>
+        <entry spanname="args"><parameter>field</parameter> <literal>from</literal> <type>interval</type></entry>
+        <entry spanname="result"><type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield; see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>extract(month from interval '2 years 3 months')</literal></entry>
-        <entry><literal>3</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>extract(month from interval '2 years 3 months')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>isfinite</primary>
          </indexterm>
-         <literal><function>isfinite(<type>date</type>)</function></literal>
+         <function>isfinite</function>
         </entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite date (not +/-infinity)</entry>
-        <entry><literal>isfinite(date '2001-02-16')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="args"><type>date</type></entry>
+        <entry spanname="result"><type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite date (not +/-infinity)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(date '2001-02-16')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>isfinite(<type>timestamp</type>)</function></literal></entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite time stamp (not +/-infinity)</entry>
-        <entry><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="func" morerows="3"><function>isfinite</function></entry>
+        <entry spanname="args"><type>timestamp</type></entry>
+        <entry spanname="result"><type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite time stamp (not +/-infinity)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>isfinite(<type>interval</type>)</function></literal></entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite interval</entry>
-        <entry><literal>isfinite(interval '4 hours')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="func" morerows="3"><function>isfinite</function></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite interval</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(interval '4 hours')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>justify_days</primary>
          </indexterm>
-         <literal><function>justify_days(<type>interval</type>)</function></literal>
+         <function>justify_days</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval so 30-day time periods are represented as months</entry>
-        <entry><literal>justify_days(interval '35 days')</literal></entry>
-        <entry><literal>1 mon 5 days</literal></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval so 30-day time periods are represented as months</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_days(interval '35 days')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>1 mon 5 days</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>justify_hours</primary>
          </indexterm>
-         <literal><function>justify_hours(<type>interval</type>)</function></literal>
+         <function>justify_hours</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval so 24-hour time periods are represented as days</entry>
-        <entry><literal>justify_hours(interval '27 hours')</literal></entry>
-        <entry><literal>1 day 03:00:00</literal></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval so 24-hour time periods are represented as days</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_hours(interval '27 hours')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>1 day 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>justify_interval</primary>
          </indexterm>
-         <literal><function>justify_interval(<type>interval</type>)</function></literal>
+         <function>justify_interval</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments</entry>
-        <entry><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
-        <entry><literal>29 days 23:00:00</literal></entry>
+        <entry spanname="args"><type>interval</type></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>29 days 23:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>localtime</primary>
          </indexterm>
-         <literal><function>localtime</function></literal>
+         <function>localtime</function>
         </entry>
-        <entry><type>time</type></entry>
-        <entry>Current time of day;
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current time of day;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>localtime</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>localtimestamp</primary>
          </indexterm>
-         <literal><function>localtimestamp</function></literal>
+         <function>localtimestamp</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none (written without parentheses)</entry>
+        <entry spanname="result"><type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>localtimestamp</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>make_date</primary>
          </indexterm>
-         <literal>
-            <function>
-             make_date(<parameter>year</parameter> <type>int</type>,
-             <parameter>month</parameter> <type>int</type>,
-             <parameter>day</parameter> <type>int</type>)
-            </function>
-         </literal>
+         <function>make_date</function>
         </entry>
-        <entry><type>date</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type></entry>
+        <entry spanname="result"><type>date</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create date from year, month and day fields
         </entry>
-        <entry><literal>make_date(2013, 7, 15)</literal></entry>
-        <entry><literal>2013-07-15</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_date(2013, 7, 15)</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2013-07-15</literal></entry>
        </row>
 
        <row>
-        <entry>
-         <indexterm>
+        <entry spanname="func" morerows="3"><indexterm>
           <primary>make_interval</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_interval(<parameter>years</parameter> <type>int</type> DEFAULT 0,
-           <parameter>months</parameter> <type>int</type> DEFAULT 0,
-           <parameter>weeks</parameter> <type>int</type> DEFAULT 0,
-           <parameter>days</parameter> <type>int</type> DEFAULT 0,
-           <parameter>hours</parameter> <type>int</type> DEFAULT 0,
-           <parameter>mins</parameter> <type>int</type> DEFAULT 0,
-           <parameter>secs</parameter> <type>double precision</type> DEFAULT 0.0)
-          </function>
-         </literal>
+         <function>make_interval</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>
+        <entry spanname="args"><optional> <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>int</type>
+         <optional>, <type>double precision</type>
+         </optional></optional></optional></optional></optional></optional></optional></entry>
+        <entry spanname="result"><type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create interval from years, months, weeks, days, hours, minutes and
-         seconds fields
+         seconds fields, each of which can default to zero
         </entry>
-        <entry><literal>make_interval(days =&gt; 10)</literal></entry>
-        <entry><literal>10 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_interval(days =&gt; 10)</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>10 days</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>make_time</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_time(<parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>)
-          </function>
-         </literal>
+         <function>make_time</function>
         </entry>
-        <entry><type>time</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type></entry>
+        <entry spanname="result"><type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create time from hour, minute and seconds fields
         </entry>
-        <entry><literal>make_time(8, 15, 23.5)</literal></entry>
-        <entry><literal>08:15:23.5</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_time(8, 15, 23.5)</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>08:15:23.5</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>make_timestamp</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_timestamp(<parameter>year</parameter> <type>int</type>,
-           <parameter>month</parameter> <type>int</type>,
-           <parameter>day</parameter> <type>int</type>,
-           <parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>)
-          </function>
-         </literal>
+         <function>make_timestamp</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>,
+         <parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type></entry>
+        <entry spanname="result"><type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create timestamp from year, month, day, hour, minute and seconds fields
         </entry>
-        <entry><literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal></entry>
-        <entry><literal>2013-07-15 08:15:23.5</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2013-07-15 08:15:23.5</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>make_timestamptz</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_timestamptz(<parameter>year</parameter> <type>int</type>,
-           <parameter>month</parameter> <type>int</type>,
-           <parameter>day</parameter> <type>int</type>,
-           <parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>,
-           <optional> <parameter>timezone</parameter> <type>text</type> </optional>)
-          </function>
-         </literal>
+         <function>make_timestamptz</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>
+        <entry spanname="args"><parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>,
+         <parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type>,
+         <optional> <parameter>timezone</parameter> <type>text</type> </optional></entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create timestamp with time zone from year, month, day, hour, minute
          and seconds fields; if <parameter>timezone</parameter> is not
          specified, the current time zone is used
         </entry>
-        <entry><literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal></entry>
-        <entry><literal>2013-07-15 08:15:23.5+01</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2013-07-15 08:15:23.5+01</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>now</primary>
          </indexterm>
-         <literal><function>now()</function></literal>
+         <function>now</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>now()</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>statement_timestamp</primary>
          </indexterm>
-         <literal><function>statement_timestamp()</function></literal>
+         <function>statement_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current statement);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current statement);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>statement_timestamp()</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>timeofday</primary>
          </indexterm>
-         <literal><function>timeofday()</function></literal>
+         <function>timeofday</function>
         </entry>
-        <entry><type>text</type></entry>
-        <entry>Current date and time
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>text</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time
          (like <function>clock_timestamp</function>, but as a <type>text</type> string);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>timeofday()</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>transaction_timestamp</primary>
          </indexterm>
-         <literal><function>transaction_timestamp()</function></literal>
+         <function>transaction_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="args">none</entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
        </row>
        <row>
-        <entry>
+        <entry spanname="example"><literal>transaction_timestamp()</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
+       </row>
+       <row>
+        <entry spanname="func" morerows="3">
          <indexterm>
           <primary>to_timestamp</primary>
          </indexterm>
-         <literal><function>to_timestamp(<type>double precision</type>)</function></literal>
+         <function>to_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
+        <entry spanname="args"><type>double precision</type></entry>
+        <entry spanname="result"><type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
          timestamp</entry>
-        <entry><literal>to_timestamp(1284352323)</literal></entry>
-        <entry><literal>2010-09-13 04:32:03+00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>to_timestamp(1284352323)</literal></entry>
+       </row>
+       <row>
+        <entry spanname="exresult"><literal>2010-09-13 04:32:03+00</literal></entry>
        </row>
       </tbody>
      </tgroup>
@@ -8236,52 +8447,74 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
 
   <table id="functions-enum-table">
     <title>Enum Support Functions</title>
-    <tgroup cols="4">
+    <tgroup cols="2">
+     <colspec colnum="1" colname="col1" colwidth="1*"/>
+     <colspec colnum="2" colname="col2" colwidth="2*"/>
+     <spanspec spanname="func" namest="col1" nameend="col1" align="left"/>
+     <spanspec spanname="desc" namest="col2" nameend="col2" align="left"/>
+     <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
+     <spanspec spanname="exresult" namest="col2" nameend="col2" align="left"/>
      <thead>
       <row>
-       <entry>Function</entry>
-       <entry>Description</entry>
-       <entry>Example</entry>
-       <entry>Example Result</entry>
+       <entry spanname="func" align="center" morerows="2">Function</entry>
+       <entry spanname="desc" align="center">Description</entry>
+      </row>
+      <row>
+       <entry spanname="example" align="center">Example</entry>
+      </row>
+      <row>
+       <entry spanname="exresult" align="center">Result</entry>
       </row>
      </thead>
      <tbody>
       <row>
-       <entry>
+       <entry spanname="func" morerows="2">
          <indexterm>
           <primary>enum_first</primary>
          </indexterm>
-         <literal>enum_first(anyenum)</literal>
+         <literal>enum_first(anyenum) returns anyenum</literal>
        </entry>
-       <entry>Returns the first value of the input enum type</entry>
-       <entry><literal>enum_first(null::rainbow)</literal></entry>
-       <entry><literal>red</literal></entry>
+       <entry spanname="desc">Returns the first value of the input enum type</entry>
       </row>
       <row>
-       <entry>
+       <entry spanname="example"><literal>enum_first(null::rainbow)</literal></entry>
+      </row>
+      <row>
+       <entry spanname="exresult"><literal>red</literal></entry>
+      </row>
+      <row>
+       <entry spanname="func" morerows="2">
          <indexterm>
           <primary>enum_last</primary>
          </indexterm>
-         <literal>enum_last(anyenum)</literal>
+         <literal>enum_last(anyenum) returns anyenum</literal>
        </entry>
-       <entry>Returns the last value of the input enum type</entry>
-       <entry><literal>enum_last(null::rainbow)</literal></entry>
-       <entry><literal>purple</literal></entry>
+       <entry spanname="desc">Returns the last value of the input enum type</entry>
       </row>
       <row>
-       <entry>
+       <entry spanname="example"><literal>enum_last(null::rainbow)</literal></entry>
+      </row>
+      <row>
+       <entry spanname="exresult"><literal>purple</literal></entry>
+      </row>
+      <row>
+       <entry spanname="func" morerows="2">
          <indexterm>
           <primary>enum_range</primary>
          </indexterm>
-         <literal>enum_range(anyenum)</literal>
+         <literal>enum_range(anyenum) returns anyarray</literal>
        </entry>
-       <entry>Returns all values of the input enum type in an ordered array</entry>
-       <entry><literal>enum_range(null::rainbow)</literal></entry>
-       <entry><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
+       <entry spanname="desc">Returns all values of the input enum type in an ordered array</entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range(null::rainbow)</literal></entry>
+      </row>
+      <row>
+       <entry spanname="exresult"><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
       </row>
       <row>
-       <entry morerows="2"><literal>enum_range(anyenum, anyenum)</literal></entry>
-       <entry morerows="2">
+       <entry spanname="func" morerows="6"><literal>enum_range(anyenum, anyenum) returns anyarray</literal></entry>
+       <entry spanname="desc">
         Returns the range between the two given enum values, as an ordered
         array. The values must be from the same enum type. If the first
         parameter is null, the result will start with the first value of
@@ -8289,16 +8522,24 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
         If the second parameter is null, the result will end with the last
         value of the enum type.
        </entry>
-       <entry><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
-       <entry><literal>{orange,yellow,green}</literal></entry>
       </row>
       <row>
-       <entry><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
-       <entry><literal>{red,orange,yellow,green}</literal></entry>
+       <entry spanname="example"><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
+      </row>
+      <row>
+       <entry spanname="exresult"><literal>{orange,yellow,green}</literal></entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
+      </row>
+      <row>
+       <entry spanname="exresult"><literal>{red,orange,yellow,green}</literal></entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
       </row>
       <row>
-       <entry><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
-       <entry><literal>{orange,yellow,green,blue,purple}</literal></entry>
+       <entry spanname="exresult"><literal>{orange,yellow,green,blue,purple}</literal></entry>
       </row>
      </tbody>
     </tgroup>
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alexander Lakhin-2
Hello Tom,
12.02.2020 00:51, Tom Lane wrote:

> The crummy formatting of our tables of functions and operators has
> been an issue for a long time.  To my mind, there are several things
> that need to be addressed:
>
> * The layout is completely unfriendly to function descriptions that
> run to more than a few words.
>
> * It's not very practical to have more than one example per function
> (or at least, we seldom do so).
>
> * The results look completely awful in PDF format, because of the
> narrow effectively-available space, plus the fact that the toolchain
> will prefer to overprint following columns instead of breaking text
> where there's no whitespace.
Please look at a less invasive approach that we use at Postgres Pro for
some time (mainly for improving the translated documentation, but it
works for the original one too). The idea is to add zero-width spaces
after/before some chars ('(', ',', '[', etc) to let fop split lines
where desired. It has one disadvantage - it's not search-friendly
(though maybe that is application-dependent).
But if it's feasible, I think this approach can at least complement a
manual tables reformatting. Decreasing a font size in the tables seems
appropriate to me too.

Best regards,
Alexander

fix-pdf-overflow.patch (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
Alexander Lakhin <[hidden email]> writes:
> Please look at a less invasive approach that we use at Postgres Pro for
> some time (mainly for improving the translated documentation, but it
> works for the original one too). The idea is to add zero-width spaces
> after/before some chars ('(', ',', '[', etc) to let fop split lines
> where desired. It has one disadvantage - it's not search-friendly
> (though maybe that is application-dependent).
> But if it's feasible, I think this approach can at least complement a
> manual tables reformatting. Decreasing a font size in the tables seems
> appropriate to me too.

Hmm, interesting proposal.  I experimented and verified that injecting
zero-width space (&#x200B;) does allow line breaking to occur in both
HTML and PDF output, so this could be a route to improving the situation
for overlength example texts.  I do not think I like the idea of
automatically injecting tons of them, though.  As you say, it might
hinder searching; and it would allow some silly breaks; and there are
cases where it still wouldn't find a break, such as the examples for
sha256() et al.  I'd be happier about manually inserting breaks just
in the places we really need them.  To keep the source readable, I'd
want to write something like "&zwsp;" not a numeric entity code,
but it looks like we can define custom entities if we want.

For amusement's sake, attached is a screenshot of what Table 9-33
looks like in A4 format, with my one-row-per-example patch of
yesterday plus a few manually-added zero-width spaces to break up
the examples.  This is the first PDF rendering of that table that
I've seen that I actually like.

I also attached a screenshot of a segment of Table 9-31, to show
what that layout proposal looks like.  It's a little busier, but
it does have the advantage that it's clearer how to apply that
format to operator tables.  The "returns <type>" notation isn't used
anywhere in SQL for operators, so I am not in love with the idea of
writing the operator tables that way.

Also worth noting is that in most function tables, and certainly
in the operator tables, we could make the first column narrower.
The same table with the first column half as wide as the others
is depicted in the last screenshot.  (For this particular table,
doing that would require breaking some of the longer function
names such as transaction_timestamp.  Not sure whether that's
a net win, but we do have the option.)

One issue that I've found is that the toolchain has no idea that
the table rows are in groups, so it's happy to split a table
across pages with a function's description and/or examples on
a new page.  No idea if there's any way around that.  Fortunately
it's not an issue in HTML, so maybe we don't have to fix it.

Thoughts?

                        regards, tom lane


table9-33.png (301K) Download Attachment
table9-31.png (318K) Download Attachment
table9-31-narrow.png (269K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alvaro Herrera-9
On 2020-Feb-12, Tom Lane wrote:

> For amusement's sake, attached is a screenshot of what Table 9-33
> looks like in A4 format, with my one-row-per-example patch of
> yesterday plus a few manually-added zero-width spaces to break up
> the examples.  This is the first PDF rendering of that table that
> I've seen that I actually like.

I like this.  The trick of mkaing the first cell take up two or three
rows makes this much clearer and sensible than what I had obtained.

> I also attached a screenshot of a segment of Table 9-31, to show
> what that layout proposal looks like.  It's a little busier, but
> it does have the advantage that it's clearer how to apply that
> format to operator tables.  The "returns <type>" notation isn't used
> anywhere in SQL for operators, so I am not in love with the idea of
> writing the operator tables that way.

Yeah, that's a little less obvious.  I just noticed that the operators
tables show the operator names but not the input datatypes except in the
examples.  Perhaps we could use a layout with a cell labelled
"signature" (namest=col2 nameend=col3) instead of input types + return
types and separate them using &rightarrow; which would look like this:
   date + integer → date

> Also worth noting is that in most function tables, and certainly
> in the operator tables, we could make the first column narrower.
> The same table with the first column half as wide as the others
> is depicted in the last screenshot.  (For this particular table,
> doing that would require breaking some of the longer function
> names such as transaction_timestamp.  Not sure whether that's
> a net win, but we do have the option.)

I like making that column narrower.

> One issue that I've found is that the toolchain has no idea that
> the table rows are in groups, so it's happy to split a table
> across pages with a function's description and/or examples on
> a new page.  No idea if there's any way around that.  Fortunately
> it's not an issue in HTML, so maybe we don't have to fix it.

My vote goes to postponing a solution to this problem :-)

--
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
Alvaro Herrera <[hidden email]> writes:
> On 2020-Feb-12, Tom Lane wrote:
>> I also attached a screenshot of a segment of Table 9-31, to show
>> what that layout proposal looks like.  It's a little busier, but
>> it does have the advantage that it's clearer how to apply that
>> format to operator tables.  The "returns <type>" notation isn't used
>> anywhere in SQL for operators, so I am not in love with the idea of
>> writing the operator tables that way.

> Yeah, that's a little less obvious.  I just noticed that the operators
> tables show the operator names but not the input datatypes except in the
> examples.  Perhaps we could use a layout with a cell labelled
> "signature" (namest=col2 nameend=col3) instead of input types + return
> types and separate them using &rightarrow; which would look like this:
>    date + integer → date

Oh, that's a thought.  We could do the same for functions:

    function name           type1, type2, type3 → rettype
                            description ...
                            example         example result

which'd relieve the column-width pressure for functions with several
arguments.  On the other hand, that would look a little funny
for functions with no arguments ... not but what they're going to
look funny no matter what.  I used "none" in my conversion of
table 9.31, but wasn't satisfied with that, because it relies
completely on font choice to be distinguishable from a data type
named "none".  With a separate argument-types cell it'd likely be
better to just leave the cell empty, but do we want to write
just "→ rettype" in a signature cell?

The other thing I was struggling with was how to distinguish
normal zero-argument functions (written with parens) from those
SQL abominations that are function calls with no parens.  I think
we need to show that somehow, so that it's clear that the examples
are correct and not typos.  It doesn't have to be *totally* obvious,
perhaps, if we have an example to back it up ... but the example
can't be the only thing.

Maybe don't take out the parens?  So it'd work like

    Function               Signature

    age                    (timestamp) → interval

    now                    () → timestamp with time zone

    current_timestamp      → timestamp with time zone

Also, I think we're both imagining that we'd use the operator name
in operator signatures:

    Operator               Signature

    +                      integer + integer → integer

    +                      + integer → integer

so being consistent with that might suggest including the function name
in function signatures:

    Function               Signature

    age                    age(timestamp) → interval

    now                    now() → timestamp with time zone

    current_timestamp      current_timestamp → timestamp with time zone

I'm a bit suspicious of how much horizontal space that would eat, but
if we're able to get rid of the separate cell for result type, it
might work out OK.

                        regards, tom lane


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alvaro Herrera-9
On 2020-Feb-12, Tom Lane wrote:

> With a separate argument-types cell it'd likely be
> better to just leave the cell empty, but do we want to write
> just "→ rettype" in a signature cell?

Yeah, it'd look very odd, and certainly the no-parens case makes it
worse.  I like this end result:

> so being consistent with that might suggest including the function name
> in function signatures:
>
>     Function               Signature
>
>     age                    age(timestamp) → interval
>
>     now                    now() → timestamp with time zone
>
>     current_timestamp      current_timestamp → timestamp with time zone
>
> I'm a bit suspicious of how much horizontal space that would eat, but
> if we're able to get rid of the separate cell for result type, it
> might work out OK.

Regarding no-parens function signatures, perhaps we can add a footnote
indicating that such functions have this strange shape because of the
SQL committee, such as "&dagger; This function signature uses no
parentheses because the SQL standard defines it in that way."

--
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
Alvaro Herrera <[hidden email]> writes:
> Yeah, it'd look very odd, and certainly the no-parens case makes it
> worse.  I like this end result:

>> Function               Signature
>> age                    age(timestamp) → interval
>> now                    now() → timestamp with time zone
>> current_timestamp      current_timestamp → timestamp with time zone

I gave that a try, and it seems to work really well.  It can even handle
the ridiculously long signature for make_interval() in reasonable style,
as shown in the screenshot attached.

One problem with the rightarrow idea is that it's not rendering quite
right for me: it looks great in HTML, but in PDF it comes out flush
with the baseline, as you can see in the screenshot.  Hopefully
there's a way to fix that that we can hide in the custom entity ...
but I have no idea how.

I decided to try converting the date/time operators table too, to
see how well this works for that.  It's bulkier than before, but
also (I think) more precise.  I realized that this table actually
had three examples already for float8 * interval, but it wasn't
at all obvious that they were the same operator.  So that aspect
is a lot nicer here.  On the other hand, it seems like the text
descriptions are only marginally useful here.  I can imagine that
they would be useful in some other operator tables, such as
geometric operators, but I'm a bit tempted to leave them out
in this particular table.  The format would adapt to that easily.

Another thing worth considering is removing duplicate left-hand-
column entries, that is, considering all the instances of
similarly-named functions/operators to be "the same".  In the
attached patch, I did that for isfinite() but not anywhere else.
I'm not quite sure if it's a good idea or not.  It seems like it
makes sense for isfinite(), but perhaps less so for operators.

Again, comments welcome.  This is starting to feel like a real
proposal now, but I'm still not at all wedded to it.

                        regards, tom lane


diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index ceda48e..adfa571 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2934,7 +2934,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         the result written in hexadecimal
        </entry>
        <entry><literal>md5('Th\000omas'::bytea)</literal></entry>
-       <entry><literal>8ab2d3c9689aaf18&#x200B;b4958c334c82d8b1</literal></entry>
+       <entry><literal>8ab2d3c9689aaf18&break;b4958c334c82d8b1</literal></entry>
       </row>
 
       <row>
@@ -2985,7 +2985,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         SHA-224 <link linkend="functions-hash-note">hash</link>
        </entry>
        <entry><literal>sha224('abc'::bytea)</literal></entry>
-       <entry><literal>\x23097d223405d8228642a477bda2&#x200B;55b32aadbce4bda0b3f7e36c9da7</literal></entry>
+       <entry><literal>\x23097d223405d8228642a477bda2&break;55b32aadbce4bda0b3f7e36c9da7</literal></entry>
       </row>
 
       <row>
@@ -3000,7 +3000,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         SHA-256 <link linkend="functions-hash-note">hash</link>
        </entry>
        <entry><literal>sha256('abc'::bytea)</literal></entry>
-       <entry><literal>\xba7816bf8f01cfea414140de5dae2223&#x200B;b00361a396177a9cb410ff61f20015ad</literal></entry>
+       <entry><literal>\xba7816bf8f01cfea414140de5dae2223&break;b00361a396177a9cb410ff61f20015ad</literal></entry>
       </row>
 
       <row>
@@ -3015,7 +3015,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
         SHA-384 <link linkend="functions-hash-note">hash</link>
        </entry>
        <entry><literal>sha384('abc'::bytea)</literal></entry>
-       <entry><literal>\xcb00753f45a35e8bb5a03d699ac65007&#x200B;272c32ab0eded1631a8b605a43ff5bed&#x200B;8086072ba1e7cc2358baeca134c825a7</literal></entry>
+       <entry><literal>\xcb00753f45a35e8bb5a03d699ac65007&break;272c32ab0eded1631a8b605a43ff5bed&break;8086072ba1e7cc2358baeca134c825a7</literal></entry>
       </row>
 
       <row>
@@ -3030,7 +3030,7 @@ SELECT format('Testing %3$s, %2$s, %s', 'one', 'two', 'three');
          SHA-512 <link linkend="functions-hash-note">hash</link>
        </entry>
        <entry><literal>sha512('abc'::bytea)</literal></entry>
-       <entry><literal>\xddaf35a193617abacc417349ae204131&#x200B;12e6fa4e89a97ea20a9eeee64b55d39a&#x200B;2192992a274fc1a836ba3c23a3feebbd&#x200B;454d4423643ce80e2a9ac94fa54ca49f</literal></entry>
+       <entry><literal>\xddaf35a193617abacc417349ae204131&break;12e6fa4e89a97ea20a9eeee64b55d39a&break;2192992a274fc1a836ba3c23a3feebbd&break;454d4423643ce80e2a9ac94fa54ca49f</literal></entry>
       </row>
 
       <row>
@@ -6670,127 +6670,256 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
      <title>Date/Time Operators</title>
 
      <tgroup cols="3">
+      <colspec colnum="1" colname="col1" colwidth="0.25*"/>
+      <colspec colnum="2" colname="col2" colwidth="1*"/>
+      <colspec colnum="3" colname="col3" colwidth="1*"/>
+      <spanspec spanname="name" namest="col1" nameend="col1" align="left"/>
+      <spanspec spanname="sig" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
+      <spanspec spanname="exresult" namest="col3" nameend="col3" align="left"/>
       <thead>
        <row>
-        <entry>Operator</entry>
-        <entry>Example</entry>
-        <entry>Result</entry>
+        <entry spanname="name" align="center" morerows="2">Operator</entry>
+        <entry spanname="sig" align="center">Signature</entry>
+       </row>
+       <row>
+        <entry spanname="desc" align="center">Description</entry>
+       </row>
+       <row>
+        <entry spanname="example" align="center">Example</entry>
+        <entry spanname="exresult" align="center">Example Result</entry>
        </row>
       </thead>
 
       <tbody>
        <row>
-        <entry> <literal>+</literal> </entry>
-        <entry><literal>date '2001-09-28' + integer '7'</literal></entry>
-        <entry><literal>date '2001-10-05'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>+</literal> </entry>
+        <entry spanname="sig"><type>date</type> <literal>+</literal> <type>integer</type>
+         &returns; <type>date</type></entry>
        </row>
-
        <row>
-        <entry> <literal>+</literal> </entry>
-        <entry><literal>date '2001-09-28' + interval '1 hour'</literal></entry>
-        <entry><literal>timestamp '2001-09-28 01:00:00'</literal></entry>
+        <entry spanname="desc">Add a number of days to a date</entry>
        </row>
-
        <row>
-        <entry> <literal>+</literal> </entry>
-        <entry><literal>date '2001-09-28' + time '03:00'</literal></entry>
-        <entry><literal>timestamp '2001-09-28 03:00:00'</literal></entry>
+        <entry spanname="example"><literal>date '2001-09-28' + 7</literal></entry>
+        <entry spanname="exresult"><literal>2001-10-05</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>+</literal> </entry>
-        <entry><literal>interval '1 day' + interval '1 hour'</literal></entry>
-        <entry><literal>interval '1 day 01:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>+</literal> </entry>
+        <entry spanname="sig"><type>date</type> <literal>+</literal> <type>interval</type>
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Add an interval to a date</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date '2001-09-28' + interval '1 hour'</literal></entry>
+        <entry spanname="exresult"><literal>2001-09-28 01:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>+</literal> </entry>
-        <entry><literal>timestamp '2001-09-28 01:00' + interval '23 hours'</literal></entry>
-        <entry><literal>timestamp '2001-09-29 00:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>+</literal> </entry>
+        <entry spanname="sig"><type>date</type> <literal>+</literal> <type>time</type>
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Add a time-of-day to a date</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date '2001-09-28' + time '03:00'</literal></entry>
+        <entry spanname="exresult"><literal>2001-09-28 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>+</literal> </entry>
-        <entry><literal>time '01:00' + interval '3 hours'</literal></entry>
-        <entry><literal>time '04:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>+</literal> </entry>
+        <entry spanname="sig"><type>interval</type> <literal>+</literal> <type>interval</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Add intervals</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>interval '1 day' + interval '1 hour'</literal></entry>
+        <entry spanname="exresult"><literal>1 day 01:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>- interval '23 hours'</literal></entry>
-        <entry><literal>interval '-23:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>+</literal> </entry>
+        <entry spanname="sig"><type>timestamp</type> <literal>+</literal> <type>interval</type>
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Add an interval to a timestamp</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>timestamp '2001-09-28 01:00' + interval '23 hours'</literal></entry>
+        <entry spanname="exresult"><literal>2001-09-29 00:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>date '2001-10-01' - date '2001-09-28'</literal></entry>
-        <entry><literal>integer '3'</literal> (days)</entry>
+        <entry spanname="name" morerows="2"> <literal>+</literal> </entry>
+        <entry spanname="sig"><type>time</type> <literal>+</literal> <type>interval</type>
+         &returns; <type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Add an interval to a time</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>time '01:00' + interval '3 hours'</literal></entry>
+        <entry spanname="exresult"><literal>04:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>date '2001-10-01' - integer '7'</literal></entry>
-        <entry><literal>date '2001-09-24'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><literal>-</literal> <type>interval</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Negate an interval</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>- interval '23 hours'</literal></entry>
+        <entry spanname="exresult"><literal>-23:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>date '2001-09-28' - interval '1 hour'</literal></entry>
-        <entry><literal>timestamp '2001-09-27 23:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>date</type> <literal>-</literal> <type>date</type>
+         &returns; <type>integer</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract dates</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date '2001-10-01' - date '2001-09-28'</literal></entry>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>time '05:00' - time '03:00'</literal></entry>
-        <entry><literal>interval '02:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>date</type> <literal>-</literal> <type>integer</type>
+         &returns; <type>date</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract a number of days from a date</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date '2001-10-01' - 7</literal></entry>
+        <entry spanname="exresult"><literal>2001-09-24</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>time '05:00' - interval '2 hours'</literal></entry>
-        <entry><literal>time '03:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>date</type> <literal>-</literal> <type>interval</type>
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract an interval from a date</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date '2001-09-28' - interval '1 hour'</literal></entry>
+        <entry spanname="exresult"><literal>2001-09-27 23:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>timestamp '2001-09-28 23:00' - interval '23 hours'</literal></entry>
-        <entry><literal>timestamp '2001-09-28 00:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>time</type> <literal>-</literal> <type>time</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract times</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>time '05:00' - time '03:00'</literal></entry>
+        <entry spanname="exresult"><literal>02:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>interval '1 day' - interval '1 hour'</literal></entry>
-        <entry><literal>interval '1 day -01:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>time</type> <literal>-</literal> <type>interval</type>
+         &returns; <type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract an interval from a time</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>time '05:00' - interval '2 hours'</literal></entry>
+        <entry spanname="exresult"><literal>03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>-</literal> </entry>
-        <entry><literal>timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00'</literal></entry>
-        <entry><literal>interval '1 day 15:00:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>timestamp</type> <literal>-</literal> <type>interval</type>
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract an interval from a timestamp</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>timestamp '2001-09-28 23:00' - interval '23 hours'</literal></entry>
+        <entry spanname="exresult"><literal>2001-09-28 00:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>*</literal> </entry>
-        <entry><literal>900 * interval '1 second'</literal></entry>
-        <entry><literal>interval '00:15:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>interval</type> <literal>-</literal> <type>interval</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract intervals</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>interval '1 day' - interval '1 hour'</literal></entry>
+        <entry spanname="exresult"><literal>1 day -01:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>*</literal> </entry>
-        <entry><literal>21 * interval '1 day'</literal></entry>
-        <entry><literal>interval '21 days'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>-</literal> </entry>
+        <entry spanname="sig"><type>timestamp</type> <literal>-</literal> <type>timestamp</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract timestamps</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>timestamp '2001-09-29 03:00' - timestamp '2001-09-27 12:00'</literal></entry>
+        <entry spanname="exresult"><literal>1 day 15:00:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>*</literal> </entry>
-        <entry><literal>double precision '3.5' * interval '1 hour'</literal></entry>
-        <entry><literal>interval '03:30:00'</literal></entry>
+        <entry spanname="name" morerows="4"> <literal>*</literal> </entry>
+        <entry spanname="sig"><type>double precision</type> <literal>*</literal> <type>interval</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Multiply an interval by a scalar</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>900 * interval '1 second'</literal></entry>
+        <entry spanname="exresult"><literal>00:15:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>21 * interval '1 day'</literal></entry>
+        <entry spanname="exresult"><literal>21 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>3.5 * interval '1 hour'</literal></entry>
+        <entry spanname="exresult"><literal>03:30:00</literal></entry>
        </row>
 
        <row>
-        <entry> <literal>/</literal> </entry>
-        <entry><literal>interval '1 hour' / double precision '1.5'</literal></entry>
-        <entry><literal>interval '00:40:00'</literal></entry>
+        <entry spanname="name" morerows="2"> <literal>/</literal> </entry>
+        <entry spanname="sig"><type>interval</type> <literal>/</literal> <type>double precision</type>
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Divide an interval by a scalar</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>interval '1 hour' / 1.5</literal></entry>
+        <entry spanname="exresult"><literal>00:40:00</literal></entry>
        </row>
       </tbody>
      </tgroup>
@@ -6798,471 +6927,614 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
 
     <table id="functions-datetime-table">
      <title>Date/Time Functions</title>
-     <tgroup cols="5">
+     <tgroup cols="3">
+      <colspec colnum="1" colname="col1" colwidth="1*"/>
+      <colspec colnum="2" colname="col2" colwidth="1*"/>
+      <colspec colnum="3" colname="col3" colwidth="1*"/>
+      <spanspec spanname="name" namest="col1" nameend="col1" align="left"/>
+      <spanspec spanname="sig" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
+      <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
+      <spanspec spanname="exresult" namest="col3" nameend="col3" align="left"/>
       <thead>
        <row>
-        <entry>Function</entry>
-        <entry>Return Type</entry>
-        <entry>Description</entry>
-        <entry>Example</entry>
-        <entry>Result</entry>
+        <entry spanname="name" align="center" morerows="2">Function</entry>
+        <entry spanname="sig" align="center">Signature</entry>
+       </row>
+       <row>
+        <entry spanname="desc" align="center">Description</entry>
+       </row>
+       <row>
+        <entry spanname="example" align="center">Example</entry>
+        <entry spanname="exresult" align="center">Example Result</entry>
        </row>
       </thead>
 
       <tbody>
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>age</primary>
          </indexterm>
-         <literal><function>age(<type>timestamp</type>, <type>timestamp</type>)</function></literal>
+         <function>age</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Subtract arguments, producing a <quote>symbolic</quote> result that
+        <entry spanname="sig"><function>age</function>(<type>timestamp</type>, <type>timestamp</type>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract arguments, producing a <quote>symbolic</quote> result that
         uses years and months, rather than just days</entry>
-        <entry><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
-        <entry><literal>43 years 9 mons 27 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>age(timestamp '2001-04-10', timestamp '1957-06-13')</literal></entry>
+        <entry spanname="exresult"><literal>43 years 9 mons 27 days</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>age(<type>timestamp</type>)</function></literal></entry>
-        <entry><type>interval</type></entry>
-        <entry>Subtract from <function>current_date</function> (at midnight)</entry>
-        <entry><literal>age(timestamp '1957-06-13')</literal></entry>
-        <entry><literal>43 years 8 mons 3 days</literal></entry>
+        <entry spanname="name" morerows="2"><function>age</function></entry>
+        <entry spanname="sig"><function>age</function>(<type>timestamp</type>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Subtract from <function>current_date</function> (at midnight)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>age(timestamp '1957-06-13')</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>clock_timestamp</primary>
          </indexterm>
-         <literal><function>clock_timestamp()</function></literal>
+         <function>clock_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (changes during statement execution);
+        <entry spanname="sig"><function>clock_timestamp</function>()
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (changes during statement execution);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>clock_timestamp()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>current_date</primary>
          </indexterm>
-         <literal><function>current_date</function></literal>
+         <function>current_date</function>
         </entry>
-        <entry><type>date</type></entry>
-        <entry>Current date;
+        <entry spanname="sig"><function>current_date</function>
+         &returns; <type>date</type></entry>
+       </row>
+       <row>
+         <entry spanname="desc">Current date;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_date</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>current_time</primary>
          </indexterm>
-         <literal><function>current_time</function></literal>
+         <function>current_time</function>
         </entry>
-        <entry><type>time with time zone</type></entry>
-        <entry>Current time of day;
+        <entry spanname="sig"><function>current_time</function>
+         &returns; <type>time with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current time of day;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_time</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>current_timestamp</primary>
          </indexterm>
-         <literal><function>current_timestamp</function></literal>
+         <function>current_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="sig"><function>current_timestamp</function>
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>current_timestamp</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>date_part</primary>
          </indexterm>
-         <literal><function>date_part(<type>text</type>, <type>timestamp</type>)</function></literal>
+         <function>date_part</function>
         </entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield (equivalent to <function>extract</function>);
+        <entry spanname="sig"><function>date_part</function>(<type>text</type>, <type>timestamp</type>)
+         &returns; <type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield (equivalent to <function>extract</function>);
          see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>20</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_part('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
+        <entry spanname="exresult"><literal>20</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_part(<type>text</type>, <type>interval</type>)</function></literal></entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield (equivalent to
+        <entry spanname="name" morerows="2"><function>date_part</function></entry>
+        <entry spanname="sig"><function>date_part</function>(<type>text</type>, <type>interval</type>)
+         &returns; <type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield (equivalent to
          <function>extract</function>); see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>date_part('month', interval '2 years 3 months')</literal></entry>
-        <entry><literal>3</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_part('month', interval '2 years 3 months')</literal></entry>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>date_trunc</primary>
          </indexterm>
-         <literal><function>date_trunc(<type>text</type>, <type>timestamp</type>)</function></literal>
+         <function>date_trunc</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="sig"><function>date_trunc</function>(<type>text</type>, <type>timestamp</type>)
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>2001-02-16 20:00:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('hour', timestamp '2001-02-16 20:38:40')</literal></entry>
+        <entry spanname="exresult"><literal>2001-02-16 20:00:00</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_trunc(<type>text</type>, <type>timestamp with time zone</type>, <type>text</type>)</function></literal></entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="name" morerows="2"><function>date_trunc</function></entry>
+        <entry spanname="sig"><function>date_trunc</function>(<type>text</type>, <type>timestamp with time zone</type>, <type>text</type>)
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision in the specified time zone; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</literal></entry>
-        <entry><literal>2001-02-16 13:00:00+00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('day', timestamptz '2001-02-16 20:38:40+00', 'Australia/Sydney')</literal></entry>
+        <entry spanname="exresult"><literal>2001-02-16 13:00:00+00</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>date_trunc(<type>text</type>, <type>interval</type>)</function></literal></entry>
-        <entry><type>interval</type></entry>
-        <entry>Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
+        <entry spanname="name" morerows="2"><function>date_trunc</function></entry>
+        <entry spanname="sig"><function>date_trunc</function>(<type>text</type>, <type>interval</type>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Truncate to specified precision; see <xref linkend="functions-datetime-trunc"/>
         </entry>
-        <entry><literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal></entry>
-        <entry><literal>2 days 03:00:00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>date_trunc('hour', interval '2 days 3 hours 40 minutes')</literal></entry>
+        <entry spanname="exresult"><literal>2 days 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>extract</primary>
          </indexterm>
-         <literal><function>extract</function>(<parameter>field</parameter> from
-         <type>timestamp</type>)</literal>
+         <function>extract</function>
         </entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield; see <xref linkend="functions-datetime-extract"/>
+        <entry spanname="sig"><function>extract</function>(<parameter>field</parameter> <literal>from</literal> <type>timestamp</type>)
+         &returns; <type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield; see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
-        <entry><literal>20</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>extract(hour from timestamp '2001-02-16 20:38:40')</literal></entry>
+        <entry spanname="exresult"><literal>20</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>extract</function>(<parameter>field</parameter> from
-         <type>interval</type>)</literal></entry>
-        <entry><type>double precision</type></entry>
-        <entry>Get subfield; see <xref linkend="functions-datetime-extract"/>
+        <entry spanname="name" morerows="2"><function>extract</function></entry>
+        <entry spanname="sig"><function>extract</function>(<parameter>field</parameter> <literal>from</literal> <type>interval</type>)
+         &returns; <type>double precision</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Get subfield; see <xref linkend="functions-datetime-extract"/>
         </entry>
-        <entry><literal>extract(month from interval '2 years 3 months')</literal></entry>
-        <entry><literal>3</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>extract(month from interval '2 years 3 months')</literal></entry>
+        <entry spanname="exresult"><literal>3</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="8">
          <indexterm>
           <primary>isfinite</primary>
          </indexterm>
-         <literal><function>isfinite(<type>date</type>)</function></literal>
+         <function>isfinite</function>
         </entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite date (not +/-infinity)</entry>
-        <entry><literal>isfinite(date '2001-02-16')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="sig"><function>isfinite</function>(<type>date</type>)
+         &returns; <type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite date (not +/-infinity)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(date '2001-02-16')</literal></entry>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>isfinite(<type>timestamp</type>)</function></literal></entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite time stamp (not +/-infinity)</entry>
-        <entry><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="sig"><function>isfinite</function>(<type>timestamp</type>)
+         &returns; <type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite time stamp (not +/-infinity)</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(timestamp '2001-02-16 21:28:30')</literal></entry>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry><literal><function>isfinite(<type>interval</type>)</function></literal></entry>
-        <entry><type>boolean</type></entry>
-        <entry>Test for finite interval</entry>
-        <entry><literal>isfinite(interval '4 hours')</literal></entry>
-        <entry><literal>true</literal></entry>
+        <entry spanname="sig"><function>isfinite</function>(<type>interval</type>)
+         &returns; <type>boolean</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Test for finite interval</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>isfinite(interval '4 hours')</literal></entry>
+        <entry spanname="exresult"><literal>true</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>justify_days</primary>
          </indexterm>
-         <literal><function>justify_days(<type>interval</type>)</function></literal>
+         <function>justify_days</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval so 30-day time periods are represented as months</entry>
-        <entry><literal>justify_days(interval '35 days')</literal></entry>
-        <entry><literal>1 mon 5 days</literal></entry>
+        <entry spanname="sig"><function>justify_days</function>(<type>interval</type>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval so 30-day time periods are represented as months</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_days(interval '35 days')</literal></entry>
+        <entry spanname="exresult"><literal>1 mon 5 days</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>justify_hours</primary>
          </indexterm>
-         <literal><function>justify_hours(<type>interval</type>)</function></literal>
+         <function>justify_hours</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval so 24-hour time periods are represented as days</entry>
-        <entry><literal>justify_hours(interval '27 hours')</literal></entry>
-        <entry><literal>1 day 03:00:00</literal></entry>
+        <entry spanname="sig"><function>justify_hours</function>(<type>interval</type>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval so 24-hour time periods are represented as days</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_hours(interval '27 hours')</literal></entry>
+        <entry spanname="exresult"><literal>1 day 03:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>justify_interval</primary>
          </indexterm>
-         <literal><function>justify_interval(<type>interval</type>)</function></literal>
+         <function>justify_interval</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments</entry>
-        <entry><literal>justify_interval(interval '1 mon -1 hour')</literal></entry>
-        <entry><literal>29 days 23:00:00</literal></entry>
+        <entry spanname="sig"><function>justify_interval</function>(<type>interval</type>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Adjust interval using <function>justify_days</function> and <function>justify_hours</function>, with additional sign adjustments</entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>justify_interval(&break;interval '1 mon -1 hour')</literal></entry>
+        <entry spanname="exresult"><literal>29 days 23:00:00</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>localtime</primary>
          </indexterm>
-         <literal><function>localtime</function></literal>
+         <function>localtime</function>
         </entry>
-        <entry><type>time</type></entry>
-        <entry>Current time of day;
+        <entry spanname="sig"><function>localtime</function>
+         &returns; <type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current time of day;
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>localtime</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>localtimestamp</primary>
          </indexterm>
-         <literal><function>localtimestamp</function></literal>
+         <function>localtimestamp</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="sig"><function>localtimestamp</function>
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>localtimestamp</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>make_date</primary>
          </indexterm>
-         <literal>
-            <function>
-             make_date(<parameter>year</parameter> <type>int</type>,
-             <parameter>month</parameter> <type>int</type>,
-             <parameter>day</parameter> <type>int</type>)
-            </function>
-         </literal>
+         <function>make_date</function>
         </entry>
-        <entry><type>date</type></entry>
-        <entry>
+        <entry spanname="sig"><function>make_date</function>(<parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>)
+         &returns; <type>date</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create date from year, month and day fields
         </entry>
-        <entry><literal>make_date(2013, 7, 15)</literal></entry>
-        <entry><literal>2013-07-15</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_date(2013, 7, 15)</literal></entry>
+        <entry spanname="exresult"><literal>2013-07-15</literal></entry>
        </row>
 
        <row>
-        <entry>
-         <indexterm>
+        <entry spanname="name" morerows="2"><indexterm>
           <primary>make_interval</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_interval(<parameter>years</parameter> <type>int</type> DEFAULT 0,
-           <parameter>months</parameter> <type>int</type> DEFAULT 0,
-           <parameter>weeks</parameter> <type>int</type> DEFAULT 0,
-           <parameter>days</parameter> <type>int</type> DEFAULT 0,
-           <parameter>hours</parameter> <type>int</type> DEFAULT 0,
-           <parameter>mins</parameter> <type>int</type> DEFAULT 0,
-           <parameter>secs</parameter> <type>double precision</type> DEFAULT 0.0)
-          </function>
-         </literal>
+         <function>make_interval</function>
         </entry>
-        <entry><type>interval</type></entry>
-        <entry>
+        <entry spanname="sig"><function>make_interval</function>(<optional> <parameter>year</parameter> <type>int</type>
+         <optional>, <parameter>month</parameter> <type>int</type>
+         <optional>, <parameter>week</parameter> <type>int</type>
+         <optional>, <parameter>day</parameter> <type>int</type>
+         <optional>, <parameter>hour</parameter> <type>int</type>
+         <optional>, <parameter>min</parameter> <type>int</type>
+         <optional>, <parameter>sec</parameter> <type>double precision</type>
+         </optional></optional></optional></optional></optional></optional></optional>)
+         &returns; <type>interval</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create interval from years, months, weeks, days, hours, minutes and
-         seconds fields
+         seconds fields, each of which can default to zero
         </entry>
-        <entry><literal>make_interval(days =&gt; 10)</literal></entry>
-        <entry><literal>10 days</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_interval(days =&gt; 10)</literal></entry>
+        <entry spanname="exresult"><literal>10 days</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>make_time</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_time(<parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>)
-          </function>
-         </literal>
+         <function>make_time</function>
         </entry>
-        <entry><type>time</type></entry>
-        <entry>
+        <entry spanname="sig"><function>make_time</function>(<parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type>)
+         &returns; <type>time</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create time from hour, minute and seconds fields
         </entry>
-        <entry><literal>make_time(8, 15, 23.5)</literal></entry>
-        <entry><literal>08:15:23.5</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_time(8, 15, 23.5)</literal></entry>
+        <entry spanname="exresult"><literal>08:15:23.5</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>make_timestamp</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_timestamp(<parameter>year</parameter> <type>int</type>,
-           <parameter>month</parameter> <type>int</type>,
-           <parameter>day</parameter> <type>int</type>,
-           <parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>)
-          </function>
-         </literal>
+         <function>make_timestamp</function>
         </entry>
-        <entry><type>timestamp</type></entry>
-        <entry>
+        <entry spanname="sig"><function>make_timestamp</function>(<parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>,
+         <parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type>)
+         &returns; <type>timestamp</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create timestamp from year, month, day, hour, minute and seconds fields
         </entry>
-        <entry><literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal></entry>
-        <entry><literal>2013-07-15 08:15:23.5</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_timestamp(2013, 7, 15, 8, 15, 23.5)</literal></entry>
+        <entry spanname="exresult"><literal>2013-07-15 08:15:23.5</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>make_timestamptz</primary>
          </indexterm>
-         <literal>
-          <function>
-           make_timestamptz(<parameter>year</parameter> <type>int</type>,
-           <parameter>month</parameter> <type>int</type>,
-           <parameter>day</parameter> <type>int</type>,
-           <parameter>hour</parameter> <type>int</type>,
-           <parameter>min</parameter> <type>int</type>,
-           <parameter>sec</parameter> <type>double precision</type>,
-           <optional> <parameter>timezone</parameter> <type>text</type> </optional>)
-          </function>
-         </literal>
+         <function>make_timestamptz</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>
+        <entry spanname="sig"><function>make_timestamptz</function>(<parameter>year</parameter> <type>int</type>,
+         <parameter>month</parameter> <type>int</type>,
+         <parameter>day</parameter> <type>int</type>,
+         <parameter>hour</parameter> <type>int</type>,
+         <parameter>min</parameter> <type>int</type>,
+         <parameter>sec</parameter> <type>double precision</type>
+         <optional>, <parameter>timezone</parameter> <type>text</type> </optional>)
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">
          Create timestamp with time zone from year, month, day, hour, minute
          and seconds fields; if <parameter>timezone</parameter> is not
          specified, the current time zone is used
         </entry>
-        <entry><literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal></entry>
-        <entry><literal>2013-07-15 08:15:23.5+01</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>make_timestamptz(2013, 7, 15, 8, 15, 23.5)</literal></entry>
+        <entry spanname="exresult"><literal>2013-07-15 08:15:23.5+01</literal></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>now</primary>
          </indexterm>
-         <literal><function>now()</function></literal>
+         <function>now</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="sig"><function>now</function>()
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>now()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>statement_timestamp</primary>
          </indexterm>
-         <literal><function>statement_timestamp()</function></literal>
+         <function>statement_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current statement);
+        <entry spanname="sig"><function>statement_timestamp</function>()
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current statement);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>statement_timestamp()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>timeofday</primary>
          </indexterm>
-         <literal><function>timeofday()</function></literal>
+         <function>timeofday</function>
         </entry>
-        <entry><type>text</type></entry>
-        <entry>Current date and time
+        <entry spanname="sig"><function>timeofday</function>()
+         &returns; <type>text</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time
          (like <function>clock_timestamp</function>, but as a <type>text</type> string);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>timeofday()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
        </row>
 
        <row>
-        <entry>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>transaction_timestamp</primary>
          </indexterm>
-         <literal><function>transaction_timestamp()</function></literal>
+         <function>transaction_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Current date and time (start of current transaction);
+        <entry spanname="sig"><function>transaction_timestamp</function>()
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Current date and time (start of current transaction);
          see <xref linkend="functions-datetime-current"/>
         </entry>
-        <entry></entry>
-        <entry></entry>
        </row>
        <row>
-        <entry>
+        <entry spanname="example"><literal>transaction_&break;timestamp()</literal></entry>
+        <entry spanname="exresult"><replaceable>variable</replaceable></entry>
+       </row>
+       <row>
+        <entry spanname="name" morerows="2">
          <indexterm>
           <primary>to_timestamp</primary>
          </indexterm>
-         <literal><function>to_timestamp(<type>double precision</type>)</function></literal>
+         <function>to_timestamp</function>
         </entry>
-        <entry><type>timestamp with time zone</type></entry>
-        <entry>Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
+        <entry spanname="sig"><function>to_timestamp</function>(<type>double precision</type>)
+         &returns; <type>timestamp with time zone</type></entry>
+       </row>
+       <row>
+        <entry spanname="desc">Convert Unix epoch (seconds since 1970-01-01 00:00:00+00) to
          timestamp</entry>
-        <entry><literal>to_timestamp(1284352323)</literal></entry>
-        <entry><literal>2010-09-13 04:32:03+00</literal></entry>
+       </row>
+       <row>
+        <entry spanname="example"><literal>to_timestamp(&break;1284352323)</literal></entry>
+        <entry spanname="exresult"><literal>2010-09-13 04:32:03+00</literal></entry>
        </row>
       </tbody>
      </tgroup>
@@ -8236,52 +8508,83 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
 
   <table id="functions-enum-table">
     <title>Enum Support Functions</title>
-    <tgroup cols="4">
+    <tgroup cols="3">
+     <colspec colnum="1" colname="col1" colwidth="0.5*"/>
+     <colspec colnum="2" colname="col2" colwidth="1*"/>
+     <colspec colnum="3" colname="col3" colwidth="1*"/>
+     <spanspec spanname="name" namest="col1" nameend="col1" align="left"/>
+     <spanspec spanname="sig" namest="col2" nameend="col3" align="left"/>
+     <spanspec spanname="desc" namest="col2" nameend="col3" align="left"/>
+     <spanspec spanname="example" namest="col2" nameend="col2" align="left"/>
+     <spanspec spanname="exresult" namest="col3" nameend="col3" align="left"/>
      <thead>
       <row>
-       <entry>Function</entry>
-       <entry>Description</entry>
-       <entry>Example</entry>
-       <entry>Example Result</entry>
+       <entry spanname="name" align="center" morerows="2">Function</entry>
+       <entry spanname="sig" align="center">Signature</entry>
+      </row>
+      <row>
+       <entry spanname="desc" align="center">Description</entry>
+      </row>
+      <row>
+       <entry spanname="example" align="center">Example</entry>
+       <entry spanname="exresult" align="center">Example Result</entry>
       </row>
      </thead>
      <tbody>
       <row>
-       <entry>
-         <indexterm>
-          <primary>enum_first</primary>
-         </indexterm>
-         <literal>enum_first(anyenum)</literal>
+       <entry spanname="name" morerows="2">
+        <indexterm>
+         <primary>enum_first</primary>
+        </indexterm>
+        <function>enum_first</function>
        </entry>
-       <entry>Returns the first value of the input enum type</entry>
-       <entry><literal>enum_first(null::rainbow)</literal></entry>
-       <entry><literal>red</literal></entry>
+       <entry spanname="sig"><function>enum_first</function>(<type>anyenum</type>) &returns; <type>anyenum</type></entry>
       </row>
       <row>
-       <entry>
-         <indexterm>
-          <primary>enum_last</primary>
-         </indexterm>
-         <literal>enum_last(anyenum)</literal>
+       <entry spanname="desc">Returns the first value of the input enum type</entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_first(&break;null::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>red</literal></entry>
+      </row>
+      <row>
+       <entry spanname="name" morerows="2">
+        <indexterm>
+         <primary>enum_last</primary>
+        </indexterm>
+        <function>enum_last</function>
        </entry>
-       <entry>Returns the last value of the input enum type</entry>
-       <entry><literal>enum_last(null::rainbow)</literal></entry>
-       <entry><literal>purple</literal></entry>
+       <entry spanname="sig"><function>enum_last</function>(<type>anyenum</type>) &returns; <type>anyenum</type></entry>
       </row>
       <row>
-       <entry>
-         <indexterm>
-          <primary>enum_range</primary>
-         </indexterm>
-         <literal>enum_range(anyenum)</literal>
+       <entry spanname="desc">Returns the last value of the input enum type</entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_last(&break;null::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>purple</literal></entry>
+      </row>
+      <row>
+       <entry spanname="name" morerows="2">
+        <indexterm>
+         <primary>enum_range</primary>
+        </indexterm>
+        <function>enum_range</function>
        </entry>
-       <entry>Returns all values of the input enum type in an ordered array</entry>
-       <entry><literal>enum_range(null::rainbow)</literal></entry>
-       <entry><literal>{red,orange,yellow,green,blue,purple}</literal></entry>
+       <entry spanname="sig"><function>enum_range</function>(<type>anyenum</type>) &returns; <type>anyarray</type></entry>
+      </row>
+      <row>
+       <entry spanname="desc">Returns all values of the input enum type in an ordered array</entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range(&break;null::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>{red,orange,yellow,&break;green,blue,purple}</literal></entry>
+      </row>
+      <row>
+       <entry spanname="name" morerows="4"><function>enum_range</function></entry>
+       <entry spanname="sig"><function>enum_range</function>(<type>anyenum</type>, <type>anyenum</type>) &returns; <type>anyarray</type></entry>
       </row>
       <row>
-       <entry morerows="2"><literal>enum_range(anyenum, anyenum)</literal></entry>
-       <entry morerows="2">
+       <entry spanname="desc">
         Returns the range between the two given enum values, as an ordered
         array. The values must be from the same enum type. If the first
         parameter is null, the result will start with the first value of
@@ -8289,16 +8592,18 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple
         If the second parameter is null, the result will end with the last
         value of the enum type.
        </entry>
-       <entry><literal>enum_range('orange'::rainbow, 'green'::rainbow)</literal></entry>
-       <entry><literal>{orange,yellow,green}</literal></entry>
       </row>
       <row>
-       <entry><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
-       <entry><literal>{red,orange,yellow,green}</literal></entry>
+       <entry spanname="example"><literal>enum_range(&break;'orange'::rainbow, 'green'::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>{orange,yellow,green}</literal></entry>
+      </row>
+      <row>
+       <entry spanname="example"><literal>enum_range(NULL, 'green'::rainbow)</literal></entry>
+       <entry spanname="exresult"><literal>{red,orange,yellow,&break;green}</literal></entry>
       </row>
       <row>
-       <entry><literal>enum_range('orange'::rainbow, NULL)</literal></entry>
-       <entry><literal>{orange,yellow,green,blue,purple}</literal></entry>
+       <entry spanname="example"><literal>enum_range(&break;'orange'::rainbow, NULL)</literal></entry>
+       <entry spanname="exresult"><literal>{orange,yellow,green,&break;blue,purple}</literal></entry>
       </row>
      </tbody>
     </tgroup>
diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e59cba7..bfe5661 100644
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -11,6 +11,12 @@
 
 <!ENTITY reference  SYSTEM "reference.sgml">
 
+<!-- zero-width space; use this to allow line breaks within table cells -->
+<!ENTITY break "&#x200B;">
+
+<!-- right arrow; use this to introduce function/operator return types -->
+<!ENTITY returns "&#x2192;">
+
 ]>
 
 <book id="postgres">

table-9-31-take2.png (403K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alexander Lakhin-2
In reply to this post by Tom Lane-2
12.02.2020 23:58, Tom Lane wrote:

> Alexander Lakhin <[hidden email]> writes:
>> Please look at a less invasive approach that we use at Postgres Pro for
>> some time (mainly for improving the translated documentation, but it
>> works for the original one too). The idea is to add zero-width spaces
>> after/before some chars ('(', ',', '[', etc) to let fop split lines
>> where desired. It has one disadvantage - it's not search-friendly
>> (though maybe that is application-dependent).
>> But if it's feasible, I think this approach can at least complement a
>> manual tables reformatting. Decreasing a font size in the tables seems
>> appropriate to me too.
> Hmm, interesting proposal.  I experimented and verified that injecting
> zero-width space (&#x200B;) does allow line breaking to occur in both
> HTML and PDF output, so this could be a route to improving the situation
> for overlength example texts.  I do not think I like the idea of
> automatically injecting tons of them, though.  As you say, it might
> hinder searching; and it would allow some silly breaks; and there are
> cases where it still wouldn't find a break, such as the examples for
> sha256() et al.  I'd be happier about manually inserting breaks just
> in the places we really need them.  To keep the source readable, I'd
> want to write something like "&zwsp;" not a numeric entity code,
> but it looks like we can define custom entities if we want.
Yes, I was starting with manual &zwsp; insertions into the translation,
but later I reduced such insertions just to several dozens. (For
example, we still have "3.1415926535&zwsp;8979323846" in the translation.)
The main issue of the manual approach was that I needed to recheck that
zwsp placement on updates, and I can't see where it's desired until I
generate pdf. Fortunately, fop prints warning like that:
[WARN] FOUserAgent - The contents of fo:block line 2 exceed the
available area in the inline-progression direction by 22725 millipoints.
(See position 127769:983)
It's not very user-friendly, but still useful when we have a pair or two
of them. (For now, I see 559 such warnings in REL_12_STABLE.)
Second issue is that the placement can depend on the page size and in
fact most of that zwsps are not needed for html or other formats
(moreover, some formats can require different placements (if we're not
just implementing some common rules)).
Third (minor) issue is with translation - when I will see some break in
the English source, e.g. "split_part('abc~@~def&zwsp;~@~ghi', '~@~',
2)", should I leave the break in the same place, or it's better to move
it because adjacent text has different length and the table columns have
different width?

For me this approach expresses a belief that the line breaking rules
should be slightly different in our context. For example, having line
break after an opening bracket is feasible and common in function calls
and declarations. Maybe the rules in the proposed xslt could be
improved/restricted, but I think that if fop would allow us to enable an
imaginary 'programming language line breaking rules' mode, we would use
it for our tables (some or all).
Maybe some of the rules can be implemented explicitly in the DocBook
source, just to reduce tons of zwsp in the generated output, or the
"fo:table-cell/fo:block//text()" condition can be improved to filter
some (text-only?) tables out, but I think that the idea of our specific
line breaking rules could work.

Best regards,
Alexander


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alvaro Herrera-9
On 2020-Feb-13, Alexander Lakhin wrote:

> Yes, I was starting with manual &zwsp; insertions into the translation,
> but later I reduced such insertions just to several dozens. (For
> example, we still have "3.1415926535&zwsp;8979323846" in the translation.)
> The main issue of the manual approach was that I needed to recheck that
> zwsp placement on updates, and I can't see where it's desired until I
> generate pdf. Fortunately, fop prints warning like that:
> [WARN] FOUserAgent - The contents of fo:block line 2 exceed the
> available area in the inline-progression direction by 22725 millipoints.
> (See position 127769:983)
> It's not very user-friendly, but still useful when we have a pair or two
> of them.

It seems to me that a productive way forward would be to fix the layout
to make these warning disappear. Then it will be relatively easy to find
where to fix, if new ones appear.

Now I suppose you're complaining about the "position 127769:983" part of
the error message which tells you with zero clarity where the problem
is.  Maybe what we need is to figure out what the numbers mean, and how
to use them; for example if they are byte offsets into the file, then it
should be possible to tell your editor to go to that byte in the
complete XML file.

> Second issue is that the placement can depend on the page size and in
> fact most of that zwsps are not needed for html or other formats
> (moreover, some formats can require different placements (if we're not
> just implementing some common rules)).

I suppose A4 page size is going to show slightly different warnings than
Letter page size in the PDF output.  Perhaps we can say that we only
care about warnings in one of them, for these purposes.

Having to touch 500+ places does not sound very appetizing, for sure.

> Third (minor) issue is with translation - when I will see some break in
> the English source, e.g. "split_part('abc~@~def&zwsp;~@~ghi', '~@~',
> 2)", should I leave the break in the same place, or it's better to move
> it because adjacent text has different length and the table columns have
> different width?

If the English version is warning-clean, then it should be possible to
keep the zwsps in the same location in the translation, and then tweak
the translation according to any new warnings that appear there.
My guess is that the majority of zwsps are going to want to stay in the
same place.

> Maybe some of the rules can be implemented explicitly in the DocBook
> source, just to reduce tons of zwsp in the generated output, or the
> "fo:table-cell/fo:block//text()" condition can be improved to filter
> some (text-only?) tables out, but I think that the idea of our specific
> line breaking rules could work.

Maybe we can mark-up specific table cells/columns as being subject to
the special line breaking rules.

--
Álvaro Herrera                https://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alexander Lakhin-2
Hello Alvaro,
14.02.2020 23:16, Alvaro Herrera wrote:
On 2020-Feb-13, Alexander Lakhin wrote:

Yes, I was starting with manual &zwsp; insertions into the translation,
but later I reduced such insertions just to several dozens. (For
example, we still have "3.1415926535&zwsp;8979323846" in the translation.)
The main issue of the manual approach was that I needed to recheck that
zwsp placement on updates, and I can't see where it's desired until I
generate pdf. Fortunately, fop prints warning like that:
[WARN] FOUserAgent - The contents of fo:block line 2 exceed the
available area in the inline-progression direction by 22725 millipoints.
(See position 127769:983)
It's not very user-friendly, but still useful when we have a pair or two
of them.
It seems to me that a productive way forward would be to fix the layout
to make these warning disappear. Then it will be relatively easy to find
where to fix, if new ones appear.

Now I suppose you're complaining about the "position 127769:983" part of
the error message which tells you with zero clarity where the problem
is.  Maybe what we need is to figure out what the numbers mean, and how
to use them; for example if they are byte offsets into the file, then it
should be possible to tell your editor to go to that byte in the
complete XML file.
I'm not complaining about the cryptic position of the problems, I'm concerned with their number.
The position is specified as {line_number}:{character_postition} in postgres-*.fo (not in the DocBook source).
For example, when performing `make postgres-A4.pdf` on REL_12_STABLE I get:
[WARN] FOUserAgent - The contents of fo:block line 1 exceed the available area in the inline-progression direction by more than 50 points. (See position 28808:374)

To find an exact problematic text you can look at the specified line(s) of postgres-A4.fo:
$ sed -n '28808,28811p' postgres-A4.fo
<fo:block id="id-1.5.13.4.7.12.1" wrap-option="wrap" text-align="start" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" space-after.minimum="0.8em" space-after.optimum="1em" space-after.maximum="1.2em" hyphenate="false" white-space-collapse="false" white-space-treatment="preserve" linefeed-treatment="preserve" font-family="monospace">
EXPLAIN SELECT * FROM tenk1 WHERE unique1 &lt; 100;

Searching this text in pdf gets you to page 467 where you can see a long line of '---' going of the page...
Third (minor) issue is with translation - when I will see some break in
the English source, e.g. "split_part('abc~@~def&zwsp;~@~ghi', '~@~',
2)", should I leave the break in the same place, or it's better to move
it because adjacent text has different length and the table columns have
different width?
If the English version is warning-clean, then it should be possible to
keep the zwsps in the same location in the translation, and then tweak
the translation according to any new warnings that appear there.
My guess is that the majority of zwsps are going to want to stay in the
same place.
Yes, that's why I consider this as minor issue, but some kind of an automatic solution can eliminate it at all.
Maybe some of the rules can be implemented explicitly in the DocBook
source, just to reduce tons of zwsp in the generated output, or the
"fo:table-cell/fo:block//text()" condition can be improved to filter
some (text-only?) tables out, but I think that the idea of our specific
line breaking rules could work.
Maybe we can mark-up specific table cells/columns as being subject to
the special line breaking rules.
Things made complicated by the xslt preprocessor, because you can't see Docbook tags and attributes on a FOP level, but I can explore possible resolutions if we choose to go this way.

Best regards,
Alexander
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
In reply to this post by Alvaro Herrera-9
Alvaro Herrera <[hidden email]> writes:
> On 2020-Feb-13, Alexander Lakhin wrote:
>> Third (minor) issue is with translation - when I will see some break in
>> the English source, e.g. "split_part('abc~@~def&zwsp;~@~ghi', '~@~',
>> 2)", should I leave the break in the same place, or it's better to move
>> it because adjacent text has different length and the table columns have
>> different width?

> If the English version is warning-clean, then it should be possible to
> keep the zwsps in the same location in the translation, and then tweak
> the translation according to any new warnings that appear there.
> My guess is that the majority of zwsps are going to want to stay in the
> same place.

So far as I've seen, the majority of places where we'll still need to
insert break opportunities are in examples and example results, which
don't seem like they'd be subject to translation.  I'm really not eager to
turn loose an automatic-zwsp-inserter for a problem that might be mostly
hypothetical once we have a more forgiving table layout in place.

                        regards, tom lane


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
In reply to this post by Tom Lane-2
I wrote:
> One problem with the rightarrow idea is that it's not rendering quite
> right for me: it looks great in HTML, but in PDF it comes out flush
> with the baseline, as you can see in the screenshot.  Hopefully
> there's a way to fix that that we can hide in the custom entity ...
> but I have no idea how.

I poked at this a little bit, and found that I could get a pretty
decent-looking result if I hacked the .fo file to contain
"<fo:inline baseline-shift="10%">→</fo:inline>" rather than a bare
right arrow.  (See attached screenshot, wherein the last rightarrow
was fixed this way but the others weren't.)  However, I do not
have much of a clue as to how such a fix might be injected into
our stylesheets --- anybody have a suggestion?

                        regards, tom lane


baseline-shift.png (90K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alexander Lakhin-2
Hello Tom,

> 16.02.2020 23:07, Tom Lane wrote:
>
>
> I poked at this a little bit, and found that I could get a pretty
> decent-looking result if I hacked the .fo file to contain
> "<fo:inline baseline-shift="10%">→</fo:inline>" rather than a bare
> right arrow.  (See attached screenshot, wherein the last rightarrow
> was fixed this way but the others weren't.)  However, I do not
> have much of a clue as to how such a fix might be injected into
> our stylesheets --- anybody have a suggestion?
Please look at the XSLT template for processing .fo before calling fop.
Maybe this can be done with just the existing stylesheet-fo.xsl, I'll
try to research this later.

Best regards,
Alexander


shift_arrow_up.patch (2K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Alexander Lakhin-2
17.02.2020 00:21, Alexander Lakhin wrote:

> Hello Tom,
>> 16.02.2020 23:07, Tom Lane wrote:
>>
>>
>> I poked at this a little bit, and found that I could get a pretty
>> decent-looking result if I hacked the .fo file to contain
>> "<fo:inline baseline-shift="10%">→</fo:inline>" rather than a bare
>> right arrow.  (See attached screenshot, wherein the last rightarrow
>> was fixed this way but the others weren't.)  However, I do not
>> have much of a clue as to how such a fix might be injected into
>> our stylesheets --- anybody have a suggestion?
> Please look at the XSLT template for processing .fo before calling fop.
> Maybe this can be done with just the existing stylesheet-fo.xsl, I'll
> try to research this later.
I've managed to simplify the patch a little by incorporating those
templates in stylesheet-fo.xsl.

Maybe it's better to use the same formatting as in the docbook xsl
template (see docbook/stylesheet/docbook-xsl/xhtml-1_1/inline.xsl).
There "$menuchoice.menu.separator" is enclosed in <fo:inline
font-size=".75em" font-family="{$symbol.font.family}">...</fo:inline>
and you can see the effect on page 536 (IPC parameters can be set in the
System Administration Manager (SAM) under Kernel Configu-
ration → Configurable Parameters.)

Yet another possibility is to use the docbook tags:
<funcdef><function>func()</function>
<returnvalue>int</returnvalue></funcdef>.
Then we can define the desired formatting for such markup (similar to
<menuchoice><guimenu>...</guimenu><guimenuitem>...</guimenuitem></menuchoice>).

Best regards,
Alexander

shift_arrow_up2.patch (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
I set this idea aside during the final v13 commitfest, but I figure that
it's fine to work on documentation improvements during feature freeze,
so I'm going to try to push it forward over the next few weeks.

Barring objections, I want to commit more or less what I posted at [1],
verify that it looks decent on the website, and then incrementally
convert the rest of our function/operator tables to the new style.
It's too big a job to get done in one commit, but a table or two at
a time seems like a reasonable approach.  After the table format
conversion is finished we can take a look at how much of a
bad-line-breaks issue we still have, and decide what to do about that.

First though, we need to nail down exactly what markup to use.

Alexander Lakhin <[hidden email]> writes:
> Maybe it's better to use the same formatting as in the docbook xsl
> template (see docbook/stylesheet/docbook-xsl/xhtml-1_1/inline.xsl).
> There "$menuchoice.menu.separator" is enclosed in <fo:inline
> font-size=".75em" font-family="{$symbol.font.family}">...</fo:inline>
> and you can see the effect on page 536 (IPC parameters can be set in the
> System Administration Manager (SAM) under Kernel Configu-
> ration → Configurable Parameters.)

Yeah, I see that that uses a right-arrow and it looks quite decent in
both HTML and PDF renderings.  So we ought to borrow those markup details
rather than solving the problem from scratch.

> Yet another possibility is to use the docbook tags:
> <funcdef><function>func()</function>
> <returnvalue>int</returnvalue></funcdef>.
> Then we can define the desired formatting for such markup (similar to
> <menuchoice><guimenu>...</guimenu><guimenuitem>...</guimenuitem></menuchoice>).

I looked into this.  It appears that <funcdef> is fairly tightly tied
to C function declaration syntax, plus it sounds like it might get
deprecated in future docbook versions.  So I don't want to use that.
But we could use <returnvalue> which seems to be defined independently
of <funcdef>, and isn't being used in our docs at present.  I found
by experimentation that this doesn't work:

  <returnvalue><type>date</type></returnvalue>

(it complains that these two tag types can't be nested); but this does:

  <returnvalue>date</returnvalue>

So if we can get <returnvalue> to both insert a right arrow and switch the
font to match <type>'s choice, this would work more or less decently, and
it's probably cleaner than the bare-entity-reference approach I posted
before.  I don't have the XSL skills to get that to work though.
Anyone want to help out?

                        regards, tom lane

[1] https://www.postgresql.org/message-id/23574.1581555393%40sss.pgh.pa.us


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Corey Huinker
On Sat, Apr 11, 2020 at 4:51 PM Tom Lane <[hidden email]> wrote:
I set this idea aside during the final v13 commitfest, but I figure that
it's fine to work on documentation improvements during feature freeze,
so I'm going to try to push it forward over the next few weeks.

If it's ok to work on doc patches during the feature freeze, and if we're already tweaking function documentation, would it be possible to add in anchor ids to function definitions so that we could reference specific functions (or rather the family of functions that share a name like this: https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART or similar. I tried it out just now, and the anchoring works, but there's no obvious place to acquire the anchored link, so presumably we'd anchor-ize the function name itself.


 
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
Corey Huinker <[hidden email]> writes:
> If it's ok to work on doc patches during the feature freeze, and if we're
> already tweaking function documentation, would it be possible to add in
> anchor ids to function definitions so that we could reference specific
> functions (or rather the family of functions that share a name like this:
> https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART
> or similar. I tried it out just now, and the anchoring works, but there's
> no obvious place to acquire the anchored link, so presumably we'd
> anchor-ize the function name itself.

Don't have a strong opinion about that, but it'd sure be a lot of new
anchors.  Is that going to be a problem for the docs toolchain?  If
the anchors are attached to individual function names rather than
sections or paragraphs, do they actually work well as link references?
(I'm particularly wondering how an <xref> would render.)

                        regards, tom lane


Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Corey Huinker
On Sat, Apr 11, 2020 at 6:41 PM Tom Lane <[hidden email]> wrote:
Corey Huinker <[hidden email]> writes:
> If it's ok to work on doc patches during the feature freeze, and if we're
> already tweaking function documentation, would it be possible to add in
> anchor ids to function definitions so that we could reference specific
> functions (or rather the family of functions that share a name like this:
> https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART
> or similar. I tried it out just now, and the anchoring works, but there's
> no obvious place to acquire the anchored link, so presumably we'd
> anchor-ize the function name itself.

Don't have a strong opinion about that, but it'd sure be a lot of new
anchors. 

True, but it'd would be a lot better than pointing a person to a page that has 20+ functions defined on it.
 
Is that going to be a problem for the docs toolchain?  If
the anchors are attached to individual function names rather than
sections or paragraphs, do they actually work well as link references?
(I'm particularly wondering how an <xref> would render.)

So I can't speak to any scalability issues for adding a bunch of refs, but I did try this out for justify_days() (diff attached) and here's what I found:
* <link linkend="function-justify-days">justify_days</link> 
   This made a link, in the same font as any other link ref.
* <xref linkend="function-justify-days"/> 
   This made a link that looks exactly like the previous one, with the text "justify_days", so if we're fine with the font change, we could use that
* <link linkend="function-justify-days"><function>justify_days</function></link>
   This made the link we want in the function font.

The docbook spec doesn't allow an xref inside a function tag, and no tags at all can be inside an xref.
 

link-one-function.diff (1K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Jürgen Purtz
In reply to this post by Tom Lane-2


On 11.04.20 22:51, Tom Lane wrote:
Yet another possibility is to use the docbook tags:
<funcdef><function>func()</function>
<returnvalue>int</returnvalue></funcdef>.
Then we can define the desired formatting for such markup (similar to
<menuchoice><guimenu>...</guimenu><guimenuitem>...</guimenuitem></menuchoice>).
I looked into this.  It appears that <funcdef> is fairly tightly tied
to C function declaration syntax, plus it sounds like it might get
deprecated in future docbook versions.

funcsynopsis, funcdef, function, ... keeps valid in Docbook 5, see: https://tdg.docbook.org/tdg/5.1/funcsynopsis.html . There is even an option to distinguish between K&R and ANSI style during rendering: <?dbhtml funcsynopsis-style='kr'?>

Kind regards, Jürgen Purtz

Reply | Threaded
Open this post in threaded view
|

Re: Getting our tables to render better in PDF output

Tom Lane-2
In reply to this post by Tom Lane-2
I wrote:
> So if we can get <returnvalue> to both insert a right arrow and switch the
> font to match <type>'s choice, this would work more or less decently, and
> it's probably cleaner than the bare-entity-reference approach I posted
> before.  I don't have the XSL skills to get that to work though.
> Anyone want to help out?

I educated myself a teensy bit about XSL, and unless I'm missing
something, this is really pretty darn trivial; the attached seems
to do the trick.

I experimented with the markup from <guimenuitem> and decided that
I didn't like their choice of a smaller font size in this context;
it looks better to me to leave the arrow full-size.  The important
thing to learn from that precedent seems to be that we have to
specify the font correctly, as indeed is mentioned in the docbook
documentation.  So it seems to work well to just use

    <fo:inline font-family="{$symbol.font.family}">&#x2192; </fo:inline>

(The extra space seems to be necessary, else the arrow ends up
adjacent to the type name.)

So I'm pretty happy with this implementation and will push forward.

                        regards, tom lane


diff --git a/doc/src/sgml/stylesheet-common.xsl b/doc/src/sgml/stylesheet-common.xsl
index e148c90..5936d9a 100644
--- a/doc/src/sgml/stylesheet-common.xsl
+++ b/doc/src/sgml/stylesheet-common.xsl
@@ -49,6 +49,11 @@
   <xsl:call-template name="inline.charseq"/>
 </xsl:template>
 
+<xsl:template match="returnvalue">
+  &#x2192;
+  <xsl:call-template name="inline.monoseq"/>
+</xsl:template>
+
 <xsl:template match="structfield">
   <xsl:call-template name="inline.monoseq"/>
 </xsl:template>
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index ea75408..a3b6463 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -63,6 +63,12 @@
   </fo:inline>
 </xsl:template>
 
+<!-- overrides stylesheet-common.xsl -->
+<xsl:template match="returnvalue">
+  <fo:inline font-family="{$symbol.font.family}">&#x2192; </fo:inline>
+  <xsl:call-template name="inline.monoseq"/>
+</xsl:template>
+
 <!-- bug fix from <https://sourceforge.net/p/docbook/bugs/1360/#831b> -->
 
 <xsl:template match="varlistentry/term" mode="xref-to">
12