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

Graham Whaley graham.whaley at linux.intel.com
Tue Sep 22 03:22:58 PDT 2015


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




More information about the Intel-gfx mailing list