On Wed, Sep 02, 2015 at 02:50:52PM +0100, Graham Whaley wrote:
> > (RFC/test - not for merging)
> > The below is a test of moving the large HTML KMS properties table
> > out
> > to markdown style in the appropriate files.
> > In the test we only use the first few rows of the existing KMS
> > table
> > an example.
> > We use a fixed width table as the other styles of table supported
> > by
> > pandoc markdown do not support multi-column cells.
> >
> > The test shows a couple of issues:
> > 1) double quote characters are being expanded in the fixed width
> > table
> > which then breaks the table alignment and leaves html style
> > <quote> tags
> > in the text
Further to this item:
Before I continue working on splitting the tables and converting to
markdown (which btw Daniel does look feasible so far...), I thought we
should understand what was going on with the markdown table quote
breakage.
I think I know what is happenig.
The problem revolves around highlight expansion in the kenrel-doc
script. In the output_highlight function we can see that first the
script does highlight expansion (with the eval of @dohighlight), and
then it invokes the markdown processing.
Done that way around what happens is:
- @dohighlight expands any "X" to html/xml quote tag sequences
- which can push the text beyond the table column widths,
- and then the markdown tries to split the text over columns, and
manages to put the break in the middle of a tag, and thus breaks the
tag formatting (see below)
At least that is what I think is happening.
I had thought maybe we could swap the markdown and highlight processing
order, but then that presents a different issue - the markdown table
contains metadata with quoted items (such as cols="5"), which the
highligh processing then expands into tags, and hence breaks the table
format metadata.
As an example, using the following table !Pinclude'd into drm.tmpl:
/**
* DOC: DRM generic
*
* : DRM generic properties
*
* +----------+--------+--------------------+---------+----------------
--------+
* |Property |Type |Property Values |Object
|Description/Restrictions|
*
+==========+========+====================+=========+===================
=====+
* |"rotation"|BITMASK |{ 0, "rotate-0" }, {|CRTC, |rotate-(degrees)
rotates|
* +----------+--------+--------------------+---------+----------------
--------+
*
*/
The post-highlight pre-markdown text captured as the $orig_context in
the markdown_to_docbook function is:
+----------+--------+--------------------+---------+-------------------
-----+
|Property |Type |Property Values |Object
|Description/Restrictions|
+==========+========+====================+=========+===================
=====+
|<quote>rotation</quote>|BITMASK |{ 0, <quote>rotate-0</quote> },
{|CRTC, |rotate-(degrees) rotates|
+----------+--------+--------------------+---------+-------------------
-----+
which when processed (and you can do this by hand with 'pandoc -
-columns=80 -f markdown -t docbook ...' generates the broken tags
example:
...
<tbody>
<row>
<entry>
<para>
<quote>rota
</para>
</entry>
<entry>
<para>
tion</quo
</para>
</entry>
<entry>
<para>
te>|BITMASK |{ 0, <qu
</para>
</entry>
<entry>
<para>
ote>rotate
</para>
</entry>
<entry>
<para>
-0</quote> }, {|CRTC, |rotate-(degrees) rotates
</para>
...
where you can see the quote tag processing has gone horribly wrong.
I believe we'll have the same problem for the other 'highlight'
processed items from kern-doc as well, meaning:
funcname()
$ENVVAR
&struct_name
@parameter
%CONST
As the kern-doc processing has no knowledge of when it is about to
process a markdown table I can't think of an obvious way around this.
At present I think the implicit rule is 'no highlight/expansion items
allowed in markdown tables', which means all those quoted strings for
the DRM properties cannot currently be migrated to look like strings.
Danilo, or anybody, any ideas?
Graham
