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. _______________________________________________ dri-devel mailing list dri-devel@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/dri-devel
