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