[PATCH] doc: Reduce the validation errors of the docbook input
Bryce Harrington
bryce at osg.samsung.com
Wed Dec 10 16:53:01 PST 2014
On Tue, Dec 09, 2014 at 07:33:51PM -0800, Bill Spitzak wrote:
> This removes all the validation errors except for missing link
> targets. You can test this by removing the --skip-validation
> from doc/publican/Makefile.am.
>
> Main changes are to add <simpara> to lists, remove some extra
> <para> commands, and prefix all the id's so that collisions
> between libclient and libserver are avoided.
I had to look up what a <simpara> was. Still not entirely certain what
the point of it vs. <para>, but if it gets rid of validation errors, +1
to that. I suppose it must solve some layout issues.
Sounds like places where we are using <para> for regular text we should
rather be using <simpara>.
> The remaining errors are due to missing links, due to it not
> copying doxygen's output for struct, union, and a macro. Turning
> on HIDE_UNDOC in wayland.doxygen.in fixes a lot of these but
> not all of them.
>
> PS: it would be useful if somebody who actually knows something
> about xslt would come up with a way to translate a block of text
> makde of <para> commands unchanged, but add <para> around plain
> text. Most of the difficulty is that doxygen's output is rather
> inconsistent here.
Jon Cruz, are you listening? ;-)
Anyway, the changes all look good to me.
Reviewed-by: Bryce Harrington <bryce at osg.samsung.com>
> ---
> doc/publican/doxygen-to-publican.xsl | 44 +++++++++--------------
> doc/publican/protocol-interfaces-to-docbook.xsl | 8 +++--
> doc/publican/protocol-to-docbook.xsl | 10 +++---
> 3 files changed, 27 insertions(+), 35 deletions(-)
>
> diff --git a/doc/publican/doxygen-to-publican.xsl b/doc/publican/doxygen-to-publican.xsl
> index 47bdc5a..5adbfa6 100644
> --- a/doc/publican/doxygen-to-publican.xsl
> +++ b/doc/publican/doxygen-to-publican.xsl
> @@ -37,20 +37,16 @@
> </para>
>
> <xsl:if test="/doxygen/compounddef[@kind='class']">
> - <para>
> - <variablelist>
> - <xsl:apply-templates select="/doxygen/compounddef" />
> - </variablelist>
> - </para>
> + <variablelist>
> + <xsl:apply-templates select="/doxygen/compounddef" />
> + </variablelist>
> </xsl:if>
>
> <para>Methods for the respective classes.</para>
>
> - <para>
> <variablelist>
> - <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
> + <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
> </variablelist>
> - </para>
> </appendix>
> </xsl:template>
>
> @@ -60,7 +56,7 @@
> <xsl:apply-templates select="parameternamelist/parametername"/>
> </term>
> <listitem>
> - <xsl:apply-templates select="parameterdescription"/>
> + <simpara><xsl:apply-templates select="parameterdescription"/></simpara>
> </listitem>
> </varlistentry>
> </xsl:template>
> @@ -74,7 +70,7 @@
> </xsl:template>
>
> <xsl:template match="ref">
> - <link linkend="{@refid}"><xsl:value-of select="." /></link>
> + <link linkend="{$which}{@refid}"><xsl:value-of select="." /></link>
> </xsl:template>
>
> <xsl:template match="simplesect[@kind='return']">
> @@ -82,22 +78,18 @@
> <varlistentry>
> <term>Returns:</term>
> <listitem>
> - <xsl:apply-templates />
> + <simpara><xsl:apply-templates /></simpara>
> </listitem>
> </varlistentry>
> </variablelist>
> </xsl:template>
>
> <xsl:template match="simplesect[@kind='see']">
> - <para>
> - See also: <xsl:apply-templates />
> - </para>
> + See also: <xsl:apply-templates />
> </xsl:template>
>
> <xsl:template match="simplesect[@kind='since']">
> - <para>
> - Since: <xsl:apply-templates />
> - </para>
> + Since: <xsl:apply-templates />
> </xsl:template>
>
> <xsl:template match="simplesect[@kind='note']">
> @@ -131,7 +123,7 @@
> <!-- methods -->
> <xsl:template match="memberdef" >
> <xsl:if test="@kind = 'function' and @static = 'no'">
> - <varlistentry id="{@id}">
> + <varlistentry id="{$which}{@id}">
> <term>
> <xsl:value-of select="name"/>
> <xsl:if test="normalize-space(briefdescription) != ''">
> @@ -139,21 +131,19 @@
> </xsl:if>
> </term>
> <listitem>
> - <para>
> - <synopsis>
> - <xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/>
> - </synopsis>
> - </para>
> + <synopsis>
> + <xsl:apply-templates select="definition"/><xsl:apply-templates select="argsstring"/>
> + </synopsis>
> <xsl:apply-templates select="detaileddescription" />
> </listitem>
> </varlistentry>
> - </xsl:if>
> + </xsl:if>
> </xsl:template>
>
> <!-- classes -->
> <xsl:template match="compounddef" >
> - <xsl:if test="@kind = 'class'">
> - <varlistentry id="{@id}">
> + <xsl:if test="@kind = 'class'">
> + <varlistentry id="{$which}{@id}">
> <term>
> <xsl:value-of select="compoundname" />
> <xsl:if test="normalize-space(briefdescription) != ''">
> @@ -165,6 +155,6 @@
> <xsl:apply-templates select="detaileddescription" />
> </listitem>
> </varlistentry>
> - </xsl:if>
> + </xsl:if>
> </xsl:template>
> </xsl:stylesheet>
> diff --git a/doc/publican/protocol-interfaces-to-docbook.xsl b/doc/publican/protocol-interfaces-to-docbook.xsl
> index fb1a816..57b3139 100644
> --- a/doc/publican/protocol-interfaces-to-docbook.xsl
> +++ b/doc/publican/protocol-interfaces-to-docbook.xsl
> @@ -37,11 +37,13 @@
> <term>
> <link linkend="protocol-spec-interface-{@name}">
> <xsl:value-of select="@name" />
> - <xsl:if test="description/@summary">
> - - <xsl:value-of select="description/@summary" />
> - </xsl:if>
> </link>
> </term>
> + <listitem>
> + <simpara>
> + <xsl:value-of select="description/@summary" />
> + </simpara>
> + </listitem>
> </varlistentry>
> </xsl:template>
>
> diff --git a/doc/publican/protocol-to-docbook.xsl b/doc/publican/protocol-to-docbook.xsl
> index 443228d..5eee0fe 100644
> --- a/doc/publican/protocol-to-docbook.xsl
> +++ b/doc/publican/protocol-to-docbook.xsl
> @@ -88,17 +88,17 @@
> <varlistentry>
> <term><xsl:value-of select="@name"/></term>
> <listitem>
> + <simpara>
> <xsl:if test="name() = 'arg'" >
> - <para>Type: <xsl:value-of select="@type"/></para>
> + Type: <xsl:value-of select="@type"/>
> </xsl:if>
> <xsl:if test="name() = 'entry'" >
> - <para>Value: <xsl:value-of select="@value"/></para>
> + Value: <xsl:value-of select="@value"/>
> </xsl:if>
> <xsl:if test="@summary" >
> - <para>
> - <xsl:value-of select="@summary"/>
> - </para>
> + <xsl:value-of select="@summary"/>
> </xsl:if>
> + </simpara>
> </listitem>
> </varlistentry>
> </xsl:template>
> --
> 1.7.9.5
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list