[Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers

[Sagar Arun Kamble]

Hi Laurent, Daniel
On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote:
> Hi Daniel,
> 
> On Monday 10 March 2014 06:21:49 Daniel Vetter wrote:
> > On Wed, Mar 5, 2014 at 11:56 AM,  <sagar.a.kamble at intel.com> wrote:
> > > +<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 Object</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</td>
> > > +</tr>
> > 
> > In my opinion this is a horrible way to write property documentations
> > - explicitly constructing html tables is error prone and really hard
> > to read in the source. Imo docbook in general is rather horrible,
> > which is way I write almost all my docs as kerneldoc ;-)
> > 
> > I think a simple asciidoc/markdown would be much simpler, with a bit
> > of free-form structure to group properties into relevant groups.
> > Long-term we might even need to split it up into different spec files
> > to keep a good overview.
> 
> Docbook is indeed hard to read and write when it comes to such tables. However 
> I like having the properties documented in the DRM core documentation. Maybe 
> we could come up with a simpler text format that would be transformed into 
> docbook when compiling the documentation ?
Does this mean we need to create comment block with "Doc: drm
properties" style section in each driver where drm properties are
instantiated. And then in drm.tmpl collect all these using !P escape
sequence?
How do create table out of these across all drivers?