[RFC] Docs: drm: Move KMS properties table out to source files

[Danilo Cesar Lemes de Paula]

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