diff mbox

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

Message ID 1441201852-4236-1-git-send-email-graham.whaley@linux.intel.com (mailing list archive)
State New, archived
Headers show

Commit Message

Graham Whaley Sept. 2, 2015, 1:50 p.m. UTC 
(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

 2) Cramming the seven columns into the apprx 80ish column width makes
 some entries fairly impractical - one word per row. For reference,
 pdfdocs rendering clips the fixed text tables at around 80 characters.

If we can:
 a) Resolve (1) above
and
 b) Agree that we are OK with comment fields extending beyond the 80th
 column significantly

then maybe we can continue looking at moving the KMS properties table out
of drm.tmpl and into markdown format fragments in the source files.
If not, then maybe we go back to considering the conversion of the KMS
table to docbook CALS format.
---
 Documentation/DocBook/drm.tmpl | 925 +----------------------------------------
 drivers/gpu/drm/drm_crtc.c     |  16 +
 2 files changed, 17 insertions(+), 924 deletions(-)

Comments

Jani Nikula Sept. 2, 2015, 2:14 p.m. UTC | #1 
On Wed, 02 Sep 2015, Graham Whaley <graham.whaley@linux.intel.com> wrote:
>  Documentation/DocBook/drm.tmpl | 925 +----------------------------------------
>  drivers/gpu/drm/drm_crtc.c     |  16 +
>  2 files changed, 17 insertions(+), 924 deletions(-)

I like this already.

BR,
Jani.
Daniel Vetter Sept. 2, 2015, 3:28 p.m. UTC | #2 
On Wed, Sep 02, 2015 at 05:14:35PM +0300, Jani Nikula wrote:
> On Wed, 02 Sep 2015, Graham Whaley <graham.whaley@linux.intel.com> wrote:
> >  Documentation/DocBook/drm.tmpl | 925 +----------------------------------------
> >  drivers/gpu/drm/drm_crtc.c     |  16 +
> >  2 files changed, 17 insertions(+), 924 deletions(-)
> 
> I like this already.

Well the patch removes the entire table but only adds the entry for
rotation property.
-Daniel
Daniel Vetter Sept. 2, 2015, 3:30 p.m. UTC | #3 
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
> 
>  2) Cramming the seven columns into the apprx 80ish column width makes
>  some entries fairly impractical - one word per row. For reference,
>  pdfdocs rendering clips the fixed text tables at around 80 characters.
> 
> If we can:
>  a) Resolve (1) above
> and
>  b) Agree that we are OK with comment fields extending beyond the 80th
>  column significantly
> 
> then maybe we can continue looking at moving the KMS properties table out
> of drm.tmpl and into markdown format fragments in the source files.
> If not, then maybe we go back to considering the conversion of the KMS
> table to docbook CALS format.

Another option would be to split up the table into sub-tables - the first
1-2 rows are really just headings for sub-tables imo. If we split them up
we have tables without spans and that could use the markdown table layout
instead of fixed-width text.

But then we'd need to do that part-by-part ...
-Daniel

> ---
>  Documentation/DocBook/drm.tmpl | 925 +----------------------------------------
>  drivers/gpu/drm/drm_crtc.c     |  16 +
>  2 files changed, 17 insertions(+), 924 deletions(-)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 66bc646..ecfd084 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -2573,930 +2573,7 @@ void intel_crt_init(struct drm_device *dev)
>  	The following table gives description of drm properties exposed by various
>  	modules/drivers.
>  	</para>
> -	<table border="1" cellpadding="0" cellspacing="0">
> -	<tbody>
> -	<tr style="font-weight: bold;">
> -	<td valign="top" >Owner Module/Drivers</td>
> -	<td valign="top" >Group</td>
> -	<td valign="top" >Property Name</td>
> -	<td valign="top" >Type</td>
> -	<td valign="top" >Property Values</td>
> -	<td valign="top" >Object attached</td>
> -	<td valign="top" >Description/Restrictions</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="37" valign="top" >DRM</td>
> -	<td valign="top" >Generic</td>
> -	<td valign="top" >“rotation”</td>
> -	<td valign="top" >BITMASK</td>
> -	<td valign="top" >{ 0, "rotate-0" },
> -	{ 1, "rotate-90" },
> -	{ 2, "rotate-180" },
> -	{ 3, "rotate-270" },
> -	{ 4, "reflect-x" },
> -	{ 5, "reflect-y" }</td>
> -	<td valign="top" >CRTC, Plane</td>
> -	<td valign="top" >rotate-(degrees) rotates the image by the specified amount in degrees
> -	in counter clockwise direction. reflect-x and reflect-y reflects the
> -	image along the specified axis prior to rotation</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="5" valign="top" >Connector</td>
> -	<td valign="top" >“EDID”</td>
> -	<td valign="top" >BLOB | IMMUTABLE</td>
> -	<td valign="top" >0</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >Contains id of edid blob ptr object.</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“DPMS”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >Contains DPMS operation mode value.</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“PATH”</td>
> -	<td valign="top" >BLOB | IMMUTABLE</td>
> -	<td valign="top" >0</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >Contains topology path to a connector.</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“TILE”</td>
> -	<td valign="top" >BLOB | IMMUTABLE</td>
> -	<td valign="top" >0</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >Contains tiling information for a connector.</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“CRTC_ID”</td>
> -	<td valign="top" >OBJECT</td>
> -	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >CRTC that connector is attached to (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="11" valign="top" >Plane</td>
> -	<td valign="top" >“type”</td>
> -	<td valign="top" >ENUM | IMMUTABLE</td>
> -	<td valign="top" >{ "Overlay", "Primary", "Cursor" }</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Plane type</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“SRC_X”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=UINT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“SRC_Y”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=UINT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“SRC_W”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=UINT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“SRC_H”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=UINT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“CRTC_X”</td>
> -	<td valign="top" >SIGNED_RANGE</td>
> -	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“CRTC_Y”</td>
> -	<td valign="top" >SIGNED_RANGE</td>
> -	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“CRTC_W”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=UINT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout CRTC (destination) width (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“CRTC_H”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=UINT_MAX</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout CRTC (destination) height (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“FB_ID”</td>
> -	<td valign="top" >OBJECT</td>
> -	<td valign="top" >DRM_MODE_OBJECT_FB</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >Scanout framebuffer (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“CRTC_ID”</td>
> -	<td valign="top" >OBJECT</td>
> -	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >CRTC that plane is attached to (atomic)</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="2" valign="top" >DVI-I</td>
> -	<td valign="top" >“subconnector”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“select subconnector”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="13" valign="top" >TV</td>
> -	<td valign="top" >“subconnector”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“select subconnector”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“left margin”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“right margin”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“top margin”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“bottom margin”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“brightness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“contrast”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker reduction”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“overscan”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“saturation”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“hue”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="2" valign="top" >Virtual GPU</td>
> -	<td valign="top" >“suggested X”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffffff</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >property to suggest an X offset for a connector</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“suggested Y”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffffff</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >property to suggest an Y offset for a connector</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="3" valign="top" >Optional</td>
> -	<td valign="top" >“scaling mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"aspect ratio"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "None", "4:3", "16:9" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >DRM property to set aspect ratio from user space app.
> -		This enum is made generic to allow addition of custom aspect
> -		ratios.</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“dirty”</td>
> -	<td valign="top" >ENUM | IMMUTABLE</td>
> -	<td valign="top" >{ "Off", "On", "Annotate" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="20" valign="top" >i915</td>
> -	<td rowspan="2" valign="top" >Generic</td>
> -	<td valign="top" >"Broadcast RGB"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“audio”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "force-dvi", "off", "auto", "on" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="17" valign="top" >SDVO-TV</td>
> -	<td valign="top" >“mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"left_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"right_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"top_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"bottom_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“hpos”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“vpos”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“contrast”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“saturation”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“hue”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“sharpness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker_filter”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker_filter_adaptive”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker_filter_2d”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“tv_chroma_filter”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“tv_luma_filter”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“dot_crawl”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >SDVO-TV/LVDS</td>
> -	<td valign="top" >“brightness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="2" valign="top" >CDV gma-500</td>
> -	<td rowspan="2" valign="top" >Generic</td>
> -	<td valign="top" >"Broadcast RGB"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ “Full”, “Limited 16:235” }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"Broadcast RGB"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ “off”, “auto”, “on” }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="19" valign="top" >Poulsbo</td>
> -	<td rowspan="1" valign="top" >Generic</td>
> -	<td valign="top" >“backlight”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=100</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="17" valign="top" >SDVO-TV</td>
> -	<td valign="top" >“mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"left_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"right_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"top_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"bottom_margin"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“hpos”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“vpos”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“contrast”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“saturation”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“hue”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“sharpness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker_filter”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker_filter_adaptive”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“flicker_filter_2d”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“tv_chroma_filter”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“tv_luma_filter”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“dot_crawl”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >SDVO-TV/LVDS</td>
> -	<td valign="top" >“brightness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max= SDVO dependent</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="11" valign="top" >armada</td>
> -	<td rowspan="2" valign="top" >CRTC</td>
> -	<td valign="top" >"CSC_YUV"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td>
> -	<td valign="top" >CRTC</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"CSC_RGB"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "Auto", "Computer system", "Studio" }</td>
> -	<td valign="top" >CRTC</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="9" valign="top" >Overlay</td>
> -	<td valign="top" >"colorkey"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"colorkey_min"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"colorkey_max"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"colorkey_val"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"colorkey_alpha"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0xffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"colorkey_mode"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "disabled", "Y component", "U component"
> -	, "V component", "RGB", “R component", "G component", "B component" }</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"brightness"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=256 + 255</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"contrast"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0x7fff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"saturation"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0x7fff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="2" valign="top" >exynos</td>
> -	<td valign="top" >CRTC</td>
> -	<td valign="top" >“mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "normal", "blank" }</td>
> -	<td valign="top" >CRTC</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >Overlay</td>
> -	<td valign="top" >“zpos”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=MAX_PLANE-1</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="2" valign="top" >i2c/ch7006_drv</td>
> -	<td valign="top" >Generic</td>
> -	<td valign="top" >“scale”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=2</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="1" valign="top" >TV</td>
> -	<td valign="top" >“mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc"
> -	, "PAL-60", "NTSC-M", "NTSC-J" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="15" valign="top" >nouveau</td>
> -	<td rowspan="6" valign="top" >NV10 Overlay</td>
> -	<td valign="top" >"colorkey"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0x01ffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“contrast”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=8192-1</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“brightness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1024</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“hue”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=359</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“saturation”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=8192-1</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“iturbt_709”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="2" valign="top" >Nv04 Overlay</td>
> -	<td valign="top" >“colorkey”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0x01ffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“brightness”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1024</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="7" valign="top" >Display</td>
> -	<td valign="top" >“dithering mode”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "auto", "off", "on" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“dithering depth”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“underscan”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“underscan hborder”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=128</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“underscan vborder”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=128</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“vibrant hue”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=180</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >“color vibrance”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=200</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >omap</td>
> -	<td valign="top" >Generic</td>
> -	<td valign="top" >“zorder”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=3</td>
> -	<td valign="top" >CRTC, Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >qxl</td>
> -	<td valign="top" >Generic</td>
> -	<td valign="top" >“hotplug_mode_update"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="9" valign="top" >radeon</td>
> -	<td valign="top" >DVI-I</td>
> -	<td valign="top" >“coherent”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >DAC enable load detect</td>
> -	<td valign="top" >“load detection”</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=1</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >TV Standard</td>
> -	<td valign="top" >"tv standard"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j"
> -	, "scart-pal", "pal-cn", "secam" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >legacy TMDS PLL detect</td>
> -	<td valign="top" >"tmds_pll"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "driver", "bios" }</td>
> -	<td valign="top" >-</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="3" valign="top" >Underscan</td>
> -	<td valign="top" >"underscan"</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "off", "on", "auto" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"underscan hborder"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=128</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"underscan vborder"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=128</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >Audio</td>
> -	<td valign="top" >“audio”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "off", "on", "auto" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >FMT Dithering</td>
> -	<td valign="top" >“dither”</td>
> -	<td valign="top" >ENUM</td>
> -	<td valign="top" >{ "off", "on" }</td>
> -	<td valign="top" >Connector</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td rowspan="3" valign="top" >rcar-du</td>
> -	<td rowspan="3" valign="top" >Generic</td>
> -	<td valign="top" >"alpha"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=255</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"colorkey"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=0, Max=0x01ffffff</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	<tr>
> -	<td valign="top" >"zpos"</td>
> -	<td valign="top" >RANGE</td>
> -	<td valign="top" >Min=1, Max=7</td>
> -	<td valign="top" >Plane</td>
> -	<td valign="top" >TBD</td>
> -	</tr>
> -	</tbody>
> -	</table>
> +!Pdrivers/gpu/drm/drm_crtc.c rotation properties
>      </sect2>
>    </sect1>
>  
> diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
> index 474f328..d48cc02 100644
> --- a/drivers/gpu/drm/drm_crtc.c
> +++ b/drivers/gpu/drm/drm_crtc.c
> @@ -5760,6 +5760,22 @@ void drm_mode_config_cleanup(struct drm_device *dev)
>  }
>  EXPORT_SYMBOL(drm_mode_config_cleanup);
>  
> +/**
> + * DOC: rotation properties
> + *
> + *     DRM rotation properties
> + *     ----------------------------------------------------------------------------
> + *     |Owner  |Group  |Property  |Type   |Property         |Object  |Description/|
> + *     |Module/|       |Name      |       |Values           |attached|Restrictions|
> + *     |Drivers|       |          |       |                 |        |            |
> + *     --------|-------|----------|-------|-----------------|--------|-------------
> + *     |DRM    |Generic|"rotation"|BITMASK|{0, "rotate-0"}, |CRTC,   |rotate      |
> + *     |       |       |          |       |{1, "rotate-90"},|Plane   |{degrees}   |
> + *     |       |       |          |       |                 |        |rotates     |
> + *     |       |       |          |       |{ blah           |        |the image   |
> + *     |       |       |          |       |...              |        |...         |
> + *     ----------------------------------------------------------------------------
> + */
>  struct drm_property *drm_mode_create_rotation_property(struct drm_device *dev,
>  						       unsigned int supported_rotations)
>  {
> -- 
> 2.4.3
>
Graham Whaley Sept. 22, 2015, 10:22 a.m. UTC | #4 
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&lt;/quo
             </para>
           </entry>
           <entry>
             <para>
               te&gt;|BITMASK |{ 0, &lt;qu
             </para>
           </entry>
           <entry>
             <para>
               ote&gt;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
Danilo Cesar Lemes de Paula Sept. 22, 2015, 7:03 p.m. UTC | #5 
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&lt;/quo
>              </para>
>            </entry>
>            <entry>
>              <para>
>                te&gt;|BITMASK |{ 0, &lt;qu
>              </para>
>            </entry>
>            <entry>
>              <para>
>                ote&gt;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
Graham Whaley Sept. 28, 2015, 9:36 a.m. UTC | #6 
On Tue, 2015-09-22 at 16:03 -0300, Danilo Cesar Lemes de Paula wrote:
> 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&lt;/quo
> >              </para>
> >            </entry>
> >            <entry>
> >              <para>
> >                te&gt;|BITMASK |{ 0, &lt;qu
> >              </para>
> >            </entry>
> >            <entry>
> >              <para>
> >                ote&gt;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

Hi all,
 I had a look at the 'pipe' table type - and the other table types
available in pandoc_markdown. I've consolidated my thoughts into the
following analysis. Note, this thread is not presently on the docs-list
- we should pull that in as well if we think it may help.

Let's say there are 5 table types we can use in pandoc_markdown, if we
add in the use of the 'codeblock' type to the four formal
pandoc_markdown tables (see table later...).

My hypothesis' are:

1) We need to have a table format that supports multi-line rows, as
some rows in the DRM table are way too big to be putting on a single
line in the source file (for instance, the 'rotation' example I have
been using totals somewhere in the region of 349 characters as a single
line)
2) We need to support the kernel-doc highlight types in the tables as:
 2a) We need to use double quotes for strings in the DRM table at least
 2b) And I think the other highlight types will be useful in the future
3) We need a table type that allows the highlight tags to be
subsequently processed into the final document format (otherwise the
highlight tag expansions get left as raw tags in the final text).
4) Because (2) 'expands' a line width when it is processing/tagging the
highlights we need a table type that supports variable length lines,
and is not based on fixed width column processing.

If we summarise that in a table (ironically :-):

tabletype | multiline | variable | processed | suitable?
--------------------------------------------------------
simple    | No        | No       | Yes       | No
multi     | Yes       | No       | Yes       | No
grid      | Yes       | No       | Yes       | No
pipe      | No        | Yes      | Yes       | No
codeblock | Yes       | Yes      | No        | No

What we are looking for is a Yes in the first three columns. And thus,
presently it looks to me like none of the table formats are wholly
suitable :-(

I've still not thought of a way of tweaking the kernel-doc and pandoc
processing to work around this either, as they are done as different
passes/phases that neither has knowledge about the others
requirements.

As it stands, I'm failing to find a method to break out the DRM table
into markdown tables that I believe works, fundamentally due to this
'incompatibility' between the kernel-doc and pandoc_markdown processing
phases around the highlight processing.

 Graham
Daniel Vetter Sept. 28, 2015, 12:44 p.m. UTC | #7 
On Mon, Sep 28, 2015 at 10:36:59AM +0100, Graham Whaley wrote:
> On Tue, 2015-09-22 at 16:03 -0300, Danilo Cesar Lemes de Paula wrote:
> > 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&lt;/quo
> > >              </para>
> > >            </entry>
> > >            <entry>
> > >              <para>
> > >                te&gt;|BITMASK |{ 0, &lt;qu
> > >              </para>
> > >            </entry>
> > >            <entry>
> > >              <para>
> > >                ote&gt;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
> 
> Hi all,
>  I had a look at the 'pipe' table type - and the other table types
> available in pandoc_markdown. I've consolidated my thoughts into the
> following analysis. Note, this thread is not presently on the docs-list
> - we should pull that in as well if we think it may help.
> 
> Let's say there are 5 table types we can use in pandoc_markdown, if we
> add in the use of the 'codeblock' type to the four formal
> pandoc_markdown tables (see table later...).
> 
> My hypothesis' are:
> 
> 1) We need to have a table format that supports multi-line rows, as
> some rows in the DRM table are way too big to be putting on a single
> line in the source file (for instance, the 'rotation' example I have
> been using totals somewhere in the region of 349 characters as a single
> line)

I think that requirement should probably be dropped, squeezing full-blown
semantics of properties into these tables just doesn't work really. For
complext stuff I except that the table just lists the propers with short
descriptions, and a bit of prose below explains the detailed
semantics/fallbacks/interactions. E.g. with color manager we'll have a
total of 5 properties, but need some _very_ detailed explanations of how
they work and interact. That won't even fit in 20 lines ;-)

> 2) We need to support the kernel-doc highlight types in the tables as:
>  2a) We need to use double quotes for strings in the DRM table at least
>  2b) And I think the other highlight types will be useful in the future
> 3) We need a table type that allows the highlight tags to be
> subsequently processed into the final document format (otherwise the
> highlight tag expansions get left as raw tags in the final text).
> 4) Because (2) 'expands' a line width when it is processing/tagging the
> highlights we need a table type that supports variable length lines,
> and is not based on fixed width column processing.
> 
> If we summarise that in a table (ironically :-):
> 
> tabletype | multiline | variable | processed | suitable?
> --------------------------------------------------------
> simple    | No        | No       | Yes       | No
> multi     | Yes       | No       | Yes       | No
> grid      | Yes       | No       | Yes       | No
> pipe      | No        | Yes      | Yes       | No
> codeblock | Yes       | Yes      | No        | No
> 
> What we are looking for is a Yes in the first three columns. And thus,
> presently it looks to me like none of the table formats are wholly
> suitable :-(
> 
> I've still not thought of a way of tweaking the kernel-doc and pandoc
> processing to work around this either, as they are done as different
> passes/phases that neither has knowledge about the others
> requirements.
> 
> As it stands, I'm failing to find a method to break out the DRM table
> into markdown tables that I believe works, fundamentally due to this
> 'incompatibility' between the kernel-doc and pandoc_markdown processing
> phases around the highlight processing.

Yeah, 1:1 translation won't work, but I think the current table for
properties doesn't work either. Pulling the details out of the table into
prose means we only need a Yes for "variable" and "processed", so I think
we should be covered. Of course if we could somehow resolve this conflict
between kerneldoc and pandoc that would be even better. One idea I have
(but it's a bit nuts) is to only build up a list of all the replacements
we'd like to do, then send things to pandoc and then apply them on the
output. That way we'll make sure that we don't accidentally replace some
of the markup pandoc generated. Would that be compatible with the ""
parsing issues?
-Daniel"
Jonathan Corbet Sept. 28, 2015, 5:33 p.m. UTC | #8 
On Mon, 28 Sep 2015 10:36:59 +0100
Graham Whaley <graham.whaley@linux.intel.com> wrote:

> I've still not thought of a way of tweaking the kernel-doc and pandoc
> processing to work around this either, as they are done as different
> passes/phases that neither has knowledge about the others
> requirements.
> 
> As it stands, I'm failing to find a method to break out the DRM table
> into markdown tables that I believe works, fundamentally due to this
> 'incompatibility' between the kernel-doc and pandoc_markdown processing
> phases around the highlight processing.

This sort of thing is why I'm increasingly nervous about this one-off mix
of doc-generation tools we're putting together.  Sigh.

One possibility might be to have kernel-doc understand some sort of table
notation of its own and make it do the right thing.

Another might be to have kernel-doc format unconditionally to markdown
(or ReST, or something) all the time, then have the secondary processor
handle everything from there.  A bigger change, obviously.  Probably not
something anybody wants to face, but we may reach a point where we need
to consider having less than three independent formatting tools in the
mix.  I *may* get a chance to mess with this idea in the next week or so,
but no promises.

jon
Graham Whaley Nov. 13, 2015, 7:19 p.m. UTC | #9 
On Mon, 2015-09-28 at 11:33 -0600, Jonathan Corbet wrote:
> On Mon, 28 Sep 2015 10:36:59 +0100
> Graham Whaley <graham.whaley@linux.intel.com> wrote:
> 
> > I've still not thought of a way of tweaking the kernel-doc and
> > pandoc
> > processing to work around this either, as they are done as
> > different
> > passes/phases that neither has knowledge about the others
> > requirements.
> > 
> > As it stands, I'm failing to find a method to break out the DRM
> > table
> > into markdown tables that I believe works, fundamentally due to
> > this
> > 'incompatibility' between the kernel-doc and pandoc_markdown
> > processing
> > phases around the highlight processing.
> 
> This sort of thing is why I'm increasingly nervous about this one-off
> mix
> of doc-generation tools we're putting together.  Sigh.

Hi Jon, all. Just to note, I've not forgotten about this. I was hoping
to bump into you at ELCE/LinuxCon Dublin to maybe chat over it Jon -
but I think you were not there. I see you did a talk on this topic at
the kernel summit though, and have read through your lwn.net article
and the string of replies.

> 
> One possibility might be to have kernel-doc understand some sort of
> table
> notation of its own and make it do the right thing.
> 
> Another might be to have kernel-doc format unconditionally to
> markdown
> (or ReST, or something) all the time, then have the secondary
> processor
> handle everything from there.  A bigger change, obviously.  Probably
> not
> something anybody wants to face, but we may reach a point where we
> need
> to consider having less than three independent formatting tools in
> the
> mix.  I *may* get a chance to mess with this idea in the next week or
> so,
> but no promises.
> 
The whole idea of moving this more towards some KISS philosophy rather
than further away is obviously appealing :-) I'm guessing you didn't
find any time yet?
I've been staring at the workflow of docproc and kernel-doc to try and
wrap my head better around exactly how it works at present.
Did you have thoughts on how moving kernel-doc to produce markdown all
the time would work in practice? Presumably we'd then have to put a
markdown->docbook processor between docproc and kernel-doc (be that
pandoc or something else). That may then solve the mixing of docbook
and markdown inside of kernel-doc that I saw with the highlighting
expansion.
I'll see if I can find some time to play with the idea - but please let
me know if that was not what you had in mind.

 Graham

> jon
diff mbox

Patch

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 66bc646..ecfd084 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -2573,930 +2573,7 @@  void intel_crt_init(struct drm_device *dev)
 	The following table gives description of drm properties exposed by various
 	modules/drivers.
 	</para>
-	<table border="1" cellpadding="0" cellspacing="0">
-	<tbody>
-	<tr style="font-weight: bold;">
-	<td valign="top" >Owner Module/Drivers</td>
-	<td valign="top" >Group</td>
-	<td valign="top" >Property Name</td>
-	<td valign="top" >Type</td>
-	<td valign="top" >Property Values</td>
-	<td valign="top" >Object attached</td>
-	<td valign="top" >Description/Restrictions</td>
-	</tr>
-	<tr>
-	<td rowspan="37" valign="top" >DRM</td>
-	<td valign="top" >Generic</td>
-	<td valign="top" >“rotation”</td>
-	<td valign="top" >BITMASK</td>
-	<td valign="top" >{ 0, "rotate-0" },
-	{ 1, "rotate-90" },
-	{ 2, "rotate-180" },
-	{ 3, "rotate-270" },
-	{ 4, "reflect-x" },
-	{ 5, "reflect-y" }</td>
-	<td valign="top" >CRTC, Plane</td>
-	<td valign="top" >rotate-(degrees) rotates the image by the specified amount in degrees
-	in counter clockwise direction. reflect-x and reflect-y reflects the
-	image along the specified axis prior to rotation</td>
-	</tr>
-	<tr>
-	<td rowspan="5" valign="top" >Connector</td>
-	<td valign="top" >“EDID”</td>
-	<td valign="top" >BLOB | IMMUTABLE</td>
-	<td valign="top" >0</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >Contains id of edid blob ptr object.</td>
-	</tr>
-	<tr>
-	<td valign="top" >“DPMS”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ “On”, “Standby”, “Suspend”, “Off” }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >Contains DPMS operation mode value.</td>
-	</tr>
-	<tr>
-	<td valign="top" >“PATH”</td>
-	<td valign="top" >BLOB | IMMUTABLE</td>
-	<td valign="top" >0</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >Contains topology path to a connector.</td>
-	</tr>
-	<tr>
-	<td valign="top" >“TILE”</td>
-	<td valign="top" >BLOB | IMMUTABLE</td>
-	<td valign="top" >0</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >Contains tiling information for a connector.</td>
-	</tr>
-	<tr>
-	<td valign="top" >“CRTC_ID”</td>
-	<td valign="top" >OBJECT</td>
-	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >CRTC that connector is attached to (atomic)</td>
-	</tr>
-	<tr>
-	<td rowspan="11" valign="top" >Plane</td>
-	<td valign="top" >“type”</td>
-	<td valign="top" >ENUM | IMMUTABLE</td>
-	<td valign="top" >{ "Overlay", "Primary", "Cursor" }</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Plane type</td>
-	</tr>
-	<tr>
-	<td valign="top" >“SRC_X”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=UINT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout source x coordinate in 16.16 fixed point (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“SRC_Y”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=UINT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout source y coordinate in 16.16 fixed point (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“SRC_W”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=UINT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout source width in 16.16 fixed point (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“SRC_H”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=UINT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout source height in 16.16 fixed point (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“CRTC_X”</td>
-	<td valign="top" >SIGNED_RANGE</td>
-	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout CRTC (destination) x coordinate (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“CRTC_Y”</td>
-	<td valign="top" >SIGNED_RANGE</td>
-	<td valign="top" >Min=INT_MIN, Max=INT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout CRTC (destination) y coordinate (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“CRTC_W”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=UINT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout CRTC (destination) width (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“CRTC_H”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=UINT_MAX</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout CRTC (destination) height (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“FB_ID”</td>
-	<td valign="top" >OBJECT</td>
-	<td valign="top" >DRM_MODE_OBJECT_FB</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >Scanout framebuffer (atomic)</td>
-	</tr>
-	<tr>
-	<td valign="top" >“CRTC_ID”</td>
-	<td valign="top" >OBJECT</td>
-	<td valign="top" >DRM_MODE_OBJECT_CRTC</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >CRTC that plane is attached to (atomic)</td>
-	</tr>
-	<tr>
-	<td rowspan="2" valign="top" >DVI-I</td>
-	<td valign="top" >“subconnector”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ “Unknown”, “DVI-D”, “DVI-A” }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“select subconnector”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ “Automatic”, “DVI-D”, “DVI-A” }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="13" valign="top" >TV</td>
-	<td valign="top" >“subconnector”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "Unknown", "Composite", "SVIDEO", "Component", "SCART" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“select subconnector”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "Automatic", "Composite", "SVIDEO", "Component", "SCART" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“left margin”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“right margin”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“top margin”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“bottom margin”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“brightness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“contrast”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker reduction”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“overscan”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“saturation”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“hue”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="2" valign="top" >Virtual GPU</td>
-	<td valign="top" >“suggested X”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffffff</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >property to suggest an X offset for a connector</td>
-	</tr>
-	<tr>
-	<td valign="top" >“suggested Y”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffffff</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >property to suggest an Y offset for a connector</td>
-	</tr>
-	<tr>
-	<td rowspan="3" valign="top" >Optional</td>
-	<td valign="top" >“scaling mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "None", "Full", "Center", "Full aspect" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"aspect ratio"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "None", "4:3", "16:9" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >DRM property to set aspect ratio from user space app.
-		This enum is made generic to allow addition of custom aspect
-		ratios.</td>
-	</tr>
-	<tr>
-	<td valign="top" >“dirty”</td>
-	<td valign="top" >ENUM | IMMUTABLE</td>
-	<td valign="top" >{ "Off", "On", "Annotate" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="20" valign="top" >i915</td>
-	<td rowspan="2" valign="top" >Generic</td>
-	<td valign="top" >"Broadcast RGB"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "Automatic", "Full", "Limited 16:235" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“audio”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "force-dvi", "off", "auto", "on" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="17" valign="top" >SDVO-TV</td>
-	<td valign="top" >“mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"left_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"right_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"top_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"bottom_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“hpos”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“vpos”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“contrast”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“saturation”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“hue”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“sharpness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker_filter”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker_filter_adaptive”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker_filter_2d”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“tv_chroma_filter”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“tv_luma_filter”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“dot_crawl”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >SDVO-TV/LVDS</td>
-	<td valign="top" >“brightness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="2" valign="top" >CDV gma-500</td>
-	<td rowspan="2" valign="top" >Generic</td>
-	<td valign="top" >"Broadcast RGB"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ “Full”, “Limited 16:235” }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"Broadcast RGB"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ “off”, “auto”, “on” }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="19" valign="top" >Poulsbo</td>
-	<td rowspan="1" valign="top" >Generic</td>
-	<td valign="top" >“backlight”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=100</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="17" valign="top" >SDVO-TV</td>
-	<td valign="top" >“mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "NTSC_M", "NTSC_J", "NTSC_443", "PAL_B" } etc.</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"left_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"right_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"top_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"bottom_margin"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“hpos”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“vpos”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“contrast”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“saturation”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“hue”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“sharpness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker_filter”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker_filter_adaptive”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“flicker_filter_2d”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“tv_chroma_filter”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“tv_luma_filter”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“dot_crawl”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >SDVO-TV/LVDS</td>
-	<td valign="top" >“brightness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max= SDVO dependent</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="11" valign="top" >armada</td>
-	<td rowspan="2" valign="top" >CRTC</td>
-	<td valign="top" >"CSC_YUV"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "Auto" , "CCIR601", "CCIR709" }</td>
-	<td valign="top" >CRTC</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"CSC_RGB"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "Auto", "Computer system", "Studio" }</td>
-	<td valign="top" >CRTC</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="9" valign="top" >Overlay</td>
-	<td valign="top" >"colorkey"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"colorkey_min"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"colorkey_max"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"colorkey_val"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"colorkey_alpha"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0xffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"colorkey_mode"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "disabled", "Y component", "U component"
-	, "V component", "RGB", “R component", "G component", "B component" }</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"brightness"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=256 + 255</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"contrast"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0x7fff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"saturation"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0x7fff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="2" valign="top" >exynos</td>
-	<td valign="top" >CRTC</td>
-	<td valign="top" >“mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "normal", "blank" }</td>
-	<td valign="top" >CRTC</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >Overlay</td>
-	<td valign="top" >“zpos”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=MAX_PLANE-1</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="2" valign="top" >i2c/ch7006_drv</td>
-	<td valign="top" >Generic</td>
-	<td valign="top" >“scale”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=2</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="1" valign="top" >TV</td>
-	<td valign="top" >“mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "PAL", "PAL-M","PAL-N"}, ”PAL-Nc"
-	, "PAL-60", "NTSC-M", "NTSC-J" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="15" valign="top" >nouveau</td>
-	<td rowspan="6" valign="top" >NV10 Overlay</td>
-	<td valign="top" >"colorkey"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0x01ffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“contrast”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=8192-1</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“brightness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1024</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“hue”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=359</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“saturation”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=8192-1</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“iturbt_709”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="2" valign="top" >Nv04 Overlay</td>
-	<td valign="top" >“colorkey”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0x01ffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“brightness”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1024</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="7" valign="top" >Display</td>
-	<td valign="top" >“dithering mode”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "auto", "off", "on" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“dithering depth”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "auto", "off", "on", "static 2x2", "dynamic 2x2", "temporal" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“underscan”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "auto", "6 bpc", "8 bpc" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“underscan hborder”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=128</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“underscan vborder”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=128</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“vibrant hue”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=180</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >“color vibrance”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=200</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >omap</td>
-	<td valign="top" >Generic</td>
-	<td valign="top" >“zorder”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=3</td>
-	<td valign="top" >CRTC, Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >qxl</td>
-	<td valign="top" >Generic</td>
-	<td valign="top" >“hotplug_mode_update"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="9" valign="top" >radeon</td>
-	<td valign="top" >DVI-I</td>
-	<td valign="top" >“coherent”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >DAC enable load detect</td>
-	<td valign="top" >“load detection”</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=1</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >TV Standard</td>
-	<td valign="top" >"tv standard"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "ntsc", "pal", "pal-m", "pal-60", "ntsc-j"
-	, "scart-pal", "pal-cn", "secam" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >legacy TMDS PLL detect</td>
-	<td valign="top" >"tmds_pll"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "driver", "bios" }</td>
-	<td valign="top" >-</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="3" valign="top" >Underscan</td>
-	<td valign="top" >"underscan"</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "off", "on", "auto" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"underscan hborder"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=128</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"underscan vborder"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=128</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >Audio</td>
-	<td valign="top" >“audio”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "off", "on", "auto" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >FMT Dithering</td>
-	<td valign="top" >“dither”</td>
-	<td valign="top" >ENUM</td>
-	<td valign="top" >{ "off", "on" }</td>
-	<td valign="top" >Connector</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td rowspan="3" valign="top" >rcar-du</td>
-	<td rowspan="3" valign="top" >Generic</td>
-	<td valign="top" >"alpha"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=255</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"colorkey"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=0, Max=0x01ffffff</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	<tr>
-	<td valign="top" >"zpos"</td>
-	<td valign="top" >RANGE</td>
-	<td valign="top" >Min=1, Max=7</td>
-	<td valign="top" >Plane</td>
-	<td valign="top" >TBD</td>
-	</tr>
-	</tbody>
-	</table>
+!Pdrivers/gpu/drm/drm_crtc.c rotation properties
     </sect2>
   </sect1>
 
diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
index 474f328..d48cc02 100644
--- a/drivers/gpu/drm/drm_crtc.c
+++ b/drivers/gpu/drm/drm_crtc.c
@@ -5760,6 +5760,22 @@  void drm_mode_config_cleanup(struct drm_device *dev)
 }
 EXPORT_SYMBOL(drm_mode_config_cleanup);
 
+/**
+ * DOC: rotation properties
+ *
+ *     DRM rotation properties
+ *     ----------------------------------------------------------------------------
+ *     |Owner  |Group  |Property  |Type   |Property         |Object  |Description/|
+ *     |Module/|       |Name      |       |Values           |attached|Restrictions|
+ *     |Drivers|       |          |       |                 |        |            |
+ *     --------|-------|----------|-------|-----------------|--------|-------------
+ *     |DRM    |Generic|"rotation"|BITMASK|{0, "rotate-0"}, |CRTC,   |rotate      |
+ *     |       |       |          |       |{1, "rotate-90"},|Plane   |{degrees}   |
+ *     |       |       |          |       |                 |        |rotates     |
+ *     |       |       |          |       |{ blah           |        |the image   |
+ *     |       |       |          |       |...              |        |...         |
+ *     ----------------------------------------------------------------------------
+ */
 struct drm_property *drm_mode_create_rotation_property(struct drm_device *dev,
 						       unsigned int supported_rotations)
 {