boost_mirror/boostbook
1
0
Fork 0
mirror of https://github.com/boostorg/boostbook.git synced 2025-05-09 23:13:58 +00:00
Code Issues Packages Projects Releases Wiki Activity

improve layout for Doxygen-generated function documentation

Browse Source 
[SVN r33445]
This commit is contained in:
Eric Niebler 2006-03-22 18:46:39 +00:00
parent 4cb3de9a91
commit 0f83dbdf6f
3 changed files with 42 additions and 207 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
xsl/function.xsl
View File

@ -10,10 +10,6 @@
description. --> description. -->
<xsl:param name="boost.compact.function">1</xsl:param> <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 <!-- The longest type length that is considered "short" for the
layout of function return types. When the length of the result type layout of function return types. When the length of the result type
and any storage specifiers is greater than this length, they will be and any storage specifiers is greater than this length, they will be
@ -709,29 +705,6 @@
<!-- Templates for functions --> <!-- Templates for functions -->
<xsl:template name="function.documentation"> <xsl:template name="function.documentation">
<xsl:param name="text"/> <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:choose>
<xsl:when test="count(ancestor::free-function-group) &gt; 0 <xsl:when test="count(ancestor::free-function-group) &gt; 0
or count(ancestor::method-group) &gt; 0 or count(ancestor::method-group) &gt; 0
@ -746,21 +719,6 @@
</xsl:choose> </xsl:choose>
</xsl:template> </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 --> <!-- Semantic descriptions of functions -->
<xsl:template name="function-requirements"> <xsl:template name="function-requirements">
<xsl:param name="namespace-reference" select="false()"/> <xsl:param name="namespace-reference" select="false()"/>
@ -771,21 +729,50 @@
<xsl:apply-templates select="description/*"/> <xsl:apply-templates select="description/*"/>
<!-- Document parameters --> <xsl:if test="parameter/description|signature/parameter/description|
<xsl:if test="parameter/description|signature/parameter/description"> requires|effects|postconditions|returns|throws|complexity|
notes|rationale">
<variablelist spacing="compact"> <variablelist spacing="compact">
<title>Parameters</title> <xsl:processing-instruction name="dbhtml">
<xsl:for-each select="parameter|signature/parameter"> list-presentation="table"
<xsl:sort select="attribute::name"/> </xsl:processing-instruction>
<xsl:if test="description">
<varlistentry> <!-- Document parameters -->
<term><xsl:value-of select="@name"/></term> <xsl:if test="parameter/description|signature/parameter/description">
<listitem> <varlistentry>
<xsl:apply-templates select="description/*"/> <term>Parameters:</term>
</listitem> <listitem>
</varlistentry> <variablelist spacing="compact">
</xsl:if> <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">
<varlistentry>
<term><xsl:value-of select="@name"/></term>
<listitem>
<xsl:apply-templates select="description/*"/>
</listitem>
</varlistentry>
</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> </xsl:for-each>
</variablelist> </variablelist>
</xsl:if> </xsl:if>
@ -798,22 +785,6 @@
<xsl:apply-templates select="para"/> <xsl:apply-templates select="para"/>
</xsl:if> </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>
<xsl:template name="function.requirement.name"> <xsl:template name="function.requirement.name">
@ -839,82 +810,6 @@
</xsl:choose> </xsl:choose>
</xsl:template> </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>:&#160;</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>:&#160;</xsl:text>
</emphasis>
</xsl:if>
<xsl:copy-of select="."/>
<xsl:apply-templates/>
</simpara>
</xsl:template>
<!-- Function reference --> <!-- Function reference -->
<xsl:template match="function|method" mode="reference"> <xsl:template match="function|method" mode="reference">
<!-- True if we should compact this function --> <!-- True if we should compact this function -->

30
xsl/html-single.xsl
View File

@ -12,33 +12,3 @@
<xsl:param name="refentry.generate.title" select="1"/> <xsl:param name="refentry.generate.title" select="1"/>
<xsl:param name="make.year.ranges" 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() &gt; 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() &gt; 1]"/>
</xsl:when>
<xsl:otherwise>
<xsl:apply-templates select="listitem/*|listitem/text()"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>

30
xsl/html.xsl
View File

@ -153,36 +153,6 @@ set toc,title
</table> </table>
</xsl:template> </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() &gt; 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() &gt; 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 <!-- We don't want refentry's to show up in the TOC because they
will merely be redundant with the synopsis. --> will merely be redundant with the synopsis. -->
<xsl:template match="refentry" mode="toc"/> <xsl:template match="refentry" mode="toc"/>