Re: Poll: are people okay with function/operator table redesign? - Mailing list pgsql-hackers

I wrote:
> Alvaro Herrera <alvherre@2ndquadrant.com> writes:
>> If we're doing nicer markup+CSS for this, then it might make sense to
>> find a better solution for this kind of entry with multiple signatures
>> (which was already an issue in the previous version):

> Yeah, agreed.  I would like to be able to have multiple signature blocks
> in one table cell, which the current hack can't handle.  There aren't
> quite enough cases to make this mandatory, but it would be nicer.
> It seems do-able if we explicitly mark signature blocks with their
> own role, say ...

Hearing no comments, I went ahead and experimented with that.
Attached is a POC patch that changes just the header and first few
entries in table 9.9, just to see what it'd look like.  This does
nicely reproduce the existing visual appearance.  (With the margin
parameters I used, there is a teensy bit more vertical space, but
I think it looks better this way.  That could be adjusted either
way of course.)

There is a small problem with getting this to work in the webstyle
HTML: somebody decided it would be a great idea to have a global
override on paragraph margin-bottom settings.  For the purposes of
this test I just deleted that from main.css, but I suppose we want
some more-nuanced solution in reality.

<digression>

One thing I couldn't help noticing while fooling with this is what
seems to be a bug in the PDF toolchain: any place you try to put
an <indexterm>, you get extra whitespace.  Not a lot, but once you
see it, you can't un-see it.  It's particularly obvious if one of
two adjacent lines has the extra indentation and the other doesn't.
In the attached, I added an <indexterm> to one of the signature
entries for "text || anynonarray", and you can see what I'm unhappy
about in the PDF screenshot.  The problem already exists in our
previous markup, at least in places where people put indexterms
inside function-table entries, but it'll be more obvious anyplace
we choose to have two signature entries in one table cell.

I tried putting the <indexterm>s outside the <para> elements, but
that makes it worse not better: instead of a little bit of extra
horizontal whitespace, you get a lot of extra vertical whitespace.

The only "fix" I've found is to place the <indexterm> at the end
of the signature <para> instead of the beginning.  That's not included
in the attached but it does hide the existence of the extra space
quite effectively.  I'm not sure though whether it might result in
odd behavior of cross-reference links to the function entry.
In any case it feels like a hack.

</digression>

It seems to me that this way is better than the markup I've been
using --- one thing I've observed is that Emacs' sgml mode is a
bit confused by the <?br?> hacks, and it's happier with this.
But it's not clear to me whether this is sufficient to resolve
Peter's unhappiness.

            regards, tom lane

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b0afaeb..ffcb0ae 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -2067,48 +2067,64 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
     <tgroup cols="1">
      <thead>
       <row>
-       <entry role="functableentry">
-        Function/Operator<?br?>Description<?br?>Example(s)
-       </entry>
+       <entry role="func_table_entry"><para role="func_signature">
+        Function/Operator
+       </para>
+       <para>
+        Description
+       </para>
+       <para>
+        Example(s)
+       </para></entry>
       </row>
      </thead>

      <tbody>
       <row>
-       <entry role="functableentry">
+       <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
          <primary>character string</primary>
          <secondary>concatenation</secondary>
         </indexterm>
         <type>text</type> <literal>||</literal> <type>text</type>
         <returnvalue>text</returnvalue>
-       <?br?>
+       </para>
+       <para>
         Concatenates the two strings.
-       <?br?>
+       </para>
+       <para>
         <literal>'Post' || 'greSQL'</literal>
         <returnvalue>PostgreSQL</returnvalue>
-       </entry>
+       </para></entry>
       </row>

       <row>
-       <entry role="functableentry">
+       <entry role="func_table_entry"><para role="func_signature">
+<indexterm>
+         <primary>character string test</primary>
+</indexterm>
         <type>text</type> <literal>||</literal> <type>anynonarray</type>
-        or <type>anynonarray</type> <literal>||</literal> <type>text</type>
         <returnvalue>text</returnvalue>
-       <?br?>
+       </para>
+       <para role="func_signature">
+        <type>anynonarray</type> <literal>||</literal> <type>text</type>
+        <returnvalue>text</returnvalue>
+       </para>
+       <para>
         Converts the non-string input to text, then concatenates the two
         strings.  (The non-string input cannot be of an array type, because
         that would create ambiguity with the array <literal>||</literal>
         operators.  If you want to concatenate an array's text equivalent,
         cast it to <type>text</type> explicitly.)
-       <?br?>
+       </para>
+       <para>
         <literal>'Value: ' || 42</literal>
         <returnvalue>Value: 42</returnvalue>
-       </entry>
+       </para></entry>
       </row>

       <row>
-       <entry role="functableentry">
+       <entry role="func_table_entry"><para role="func_signature">
         <indexterm>
          <primary>normalized</primary>
         </indexterm>
@@ -2117,7 +2133,8 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         </indexterm>
          <type>text</type> <literal>IS</literal> <optional><literal>NOT</literal></optional>
<optional><parameter>form</parameter></optional><literal>NORMALIZED</literal> 
         <returnvalue>boolean</returnvalue>
-       <?br?>
+       </para>
+       <para>
         Checks whether the string is in the specified Unicode normalization
         form.  The optional <parameter>form</parameter> key word specifies the
         form: <literal>NFC</literal> (the default), <literal>NFD</literal>,
@@ -2125,10 +2142,11 @@ repeat('Pg', 4) <returnvalue>PgPgPgPg</returnvalue>
         only be used when the server encoding is <literal>UTF8</literal>.  Note
         that checking for normalization using this expression is often faster
         than normalizing possibly already normalized strings.
-       <?br?>
+       </para>
+       <para>
         <literal>U&'\0061\0308bc' IS NFD NORMALIZED</literal>
         <returnvalue>t</returnvalue>
-       </entry>
+       </para></entry>
       </row>

       <row>
diff --git a/doc/src/sgml/stylesheet-fo.xsl b/doc/src/sgml/stylesheet-fo.xsl
index 6797e06..e923b00 100644
--- a/doc/src/sgml/stylesheet-fo.xsl
+++ b/doc/src/sgml/stylesheet-fo.xsl
@@ -89,6 +89,16 @@
   </xsl:choose>
 </xsl:template>

+<!-- formatting for entries in tables of functions -->
+<xsl:template match="entry[@role='func_table_entry']/para">
+  <fo:block margin-left="4em" text-align="left">
+    <xsl:if test="self::para[@role='func_signature']">
+      <xsl:attribute name="text-indent">-3.5em</xsl:attribute>
+    </xsl:if>
+    <xsl:apply-templates/>
+  </fo:block>
+</xsl:template>
+
 <!-- overrides stylesheet-common.xsl -->
 <!-- FOP needs us to be explicit about the font to use for right arrow -->
 <xsl:template match="returnvalue">
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index f369e12..d28cec4 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -85,6 +85,18 @@ td.functableentry {
     text-align: left;
 }

+th.func_table_entry p,
+td.func_table_entry p {
+    margin-top: 0.1em;
+    margin-bottom: 0.1em;
+    padding-left: 4em;
+    text-align: left;
+}
+
+p.func_signature {
+    text-indent: -3.5em;
+}
+
 /* Put these here instead of inside the HTML (see unsetting of
    admon.style in XSL) so that the web site stylesheet can set its own
    style. */
--- main.css~    2020-04-26 12:45:29.646286775 -0400
+++ main.css    2020-04-26 12:54:04.605046657 -0400
@@ -624,9 +624,11 @@
   margin-top: 1rem;
 }
 
+/*
 #docContent p {
   margin-bottom: 1rem !important;
 }
+*/
 
 #docContent hr {
   margin: 0 0 0.5em 0;
@@ -799,6 +801,18 @@
     text-align: left;
 }
 
+#docContent table.table th.func_table_entry p,
+#docContent table.table td.func_table_entry p {
+    margin-top: 0.1em;
+    margin-bottom: 0.1em;
+    padding-left: 4em;
+    text-align: left;
+}
+
+#docContent table.table p.func_signature {
+    text-indent: -3.5em;
+}
+
 /**
  * Titles, Navigation
  */