doc: Reduce the validation errors of the docbook input

Submitted by Bill Spitzak on Dec. 10, 2014, 3:33 a.m.

Details

Message ID 1418182431-65427-1-git-send-email-spitzak@gmail.com
State Changes Requested
Headers show

Not browsing as part of any series.

Commit Message

Bill Spitzak Dec. 10, 2014, 3:33 a.m.
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(-)

Patch hide | download patch | download mbox

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>

Comments

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@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@lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
On 12/10/2014 04:53 PM, Bryce Harrington wrote:

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

It seems to avoid putting a blank line before and after it, which I 
think make the variable lists look a lot nicer. <para> avoids the 
validation errors too, but put a lot of whitespace in the output.

I found it from the validation error message, which lists all the 
commands allowed at that point.

I don't think it should be used in regular text, use <para> there.
On 12/09/2014 07:33 PM, Bill Spitzak wrote:
> 
> 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.


Unfortunately, that sounds like it could be me.  ;-)


I'm currently in the middle of trying to get a reasonable xslt to inject
image map areas into the docbook XML. Once that's set I can poke at this
<para> issue.
On Wed, 10 Dec 2014 16:53:01 -0800
Bryce Harrington <bryce@osg.samsung.com> wrote:

> 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@osg.samsung.com>

The changes to Chapter 4 are nice.

The changes to Appendix A seem to be lacking somewhat, we get things
like:

callback_data
    Type: uintrequest-specific data for the wl_callback

There should be some separation between the type and the explanation.
There used to be <p> tags, but now there is nothing.

In Appendices B and C I did not notice any breakage.

Could you revise this patch to fix that one issue?


I think this patch does too many things in one go, the para changes are
not related for the id namespacing, are they?


Thanks,
pq

> 
> > ---
> >  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(-)