doc: improve formatting of client-side documentation

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@who-t.net>

diff --git a/doc/Wayland/doxygen-to-publican.xsl b/doc/Wayland/doxygen-to-publican.xsl
index 2e3ec5d..864237c 100644 (file)
--- 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>