[PATCH] doc: Reduce the validation errors of the docbook input

[Bill Spitzak]

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.

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.
---
 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