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

[Graham Whaley]

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