[PATCH 17/18] doc: improve formatting of client-side documentation
Peter Hutterer
peter.hutterer at who-t.net
Mon Apr 1 17:09:11 PDT 2013
A bunch of changes to the xsl transformation stylesheet to make Chapter 4
(Client API) look nicer and more readable.
Main changes:
- function synopsis listed
- lists for parameters and return values
- long function descriptions
- misc other hooks for "see also", "note", etc
The long description is a sore point. doxygen xml output is difficult to
parse with the output being in the form of
<detailed description>
<para>
<parameterlist> .... </parameterlist>
<simplesect kind="return">... </simplesect>
First paragraph of long description
</para>
<para>
Second paragraph of long <sometag>description</sometag>
</para>
</detaileddescription>
So we need to ignore parameterlist and simplesect, but extract the text from
everything else. Any improvements on that welcome.
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
doc/Wayland/doxygen-to-publican.xsl | 95 +++++++++++++++++++++++++++++++++++--
1 file changed, 92 insertions(+), 3 deletions(-)
diff --git a/doc/Wayland/doxygen-to-publican.xsl b/doc/Wayland/doxygen-to-publican.xsl
index 2e3ec5d..864237c 100644
--- a/doc/Wayland/doxygen-to-publican.xsl
+++ b/doc/Wayland/doxygen-to-publican.xsl
@@ -35,17 +35,106 @@
</section>
</xsl:template>
+<xsl:template match="parameteritem">
+ <varlistentry>
+ <term>
+ <xsl:value-of select="parameternamelist/parametername"/>
+ </term>
+ <listitem>
+ <para>
+ <xsl:value-of select="parameterdescription/para"/>
+ </para>
+ </listitem>
+ </varlistentry>
+</xsl:template>
+
+<xsl:template match="parameterlist">
+ <xsl:if test="parameteritem">
+ <variablelist>
+ <xsl:apply-templates select="parameteritem" />
+ </variablelist>
+ </xsl:if>
+</xsl:template>
+
+<xsl:template match="ref">
+ <emphasis><xsl:value-of select="." /></emphasis>
+</xsl:template>
+
+<xsl:template match="simplesect[@kind='return']">
+ <variablelist>
+ <varlistentry>
+ <term>Returns:</term>
+ <listitem>
+ <para>
+ <xsl:value-of select="." />
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+</xsl:template>
+
+<xsl:template match="simplesect[@kind='see']">
+ <itemizedlist>
+ <listitem>
+ <para>
+ See also:
+ <xsl:for-each select="para/ref">
+ <emphasis><xsl:value-of select="."/><xsl:text> </xsl:text></emphasis>
+ </xsl:for-each>
+ </para>
+ </listitem>
+ </itemizedlist>
+</xsl:template>
+
+<xsl:template match="simplesect[@kind='since']">
+ <itemizedlist>
+ <listitem>
+ <para>
+ Since: <xsl:value-of select="para"/>
+ </para>
+ </listitem>
+ </itemizedlist>
+</xsl:template>
+
+<xsl:template match="simplesect[@kind='note']">
+ <emphasis>Note: <xsl:value-of select="."/></emphasis>
+</xsl:template>
+
+<xsl:template match="programlisting">
+ <programlisting><xsl:value-of select="."/></programlisting>
+</xsl:template>
+
+<!-- this opens a para for each detaileddescription/para. I could not find a
+ way to extract the right text for the description from the
+ source otherwise. Downside: we can't use para for return value, "see
+ also", etc. because they're already inside a para. So they're lists.
+
+ It also means we don't control the order of when something is added to
+ the output, it matches the input file
+ -->
+<xsl:template match="detaileddescription/para">
+ <para><xsl:apply-templates /></para>
+</xsl:template>
+
+<xsl:template match="detaileddescription">
+ <xsl:apply-templates select="para" />
+</xsl:template>
<!-- methods -->
<xsl:template match="memberdef" >
- <xsl:if test="@kind = 'function' and @static = 'no'">
+ <xsl:if test="@kind = 'function' and @static = 'no'">
<varlistentry>
<term>
- <xsl:value-of select="name" />
+ <xsl:value-of select="name"/>
- <xsl:value-of select="briefdescription" />
</term>
<listitem>
- <para></para>
+ <para>
+ <synopsis>
+ <xsl:value-of select="definition"/><xsl:value-of select="argsstring"/>
+ </synopsis>
+ </para>
+ <xsl:apply-templates select="detaileddescription" />
</listitem>
</varlistentry>
</xsl:if>
--
1.8.1.4
More information about the wayland-devel
mailing list