From dfc64f9ffe0ceecf8e93d6eba3fdb7b1165c9c43 Mon Sep 17 00:00:00 2001
From: Bill Spitzak <spitzak@gmail.com>
Date: Thu, 18 Dec 2014 20:15:05 -0800
Subject: [PATCH] doc: Reduce the validation errors of the docbook input

(this is different from previous version as it removes some
broken and irrelevant changes to the protocol appendix).

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 avoid nesting <para> commands. I also used
<simpara> in some places to reduce the amount of blank space.
And the reference id's are prefixed with the chapter name to
avoid collisions between libclient and libserver.

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.

Tested-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
---
 doc/publican/doxygen-to-publican.xsl            | 44 ++++++++++---------------
 doc/publican/protocol-interfaces-to-docbook.xsl |  8 +++--
 doc/publican/protocol-to-docbook.xsl            |  4 +--
 3 files changed, 23 insertions(+), 33 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..a43c9fa 100644
--- a/doc/publican/protocol-to-docbook.xsl
+++ b/doc/publican/protocol-to-docbook.xsl
@@ -95,9 +95,7 @@
           <para>Value: <xsl:value-of select="@value"/></para>
         </xsl:if>
         <xsl:if test="@summary" >
-          <para>
-            <xsl:value-of select="@summary"/>
-          </para>
+          <para><xsl:value-of select="@summary"/></para>
         </xsl:if>
     </listitem>
   </varlistentry>
-- 
2.7.4