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.