[PATCH 17/18] doc: improve formatting of client-side documentation

[Kristian Høgsberg]

On Tue, Apr 02, 2013 at 10:09:11AM +1000, Peter Hutterer wrote:
> 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.

Let's go with this for now, but there's always the option to parse the
protocol xml directly instead of passing it through doxygen.

Kristian

> 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
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel