I support approach using docbook to start since there are not lot of properties. Laurent has ack'ed this one. Can we go ahead with this? http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html Adding description of new property is not very complex (assuming table format is understood and being comfortable with HTML row/table manipulation). Adding description of each property in their source might be time consuming task. thanks, Sagar On Sat, 2014-05-10 at 06:56 -0400, Rob Clark wrote: > On Sat, May 10, 2014 at 6:39 AM, Ville Syrjälä > <ville.syrjala@xxxxxxxxxxxxxxx> wrote: > > On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote: > >> Hi Sagar, > >> > >> On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote: > >> > On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote: > >> > > On Monday 10 March 2014 06:21:49 Daniel Vetter wrote: > >> > > > On Wed, Mar 5, 2014 at 11:56 AM, <sagar.a.kamble@xxxxxxxxx> 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? > >> > >> I don't have a strong preference here. Documenting properties in source code > >> comments would be fine, so would an external central documentation file in a > >> non Docbook format. For the record I'm personally fine with using Docbook as > >> in this patch :-) > >> > >> If we decide to go for property documentation inside the source code then I > >> believe we'll have to create our own format, as creating a properties table > >> from kerneldoc information extracted from comments is probably not possible. > > > > Can comeone pick up the ball here and figure out what needs to be done? > > > > The reason why I want a central place for the documentation is to force > > people to collaborate outside their own sandbox when adding properties. > > Whether that's docbook or some text file I don't care so much at this > > point. The fact that it's a central place should mandate that the > > patches changing it will go through dri-devel and so everyone should se > > them, and when adding new properties it would make the patch author more > > likely to look around a bit before adding another slighty incompatible > > version of the same property. If someone has a better suggestion how to > > encforce this I'm all ears. > > > > Of course this idea can still fail if our esteemed maintainer merges > > stuff without checking for violations of this policy. Dave, any thoughts > > on the subject? > > > > Either way I can tell you that I'm not very enthusiastic about reviewing > > any property patches until some kind of decision about this is reached, > > be it "docbook", "text", "plan c", or "fuck it, let the world burn!". > > any of the first three options would be vastly superior to what we do now > > tbh, I'd suggest imposing a no-new-properties-without-docs rule even > if we haven't finished bikeshedding about the docs format. That might > motivate someone to hurry up and just pick one. > > We can change the format, figure out some way to get it into docbook, > etc, later.. it's not such a huge volume of words we have to type here > that we can't reformat it later. > > BR, > -R > > > > > > -- > > Ville Syrjälä > > Intel OTC > > _______________________________________________ > > dri-devel mailing list > > dri-devel@xxxxxxxxxxxxxxxxxxxxx > > http://lists.freedesktop.org/mailman/listinfo/dri-devel -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
