From mboxrd@z Thu Jan  1 00:00:00 1970
From: Graham Whaley <graham.whaley@linux.intel.com>
Subject: commit f6d6913 'convert to markdown' breaks pdfdocs with double
 <para>s
Date: Mon, 17 Aug 2015 17:53:33 +0100
Message-ID: <1439830413.21310.9.camel@linux.intel.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: 7bit
Return-path: <linux-doc-owner@vger.kernel.org>
Sender: linux-doc-owner@vger.kernel.org
To: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk>, dri-devel@lists.freedesktop.org
Cc: Daniel Vetter <daniel.vetter@intel.com>, linux-doc@vger.kernel.org
List-Id: dri-devel@lists.freedesktop.org

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