commit f6d6913 'convert to markdown' breaks pdfdocs with double <para>s

commit f6d6913 'convert to markdown' breaks pdfdocs with double <para>s

[Graham Whaley]

Hi,
 commit f6d6913425a560c3cd213096e34834e797ef83f8: drm/doc: Convert to
markdown

caused some changes to the drm.xml layout, particularly in the <para>
parts,that make pdfdocs generation unhappy.  In particular (working at
the commit above), the following new error:

 jade:/Documentation/DocBook/drm.xml:2491:8:E: document type does not
allow element "para" here; missing one of "footnote", "caution",
"important", "note", "tip", "warning", "blockquote", "informalexample"
start-tag

comes from this code:

---- drm.xml:2488
 <function>drm_vma_node_offset_addr</function>.
   </para>
   <para>
   <para>
   Additionally to offset management,
----

That code comes from:
  drm.tmpl:888: !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager

Before markdown/pandoc (or if you turn off MARKDOWN in the Makefile)
this looked like this:

---- drm.xml:2488
   please see <function>drm_vma_node_offset_addr</function>.
   </para><para>
   Additionally to offset management,
----

I've failed to figure out exactly how/what/why markdown/pandoc is doing
here or if it is a pandoc or kernel-doc or other error or
incompatibility.
As to the pdfdocs error, my suspicion is that nested <para>s are not
allowed, but the html generation 'gets away' with it - generating HTML
like this (grrr - Evolution is messing with the html layout below, even
in a 'plain text' email!):

---- drm/drm-memory-management.html:391
   <code class="function"><a class="link" href="API-drm-vma-node-offset
-addr.html"
title="drm_vma_node_offset_addr">drm_vma_node_offset_addr</a>      
</code>.                  
</p><p>                                                                
           
   </p><p>                                                             
              
   Additionally to offset management,
----

The double <para> is very easy to generate from pandoc. If the
following fragment is fed to pandoc using the same parameters as used
in kernel-doc then you see it. I grabbed the idea of the fragment by
enabling some of the stderr debug in kernel-doc to try and see what was
going on.

---- fragment.in
</para><para>
x
----

# pandoc --columns=80 -f markdown -t docbook fragment.in
---- stdout
</para>
<para>
<para>
  x
</para>
----

There are a number of occurrences of the 'double para' in the xml now,
but I have not figured out if there is a pattern to what makes those
specific parts come out that way, and not others.

Anybody got any ideas?

 Graham

Re: commit f6d6913 'convert to markdown' breaks pdfdocs with double <para>s

[Danilo Cesar Lemes de Paula]

On 08/17/2015 01:53 PM, Graham Whaley wrote:
> Hi,
>  commit f6d6913425a560c3cd213096e34834e797ef83f8: drm/doc: Convert to
> markdown
> 
> caused some changes to the drm.xml layout, particularly in the <para>
> parts,that make pdfdocs generation unhappy.  In particular (working at
> the commit above), the following new error:
> 
>  jade:/Documentation/DocBook/drm.xml:2491:8:E: document type does not
> allow element "para" here; missing one of "footnote", "caution",
> "important", "note", "tip", "warning", "blockquote", "informalexample"
> start-tag
> 
> comes from this code:
> 
> ---- drm.xml:2488
>  <function>drm_vma_node_offset_addr</function>.
>    </para>
>    <para>
>    <para>
>    Additionally to offset management,
> ----
> 
> That code comes from:
>   drm.tmpl:888: !Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager
> 
> Before markdown/pandoc (or if you turn off MARKDOWN in the Makefile)
> this looked like this:
> 
> ---- drm.xml:2488
>    please see <function>drm_vma_node_offset_addr</function>.
>    </para><para>
>    Additionally to offset management,
> ----
> 
> I've failed to figure out exactly how/what/why markdown/pandoc is doing
> here or if it is a pandoc or kernel-doc or other error or
> incompatibility.
> As to the pdfdocs error, my suspicion is that nested <para>s are not
> allowed, but the html generation 'gets away' with it - generating HTML
> like this (grrr - Evolution is messing with the html layout below, even
> in a 'plain text' email!):
> 
> ---- drm/drm-memory-management.html:391
>    <code class="function"><a class="link" href="API-drm-vma-node-offset
> -addr.html"
> title="drm_vma_node_offset_addr">drm_vma_node_offset_addr</a>      
> </code>.                  
> </p><p>                                                                
>            
>    </p><p>                                                             
>               
>    Additionally to offset management,
> ----
> 
> The double <para> is very easy to generate from pandoc. If the
> following fragment is fed to pandoc using the same parameters as used
> in kernel-doc then you see it. I grabbed the idea of the fragment by
> enabling some of the stderr debug in kernel-doc to try and see what was
> going on.
> 
> ---- fragment.in
> </para><para>
> x
> ----
> 
> # pandoc --columns=80 -f markdown -t docbook fragment.in
> ---- stdout
> </para>
> <para>
> <para>
>   x
> </para>
> ----
> 
> There are a number of occurrences of the 'double para' in the xml now,
> but I have not figured out if there is a pattern to what makes those
> specific parts come out that way, and not others.
> 
> Anybody got any ideas?

I think I know what's going on.

Pandoc is being called too late, Kernel-doc already applies some XML
formatting before the pandoc call is made.

I did see it before (and even fixed a minor side effect of that
behavior), but since it didn't cause any real issue with the html target
(error/warning-wise and visualization-wise) I didn't pay too much
attention to it.

Perhaps pandoc should be the one dealing with all paragraphs stuff in
case we have the markdown-down flag.
I will investigate this a bit more and send a fix soon.

Thanks for testing it and letting me know.

Danilo Cesar

* adding Jonathan Corbet to the CC list as he might be interested.