[RFC] Docs: drm: Move KMS properties table out to source files
On Mon, 2015-09-28 at 11:33 -0600, Jonathan Corbet wrote: > On Mon, 28 Sep 2015 10:36:59 +0100 > Graham Whaley 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
[RFC] Docs: drm: Move KMS properties table out to source files
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
> > > > > 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|
> > > +==+++=+===
> > >
> > > =+
> > > > rotation|BITMASK |{ 0, rotate-0 },
> > > {|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:
> > >
> > > ...
> > >
> > >
> > >
> > >
> > >rota
> > >
> > >
> > >
> > >
> > >tion/quo
> > >
> > >
> > >
> > >
> > >te|BITMASK |{ 0, qu
> > >
> > >
> > >
> > >
> > >oterotate
> > >
> > >
> > >
> > >
> > >-0 }, {|CRTC, |rotate-(degrees) rotates
> > >
> > > ...
> > >
> > > 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
> > > _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
[RFC] Docs: drm: Move KMS properties table out to source files
On Mon, 28 Sep 2015 10:36:59 +0100 Graham Whaley 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
[RFC] Docs: drm: Move KMS properties table out to source files
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
> > > > 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|
> > +==+++=+===
> >
> > =+
> > > rotation|BITMASK |{ 0, rotate-0 },
> > {|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:
> >
> > ...
> >
> >
> >
> >
> >rota
> >
> >
> >
> >
> >tion/quo
> >
> >
> >
> >
> >te|BITMASK |{ 0, qu
> >
> >
> >
> >
> >oterotate
> >
> >
> >
> >
> >-0 }, {|CRTC, |rotate-(degrees) rotates
> >
> > ...
> >
> > 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
> > _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
[RFC] Docs: drm: Move KMS properties table out to source files
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
>>> 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|
> +==+++=+===
> =+
> |rotation|BITMASK |{ 0, rotate-0 },
> {|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:
>
> ...
>
>
>
>
>rota
>
>
>
>
>tion/quo
>
>
>
>
>te|BITMASK |{ 0, qu
>
>
>
>
>oterotate
>
>
>
>
>-0 }, {|CRTC, |rotate-(degrees) rotates
>
> ...
>
> 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
> _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
[RFC] Docs: drm: Move KMS properties table out to source files
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
> > 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|
+==+++=+===
=+
|rotation|BITMASK |{ 0, rotate-0 },
{|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:
...
rota
tion/quo
te|BITMASK |{ 0, qu
oterotate
-0 }, {|CRTC, |rotate-(degrees) rotates
...
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
_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
[RFC] Docs: drm: Move KMS properties table out to source files
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 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.
>
> -
> -
> -
> - Owner Module/Drivers
> - Group
> - Property Name
> - Type
> - Property Values
> - Object attached
> - Description/Restrictions
> -
> -
> - DRM
> - Generic
> - ârotationâ
> - BITMASK
> - { 0, "rotate-0" },
> - { 1, "rotate-90" },
> - { 2, "rotate-180" },
> - { 3, "rotate-270" },
> - { 4, "reflect-x" },
> - { 5, "reflect-y" }
> - CRTC, Plane
> - 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
> -
> -
> - Connector
> - âEDIDâ
> - BLOB | IMMUTABLE
> - 0
> - Connector
> - Contains id of edid blob ptr object.
> -
> -
> - âDPMSâ
> - ENUM
> - { âOnâ, âStandbyâ, âSuspendâ, âOffâ
> }
> - Connector
> - Contains DPMS operation mode value.
> -
> -
> - âPATHâ
> - BLOB | IMMUTABLE
> - 0
> - Connector
> - Contains topology path to a connector.
> -
> -
> - âTILEâ
> - BLOB | IMMUTABLE
> - 0
> - Connector
> - Contains tiling information for a connector.
> -
> -
> - âCRTC_IDâ
> - OBJECT
> - DRM_MODE_OBJECT_CRTC
> - Connector
> - CRTC that connector is attached to (atomic)
> -
> -
> - Plane
> - âtypeâ
> - ENUM | IMMUTABLE
> - { "Overlay", "Primary", "Cursor" }
> - Plane
> - Plane type
> -
> -
> - âSRC_Xâ
> - RANGE
> - Min=0, Max=UINT_MAX
> - Plane
> - Scanout source x coordinate in 16.16 fixed point
> (atomic)
> -
> -
> - âSRC_Yâ
> - RANGE
> - Min=0, Max=UINT_MAX
> - Plane
> - Scanout source y coordinate in 16.16 fixed point
> (atomic)
> -
> -
> - âSRC_Wâ
> - RANGE
> - Min=0, Max=UINT_MAX
> - Plane
> - Scanout source width in 16.16 fixed point
> (atomic)
> -
> -
> - âSRC_Hâ
> - RANGE
> - Min=0, Max=UINT_MAX
> - Plane
> - Scanout source height in 16.16 fixed point
> (atomic)
> -
> -
> - âCRTC_Xâ
> - SIGNED_RANGE
> - Min=INT_MIN, Max=INT_MAX
> - Plane
> - Scanout CRTC (destination) x coordinate (atomic)
> -
> -
> - âCRTC_Yâ
> - SIGNED_RANGE
> - Min=INT_MIN, Max=INT_MAX
> - Plane
> - Scanout CRTC (destination) y coordinate (atomic)
> -
> -
> - âCRTC_Wâ
> - RANGE
> - Min=0, Max=UINT_MAX
> - Plane
> - Scanout CRTC (destination) width (atomic)
> -
> -
> - âCRTC_Hâ
> - RANGE
> - Min=0, Max=UINT_MAX
> - Plane
> - Scanout CRTC (destination) height (atomic)
> -
> -
> -
[RFC] Docs: drm: Move KMS properties table out to source files
On Wed, Sep 02, 2015 at 05:14:35PM +0300, Jani Nikula wrote: > On Wed, 02 Sep 2015, Graham Whaley 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 Software Engineer, Intel Corporation http://blog.ffwll.ch
[RFC] Docs: drm: Move KMS properties table out to source files
On Wed, 02 Sep 2015, Graham Whaley 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. -- Jani Nikula, Intel Open Source Technology Center
[RFC] Docs: drm: Move KMS properties table out to source files
(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 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(-)
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.
-
-
-
- Owner Module/Drivers
- Group
- Property Name
- Type
- Property Values
- Object attached
- Description/Restrictions
-
-
- DRM
- Generic
- ârotationâ
- BITMASK
- { 0, "rotate-0" },
- { 1, "rotate-90" },
- { 2, "rotate-180" },
- { 3, "rotate-270" },
- { 4, "reflect-x" },
- { 5, "reflect-y" }
- CRTC, Plane
- 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
-
-
- Connector
- âEDIDâ
- BLOB | IMMUTABLE
- 0
- Connector
- Contains id of edid blob ptr object.
-
-
- âDPMSâ
- ENUM
- { âOnâ, âStandbyâ, âSuspendâ, âOffâ
}
- Connector
- Contains DPMS operation mode value.
-
-
- âPATHâ
- BLOB | IMMUTABLE
- 0
- Connector
- Contains topology path to a connector.
-
-
- âTILEâ
- BLOB | IMMUTABLE
- 0
- Connector
- Contains tiling information for a connector.
-
-
- âCRTC_IDâ
- OBJECT
- DRM_MODE_OBJECT_CRTC
- Connector
- CRTC that connector is attached to (atomic)
-
-
- Plane
- âtypeâ
- ENUM | IMMUTABLE
- { "Overlay", "Primary", "Cursor" }
- Plane
- Plane type
-
-
- âSRC_Xâ
- RANGE
- Min=0, Max=UINT_MAX
- Plane
- Scanout source x coordinate in 16.16 fixed point
(atomic)
-
-
- âSRC_Yâ
- RANGE
- Min=0, Max=UINT_MAX
- Plane
- Scanout source y coordinate in 16.16 fixed point
(atomic)
-
-
- âSRC_Wâ
- RANGE
- Min=0, Max=UINT_MAX
- Plane
- Scanout source width in 16.16 fixed point
(atomic)
-
-
- âSRC_Hâ
- RANGE
- Min=0, Max=UINT_MAX
- Plane
- Scanout source height in 16.16 fixed point
(atomic)
-
-
- âCRTC_Xâ
- SIGNED_RANGE
- Min=INT_MIN, Max=INT_MAX
- Plane
- Scanout CRTC (destination) x coordinate (atomic)
-
-
- âCRTC_Yâ
- SIGNED_RANGE
- Min=INT_MIN, Max=INT_MAX
- Plane
- Scanout CRTC (destination) y coordinate (atomic)
-
-
- âCRTC_Wâ
- RANGE
- Min=0, Max=UINT_MAX
- Plane
- Scanout CRTC (destination) width (atomic)
-
-
- âCRTC_Hâ
- RANGE
- Min=0, Max=UINT_MAX
- Plane
- Scanout CRTC (destination) height (atomic)
-
-
- âFB_IDâ
- OBJECT
- DRM_MODE_OBJECT_FB
- Plane
- Scanout framebuffer (atomic)
-
-
- âCRTC_IDâ
- OBJECT
- DRM_MODE_OBJECT_CRTC
- Plane
- CRTC that plane is attached to (atomic)
-
-
- DVI-I
- âsubconnectorâ
- ENUM
- { âUnknownâ, âDVI-Dâ, âDVI-Aâ }
- Connector
- TBD
-
-
- âselect subconnectorâ
- ENUM
-
