Hi Daniel, On Tuesday 13 May 2014 09:34:45 Daniel Vetter wrote: > On Tue, May 13, 2014 at 9:17 AM, Thierry Reding wrote: > > On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: > >> On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: > >> > 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. > >> > >> Yeah I'm ok with docbook for the time being. My long-term plan is to fix > >> up kerneldoc to support markdown and then we can move such neat tables > >> into the code. There's lots other places that would benefit from proper > >> list formatting and tables. So Ack from my side on both the docbook patch > >> and the no-more-props-without-doc-patch rule (which is kinda what I've > >> been doing thus far). > > > > What happened to the proposal to add this to the Documentation/ABI > > directory? That already contains a bunch of files describing userspace > > ABI (although most of it is sysfs-related). > > > > The objection that I have to including property documentation in docbook > > is that the DRM docbook is documentation targetted at driver developers, > > but properties are userspace ABI. Therefore I think we should be using > > mechanisms that have been used to document other userspace ABI before to > > make it easier for people to find (and for consistency). > > > > One big advantage in using Documentation/ABI is that there's a fairly > > well documented process of how to add, deprecate and remove ABI. There's > > also a template that should be followed when writing these files. People > > have obviously put some thought into this before, so it would be a bit > > of a waste trying to come up with our own. > > > > The README file has some good information about all of this and I think > > it matches what we need fairly well. In particular I like the concept of > > the "Users" section, which could save us a lot of work trying to track > > potential users of crufty ABI retrospectively. > > Not really sold on this, since in the end if we break userspace we > have to fix it up anyway. And all these properties are meant to be > used by userspace after all. I think for properties it's more > important to keep them all grouped together so that if new driver > writes look for something to use they don't reinvent a slight > variation of something existing again. Documentation/ABI otoh seems to > split things up per-knob, even across stable/testing/deprecated > directories. > > Also eventually I want to pull these tables directly out of source > code comments - everything else tends to never get updated when the > code changes. On the subject of moving documentation from docbook to source code, do your kerneldoc extensions plans include supporting images ? A drawing is worth a thousand words (see http://linuxtv.org/downloads/v4l-dvb-apis/subdev.html#subdev-image-processing-scaling-multi-source for instance), and that's currently a pretty important feature of the docbook format. -- Regards, Laurent Pinchart -- 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
