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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
