mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Doc: re-re-revise markup for tables of functions.

Browse Source 
Make the markup a bit less ad-hoc.  A function-table cell now contains
several <para> units, and we label the ones that contain function
signatures with role="func_signature".  The CSS or FO stylesheets then
key off of that to decide how to set the indentation.  A very useful
win from this approach is that we can have more than one signature
entry per table cell, simplifying the documentation of closely-related
operators and functions.

This patch mostly just replaces the markup in the tables I converted so
far.  But I did alter a couple of places where multiple signatures were
helpful.

Discussion: https://postgr.es/m/5561.1587922854@sss.pgh.pa.us
This commit is contained in:
Tom Lane 2020-04-30 00:34:05 -04:00
parent ab2343d4cb
commit 4ad047a6ea
4 changed files with 2962 additions and 1827 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4730
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

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

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

@ -63,30 +63,14 @@
</fo:inline> </fo:inline>
</xsl:template> </xsl:template>
<!-- overrides built-in DocBook template --> <!-- formatting for entries in tables of functions -->
<xsl:template name="table.cell.block.properties"> <xsl:template match="entry[@role='func_table_entry']/para">
<!-- highlight this entry? --> <fo:block margin-left="4em" text-align="left">
<xsl:choose> <xsl:if test="self::para[@role='func_signature']">
<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">4em</xsl:attribute>
<xsl:attribute name="text-indent">-3.5em</xsl:attribute> <xsl:attribute name="text-indent">-3.5em</xsl:attribute>
<xsl:attribute name="text-align">left</xsl:attribute> </xsl:if>
</xsl:when> <xsl:apply-templates/>
</xsl:choose> </fo:block>
</xsl:template> </xsl:template>
<!-- overrides stylesheet-common.xsl --> <!-- overrides stylesheet-common.xsl -->
@ -96,11 +80,6 @@
<xsl:call-template name="inline.monoseq"/> <xsl:call-template name="inline.monoseq"/>
</xsl:template> </xsl:template>
<!-- overrides stylesheet-common.xsl -->
<xsl:template match="processing-instruction('br')">
<fo:block/>
</xsl:template>
<!-- FOP needs us to be explicit about use of symbol font in some cases --> <!-- FOP needs us to be explicit about use of symbol font in some cases -->
<xsl:template match="phrase[@role='symbol_font']"> <xsl:template match="phrase[@role='symbol_font']">
<fo:inline font-family="{$symbol.font.family}"><xsl:value-of select="."/></fo:inline> <fo:inline font-family="{$symbol.font.family}"><xsl:value-of select="."/></fo:inline>

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

@ -78,13 +78,24 @@ div.example {
/* formatting for entries in tables of functions: indent all but first line */ /* formatting for entries in tables of functions: indent all but first line */
th.functableentry, th.func_table_entry p,
td.functableentry { td.func_table_entry p {
margin-top: 0.1em;
margin-bottom: 0.1em;
padding-left: 4em; padding-left: 4em;
text-indent: -3.5em;
text-align: left; text-align: left;
} }
p.func_signature {
text-indent: -3.5em;
}
td.func_table_entry pre.programlisting {
margin-top: 0.1em;
margin-bottom: 0.1em;
padding-left: 4em;
}
/* Put these here instead of inside the HTML (see unsetting of /* 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 admon.style in XSL) so that the web site stylesheet can set its own
style. */ style. */