mirror of
https://github.com/boostorg/boostbook.git
synced 2025-05-09 15:03:57 +00:00
improve layout for Doxygen-generated function documentation
[SVN r33445]
This commit is contained in:
Eric Niebler
parent
4cb3de9a91
commit
0f83dbdf6f
165
xsl/function.xsl
165
xsl/function.xsl
@ -10,10 +10,6 @@
|
||||
description. -->
|
||||
<xsl:param name="boost.compact.function">1</xsl:param>
|
||||
|
||||
<!-- BoostBook documentation mode. Can be "compact" or
|
||||
"standardese", for now -->
|
||||
<xsl:param name="boost.generation.mode">compact</xsl:param>
|
||||
|
||||
<!-- The longest type length that is considered "short" for the
|
||||
layout of function return types. When the length of the result type
|
||||
and any storage specifiers is greater than this length, they will be
|
||||
@ -709,29 +705,6 @@
|
||||
<!-- Templates for functions -->
|
||||
<xsl:template name="function.documentation">
|
||||
<xsl:param name="text"/>
|
||||
|
||||
<xsl:choose>
|
||||
<xsl:when test="$boost.generation.mode='compact'">
|
||||
<xsl:call-template name="function.documentation.compact">
|
||||
<xsl:with-param name="text" select="$text"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:when test="$boost.generation.mode='standardese'">
|
||||
<xsl:call-template name="function.documentation.standardese">
|
||||
<xsl:with-param name="text" select="$text"/>
|
||||
</xsl:call-template>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:text>Error: invalid value '</xsl:text>
|
||||
<xsl:value-of select="$boost.generation.mode"/>
|
||||
<xsl:text>' for stylesheet parameter boost.generation.mode.</xsl:text>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template name="function.documentation.compact">
|
||||
<xsl:param name="text"/>
|
||||
|
||||
<xsl:choose>
|
||||
<xsl:when test="count(ancestor::free-function-group) > 0
|
||||
or count(ancestor::method-group) > 0
|
||||
@ -746,21 +719,6 @@
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template name="function.documentation.standardese">
|
||||
<xsl:param name="text"/>
|
||||
<!--
|
||||
<formalpara>
|
||||
<title>
|
||||
<xsl:call-template name="fully-qualified-name">
|
||||
<xsl:with-param name="node" select="."/>
|
||||
</xsl:call-template>
|
||||
</title>
|
||||
<xsl:copy-of select="$text"/>
|
||||
</formalpara>
|
||||
-->
|
||||
<listitem><xsl:copy-of select="$text"/></listitem>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Semantic descriptions of functions -->
|
||||
<xsl:template name="function-requirements">
|
||||
<xsl:param name="namespace-reference" select="false()"/>
|
||||
@ -771,10 +729,23 @@
|
||||
|
||||
<xsl:apply-templates select="description/*"/>
|
||||
|
||||
<xsl:if test="parameter/description|signature/parameter/description|
|
||||
requires|effects|postconditions|returns|throws|complexity|
|
||||
notes|rationale">
|
||||
<variablelist spacing="compact">
|
||||
<xsl:processing-instruction name="dbhtml">
|
||||
list-presentation="table"
|
||||
</xsl:processing-instruction>
|
||||
|
||||
<!-- Document parameters -->
|
||||
<xsl:if test="parameter/description|signature/parameter/description">
|
||||
<varlistentry>
|
||||
<term>Parameters:</term>
|
||||
<listitem>
|
||||
<variablelist spacing="compact">
|
||||
<title>Parameters</title>
|
||||
<xsl:processing-instruction name="dbhtml">
|
||||
list-presentation="table"
|
||||
</xsl:processing-instruction>
|
||||
<xsl:for-each select="parameter|signature/parameter">
|
||||
<xsl:sort select="attribute::name"/>
|
||||
<xsl:if test="description">
|
||||
@ -787,6 +758,22 @@
|
||||
</xsl:if>
|
||||
</xsl:for-each>
|
||||
</variablelist>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:if>
|
||||
|
||||
<!-- Document rest of function's contract -->
|
||||
<xsl:for-each select="requires|effects|postconditions|returns|throws|complexity|
|
||||
notes|rationale">
|
||||
<varlistentry>
|
||||
<term><xsl:call-template name="function.requirement.name"/>:</term>
|
||||
<listitem>
|
||||
<xsl:apply-templates select="./*|./text()" mode="annotation"/>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:for-each>
|
||||
|
||||
</variablelist>
|
||||
</xsl:if>
|
||||
|
||||
<xsl:if test="para">
|
||||
@ -798,22 +785,6 @@
|
||||
<xsl:apply-templates select="para"/>
|
||||
</xsl:if>
|
||||
|
||||
<xsl:if test="requires|effects|postconditions|returns|throws|complexity|
|
||||
notes|rationale">
|
||||
<xsl:choose>
|
||||
<xsl:when test="$boost.generation.mode='compact'">
|
||||
<xsl:call-template name="function.requirements.compact"/>
|
||||
</xsl:when>
|
||||
<xsl:when test="$boost.generation.mode='standardese'">
|
||||
<xsl:call-template name="function.requirements.standardese"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:text>Error: invalid value '</xsl:text>
|
||||
<xsl:value-of select="$boost.generation.mode"/>
|
||||
<xsl:text>' for stylesheet parameter boost.generation.mode.</xsl:text>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:if>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template name="function.requirement.name">
|
||||
@ -839,82 +810,6 @@
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- The "compact" function requirements mode uses variable lists -->
|
||||
<xsl:template name="function.requirements.compact">
|
||||
<variablelist spacing="boost">
|
||||
<xsl:apply-templates
|
||||
select="requires|effects|postconditions|returns|throws|complexity|
|
||||
notes|rationale"
|
||||
mode="function.requirements.compact"/>
|
||||
</variablelist>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="*" mode="function.requirements.compact">
|
||||
<varlistentry>
|
||||
<term><xsl:call-template name="function.requirement.name"/></term>
|
||||
<listitem>
|
||||
<xsl:apply-templates select="./*|./text()" mode="annotation"/>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</xsl:template>
|
||||
|
||||
<!-- The "standardese" function requirements mode uses ordered lists -->
|
||||
<xsl:template name="function.requirements.standardese">
|
||||
<orderedlist spacing="compact" numeration="arabic">
|
||||
<xsl:apply-templates
|
||||
select="requires|effects|postconditions|returns|throws|complexity|
|
||||
notes|rationale"
|
||||
mode="function.requirements.standardese"/>
|
||||
</orderedlist>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="*" mode="function.requirements.standardese">
|
||||
<listitem>
|
||||
<xsl:apply-templates select="./*|./text()"
|
||||
mode="function.requirements.injection">
|
||||
<xsl:with-param name="requirement">
|
||||
<xsl:call-template name="function.requirement.name"/>
|
||||
</xsl:with-param>
|
||||
</xsl:apply-templates>
|
||||
</listitem>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Handle paragraphs in function requirement clauses -->
|
||||
<xsl:template match="para|simpara" mode="function.requirements.injection">
|
||||
<xsl:param name="requirement"/>
|
||||
|
||||
<xsl:element name="{local-name(.)}">
|
||||
<xsl:for-each select="./@*">
|
||||
<xsl:attribute name="{name(.)}">
|
||||
<xsl:value-of select="."/>
|
||||
</xsl:attribute>
|
||||
</xsl:for-each>
|
||||
|
||||
<xsl:if test="position()=1">
|
||||
<emphasis role="bold">
|
||||
<xsl:copy-of select="$requirement"/>
|
||||
<xsl:text>: </xsl:text>
|
||||
</emphasis>
|
||||
</xsl:if>
|
||||
<xsl:apply-templates/>
|
||||
</xsl:element>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="text()" mode="function.requirements.injection">
|
||||
<xsl:param name="requirement"/>
|
||||
|
||||
<simpara>
|
||||
<xsl:if test="position()=1">
|
||||
<emphasis role="bold">
|
||||
<xsl:copy-of select="$requirement"/>
|
||||
<xsl:text>: </xsl:text>
|
||||
</emphasis>
|
||||
</xsl:if>
|
||||
<xsl:copy-of select="."/>
|
||||
<xsl:apply-templates/>
|
||||
</simpara>
|
||||
</xsl:template>
|
||||
|
||||
<!-- Function reference -->
|
||||
<xsl:template match="function|method" mode="reference">
|
||||
<!-- True if we should compact this function -->
|
||||
|
||||
@ -12,33 +12,3 @@
|
||||
<xsl:param name="refentry.generate.title" select="1"/>
|
||||
<xsl:param name="make.year.ranges" select="1"/>
|
||||
|
||||
<xsl:template match="variablelist">
|
||||
<xsl:choose>
|
||||
<xsl:when test="@spacing='boost'">
|
||||
<p><xsl:apply-templates mode="boost.variablelist"/></p>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:apply-imports />
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="varlistentry" mode="boost.variablelist">
|
||||
<xsl:if test="position() > 1">
|
||||
<br/>
|
||||
</xsl:if>
|
||||
<b><xsl:apply-templates select="term"/></b>:
|
||||
|
||||
<xsl:choose>
|
||||
<xsl:when test="local-name(listitem/*[1])='simpara' or
|
||||
local-name(listitem/*[1])='para'">
|
||||
<xsl:apply-templates
|
||||
select="listitem/*[1]/*|listitem/*[1]/text()"/>
|
||||
<xsl:apply-templates select="(listitem/*|listitem/text())[position() > 1]"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:apply-templates select="listitem/*|listitem/text()"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
</xsl:stylesheet>
|
||||
|
||||
30
xsl/html.xsl
30
xsl/html.xsl
@ -153,36 +153,6 @@ set toc,title
|
||||
</table>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="variablelist">
|
||||
<xsl:choose>
|
||||
<xsl:when test="@spacing='boost'">
|
||||
<p><xsl:apply-templates mode="boost.variablelist"/></p>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:apply-imports />
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<xsl:template match="varlistentry" mode="boost.variablelist">
|
||||
<xsl:if test="position() > 1">
|
||||
<br/>
|
||||
</xsl:if>
|
||||
<b><xsl:apply-templates select="term"/></b>:
|
||||
|
||||
<xsl:choose>
|
||||
<xsl:when test="local-name(listitem/*[1])='simpara' or
|
||||
local-name(listitem/*[1])='para'">
|
||||
<xsl:apply-templates
|
||||
select="listitem/*[1]/*|listitem/*[1]/text()"/>
|
||||
<xsl:apply-templates select="(listitem/*|listitem/text())[position() > 1]"/>
|
||||
</xsl:when>
|
||||
<xsl:otherwise>
|
||||
<xsl:apply-templates select="listitem/*|listitem/text()"/>
|
||||
</xsl:otherwise>
|
||||
</xsl:choose>
|
||||
</xsl:template>
|
||||
|
||||
<!-- We don't want refentry's to show up in the TOC because they
|
||||
will merely be redundant with the synopsis. -->
|
||||
<xsl:template match="refentry" mode="toc"/>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user