postgresql/doc/src/sgml/stylesheet-common.xsl

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

128 lines
3.8 KiB
XML
Raw Normal View History

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!--
This file contains XSLT stylesheet customizations that are common to
all output formats (HTML, HTML Help, XSL-FO, etc.).
-->
<xsl:include href="stylesheet-speedup-common.xsl" />
<!-- Parameters -->
<!--
<xsl:param name="draft.mode">
<xsl:choose>
<xsl:when test="contains($pg.version, 'devel')">yes</xsl:when>
<xsl:otherwise>no</xsl:otherwise>
</xsl:choose>
</xsl:param>
-->
<xsl:param name="show.comments">
<xsl:choose>
<xsl:when test="contains($pg.version, 'devel')">1</xsl:when>
<xsl:otherwise>0</xsl:otherwise>
</xsl:choose>
</xsl:param>
<xsl:param name="callout.graphics" select="'0'"></xsl:param>
<xsl:param name="glossentry.show.acronym">yes</xsl:param>
<xsl:param name="toc.section.depth">2</xsl:param>
<xsl:param name="linenumbering.extension" select="'0'"></xsl:param>
<xsl:param name="section.autolabel" select="1"></xsl:param>
<xsl:param name="section.label.includes.component.label" select="1"></xsl:param>
<xsl:param name="refentry.generate.name" select="0"></xsl:param>
<xsl:param name="refentry.generate.title" select="1"></xsl:param>
<xsl:param name="refentry.xref.manvolnum" select="0"/>
<xsl:param name="formal.procedures" select="0"></xsl:param>
<xsl:param name="generate.consistent.ids" select="1"/>
<xsl:param name="punct.honorific" select="''"></xsl:param>
<xsl:param name="variablelist.term.break.after">1</xsl:param>
<xsl:param name="variablelist.term.separator"></xsl:param>
<xsl:param name="xref.with.number.and.title" select="0"></xsl:param>
<!-- Change display of some elements -->
<xsl:template match="productname">
<xsl:call-template name="inline.charseq"/>
</xsl:template>
Doc: introduce new layout for tables of functions and operators. We've long fought with the draconian space limitations of our traditional table layout for describing SQL functions and operators. This commit introduces a new approach, though so far I've only applied it to a few of those tables. The new way makes use of DocBook's support for different layouts in different rows of a table, and allows the descriptions and examples for a function or operator to run to several lines without as much ugliness and wasted space as before. The core layout concept is now Name Signature Description Example Example Result so that a function or operator really has three table rows not one, but we group them to look like one row by having the name column have only one entry for all three rows. (Actually, there could be four or more rows if you wanted to have more than one example, which is another thing that was painful before but works easily now.) This is handled by a "morerows" annotation on the name entry, which isn't perfect (notably, the toolchain is not smart enough to avoid breaking these row groups across PDF pages) but there seems no better solution in DocBook. The name column is normally fairly narrow, allowing plenty of space for the other column(s), and not wasting too much space when one of the other components runs to multiple lines. The varying row layout is managed by defining named "spans" and then tagging entries with a "spanname" of "name", "sig", "desc", "example", or "exresult". This provides a bit of semantic annotation to go with the formatting improvement, which seems like a good thing. (It seems that we have to re-define these spans afresh for each table, which is annoying, but it's not any worse than the duplication involved in the table headers. At least that gives us an opportunity to vary the relative column widths per-table, which is handy since function tables sometimes need much wider name columns than operator tables.) Signature entries should be written in the style <function>fname</function>(<type>typename</type> ...) <returnvalue>typename</returnvalue> The <returnvalue> tag produces a right arrow before the result type name. (I'll document that convention in a user-visible place later.) While this provides significantly more horizontal space than before for examples, it's still true that PDF output is a lot narrower than typical webpage viewing windows, so some examples need to be broken in places where there is no whitespace. I've added &zwsp; markers in suitable places to allow the tables to render warning-free in PDF. I've so far converted only the date/time operator, date/time function, and enum function tables in sections 9.9 and 9.10; these were chosen to provide a reasonable sample of the formatting problems that need to be solved. Assuming that this looks good on the website and doesn't provoke howls of anguish, I'll work on the other similar tables in the near future. There's a moderate amount of new editorial content in this patch along with the raw formatting changes; for instance I had to write text descriptions for operators that lacked them. I failed to resist the temptation to improve some other descriptions and examples, too. Patch by me, with thanks to Alexander Lakhin for assistance with figuring out some formatting issues. Discussion: https://postgr.es/m/9326.1581457869@sss.pgh.pa.us
2020-04-13 00:03:20 +02:00
<!-- Render <returnvalue> with a right arrow then the type name -->
<!-- Avoid adding unnecessary white space in this template! -->
<xsl:template match="returnvalue">&#x2192; <xsl:call-template name="inline.monoseq"/></xsl:template>
Doc: introduce new layout for tables of functions and operators. We've long fought with the draconian space limitations of our traditional table layout for describing SQL functions and operators. This commit introduces a new approach, though so far I've only applied it to a few of those tables. The new way makes use of DocBook's support for different layouts in different rows of a table, and allows the descriptions and examples for a function or operator to run to several lines without as much ugliness and wasted space as before. The core layout concept is now Name Signature Description Example Example Result so that a function or operator really has three table rows not one, but we group them to look like one row by having the name column have only one entry for all three rows. (Actually, there could be four or more rows if you wanted to have more than one example, which is another thing that was painful before but works easily now.) This is handled by a "morerows" annotation on the name entry, which isn't perfect (notably, the toolchain is not smart enough to avoid breaking these row groups across PDF pages) but there seems no better solution in DocBook. The name column is normally fairly narrow, allowing plenty of space for the other column(s), and not wasting too much space when one of the other components runs to multiple lines. The varying row layout is managed by defining named "spans" and then tagging entries with a "spanname" of "name", "sig", "desc", "example", or "exresult". This provides a bit of semantic annotation to go with the formatting improvement, which seems like a good thing. (It seems that we have to re-define these spans afresh for each table, which is annoying, but it's not any worse than the duplication involved in the table headers. At least that gives us an opportunity to vary the relative column widths per-table, which is handy since function tables sometimes need much wider name columns than operator tables.) Signature entries should be written in the style <function>fname</function>(<type>typename</type> ...) <returnvalue>typename</returnvalue> The <returnvalue> tag produces a right arrow before the result type name. (I'll document that convention in a user-visible place later.) While this provides significantly more horizontal space than before for examples, it's still true that PDF output is a lot narrower than typical webpage viewing windows, so some examples need to be broken in places where there is no whitespace. I've added &zwsp; markers in suitable places to allow the tables to render warning-free in PDF. I've so far converted only the date/time operator, date/time function, and enum function tables in sections 9.9 and 9.10; these were chosen to provide a reasonable sample of the formatting problems that need to be solved. Assuming that this looks good on the website and doesn't provoke howls of anguish, I'll work on the other similar tables in the near future. There's a moderate amount of new editorial content in this patch along with the raw formatting changes; for instance I had to write text descriptions for operators that lacked them. I failed to resist the temptation to improve some other descriptions and examples, too. Patch by me, with thanks to Alexander Lakhin for assistance with figuring out some formatting issues. Discussion: https://postgr.es/m/9326.1581457869@sss.pgh.pa.us
2020-04-13 00:03:20 +02:00
<xsl:template match="structfield">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template match="structname">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template match="symbol">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template match="systemitem">
<xsl:call-template name="inline.charseq"/>
</xsl:template>
<xsl:template match="token">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template match="type">
<xsl:call-template name="inline.monoseq"/>
</xsl:template>
<xsl:template match="programlisting/emphasis">
<xsl:call-template name="inline.boldseq"/>
</xsl:template>
<!-- Special support for Tcl synopses -->
<xsl:template match="optional[@role='tcl']">
2016-11-09 18:00:00 +01:00
<xsl:text>?</xsl:text>
<xsl:call-template name="inline.charseq"/>
<xsl:text>?</xsl:text>
</xsl:template>
<!-- Support for generating xref link text to additional elements -->
<xsl:template match="command" mode="xref-to">
<xsl:apply-templates select="." mode="xref"/>
</xsl:template>
<xsl:template match="function" mode="xref-to">
<xsl:apply-templates select="." mode="xref"/>
</xsl:template>
<!--
Support for copying images to the output directory, so the output is self
contained.
-->
<xsl:template name="write-image">
<xsl:variable name="input_filename">
<xsl:value-of select="imagedata/@fileref"/>
</xsl:variable>
<!-- references images directly, without images/ -->
<xsl:variable name="output_filename">
<xsl:value-of select="concat($chunk.base.dir, substring-after($input_filename, '/'))"/>
</xsl:variable>
<xsl:call-template name="write.chunk">
<xsl:with-param name="filename" select="$output_filename"/>
<xsl:with-param name="content" select="document($input_filename)"/>
</xsl:call-template>
</xsl:template>
</xsl:stylesheet>