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

[Laurent Pinchart]

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 ?

-- 
Regards,

Laurent Pinchart