1berry/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Doc: revise formatting of function/operator tables.

Browse Source 
The table layout ideas proposed in commit e894c6183 were not as widely
popular as I'd hoped.  After discussion, we've settled on a layout
that's effectively a single-column table with cell contents much like a
<varlistentry> description of the function or operator; though we're not
actually using <varlistentry>, because it'd add way too much vertical
space.  Instead the effect is accomplished using line-break processing
instructions to separate the description and example(s), plus CSS or FO
customizations to produce indentation of all but the first line in each
cell.  While technically this is a bit grotty, it does have the
advantage that we won't need to write nearly as much boilerplate markup.

This patch updates tables 9.30, 9.31, and 9.33 (which were touched by
the previous patch) to the revised style, and additionally converts
table 9.10.  A lot of work still remains to do, but hopefully it won't
be too controversial.

Thanks to Andrew Dunstan, Pierre Giraud, Robert Haas, Alvaro Herrera,
David Johnston, Jonathan Katz, Isaac Morland for valuable ideas.

Discussion: https://postgr.es/m/8691.1586798003@sss.pgh.pa.us
This commit is contained in:
Tom Lane 2020-04-17 20:50:26 -04:00
parent 6741cfa596
commit 737d69ffc3
4 changed files with 933 additions and 1037 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1918
doc/src/sgml/func.sgml
View File

File diff suppressed because it is too large Load Diff

7
doc/src/sgml/stylesheet-common.xsl
View File

@ -103,4 +103,11 @@
<xsl:apply-templates select="." mode="xref"/>
</xsl:template>
<!-- Support for explicit line breaks <?br?> within table cells -->
<xsl:template match="processing-instruction('br')">
<br/>
</xsl:template>
</xsl:stylesheet>

31
doc/src/sgml/stylesheet-fo.xsl
View File

@ -63,6 +63,32 @@
</fo:inline>
</xsl:template>
<!-- overrides built-in DocBook template -->
<xsl:template name="table.cell.block.properties">
<!-- highlight this entry? -->
<xsl:choose>
<xsl:when test="ancestor::thead or ancestor::tfoot">
<xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:when>
<!-- Make row headers bold too -->
<xsl:when test="ancestor::tbody and
(ancestor::table[@rowheader = 'firstcol'] or
ancestor::informaltable[@rowheader = 'firstcol']) and
ancestor-or-self::entry[1][count(preceding-sibling::entry) = 0]">
<xsl:attribute name="font-weight">bold</xsl:attribute>
</xsl:when>
</xsl:choose>
<!-- Postgres additions start here -->
<!-- indent all but first line of entries in tables of functions -->
<xsl:choose>
<xsl:when test="self::entry[@role='functableentry']">
<xsl:attribute name="margin-left">5em</xsl:attribute>
<xsl:attribute name="text-indent">-5em</xsl:attribute>
<xsl:attribute name="text-align">left</xsl:attribute>
</xsl:when>
</xsl:choose>
</xsl:template>
<!-- overrides stylesheet-common.xsl -->
<!-- FOP needs us to be explicit about the font to use for right arrow -->
<xsl:template match="returnvalue">
@ -70,6 +96,11 @@
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<!-- overrides stylesheet-common.xsl -->
<xsl:template match="processing-instruction('br')">
<fo:block/>
</xsl:template>
<!-- bug fix from <https://sourceforge.net/p/docbook/bugs/1360/#831b> -->
<xsl:template match="varlistentry/term" mode="xref-to">

14
doc/src/sgml/stylesheet.css
View File

@ -76,6 +76,20 @@ div.example {
margin: 0.5ex;
}
/* formatting for entries in tables of functions: indent all but first line */
th.functableentry {
padding-left: 5em;
text-indent: -5em;
text-align: left;
}
td.functableentry {
padding-left: 5em;
text-indent: -5em;
text-align: left;
}
/* 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. */