On 09/22/2015 07:22 AM, Graham Whaley wrote:
> 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?
Your debugging is pretty precise. The "+=====+===" format is rigid. I
don't know if it's a bug in pandoc or something from the spec itself.
May I suggest another format?
| Property | Type |
|------------|:-------:|
| "rotation" | BITMASK |
This format looks to work pretty well even if "rotation" is replaced by
some very long string (which seems to be the problem). I didn't test it
with kernel-doc, but pandoc looks to work fine with it.
I'm not sure if we can call it a proper fix, but it should allow you to
keep the ball rolling.
--
Danilo Cesar
_______________________________________________
Intel-gfx mailing list
Intel-gfx@xxxxxxxxxxxxxxxxxxxxx
http://lists.freedesktop.org/mailman/listinfo/intel-gfx
