From mboxrd@z Thu Jan 1 00:00:00 1970 From: Thierry Reding Subject: Re: [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers Date: Tue, 13 May 2014 09:17:42 +0200 Message-ID: <20140513071741.GB6754@ulmo> References: <1394016990-5218-1-git-send-email-sagar.a.kamble@intel.com> <2919182.UBDg5nOr7Z@avalon> <1394622965.18918.12.camel@sagar-desktop> <3136468.2PAlK4Gq8k@avalon> <20140510103937.GC18465@intel.com> <1399874873.15218.32.camel@sagar-desktop> <20140512080355.GB25056@phenom.ffwll.local> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============2039188887==" Return-path: In-Reply-To: <20140512080355.GB25056@phenom.ffwll.local> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: intel-gfx-bounces@lists.freedesktop.org Sender: "Intel-gfx" To: Daniel Vetter Cc: Laurent Pinchart , linux-doc@vger.kernel.org, Daniel Vetter , intel-gfx , shashidhar.hiremath@intel.com, "dri-devel@lists.freedesktop.org" , Laurent Pinchart , Rob Landley , Alex Deucher , Dave Airlie , Sagar Arun Kamble List-Id: intel-gfx@lists.freedesktop.org --===============2039188887== Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="R3G7APHDIzY6R/pk" Content-Disposition: inline --R3G7APHDIzY6R/pk Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 > >=20 > > Adding description of new property is not very complex (assuming table > > format is understood and being comfortable with HTML row/table > > manipulation). > >=20 > > Adding description of each property in their source might be time > > consuming task. >=20 > 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. Thierry --R3G7APHDIzY6R/pk Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iQIcBAEBAgAGBQJTcccVAAoJEN0jrNd/PrOhA68QAIllaLrSNC2+MjB7h7zLjtT/ P1u46mSgvvwA6p7D/9YJYEjAQv4EtLUMKtd1Hiht5CTKXAs0+SZqSm6nTg43oN0U k9e43of6jRhtuqrUaGGw0sS1Ch+T3WPATk7yhVozbOzGOqXvpaMagAt6B6A7TIGX TQCVuVPrBqGmvln3Dw5FARxUbEdBy8ZpsRemN0HGNq8DOZlvAklE3ahhDmf5PbrE DTXlyLxfB2MPyEJNd9OQMfpNlOR3Lo/rD/GVmjYk3bUxZUyxrYIWjNaefNzcZlGa H4yu6i2P5g6D9uDf1pMWBVCradmcfxXmtCA/Y95IUdr3+yJDMqxhwz9FQtUn/DVs 5VTKeOJ0sR6CPR/fm8sbP5gkMjTkM9MLVOE/vBUL5uXPJurbuGX9rQzXaDmM/R+A O/ufxcXg56MHRRwde1RbTwc6FX9Sy97fWrT92A6qJZk53ol7syYM2Hx2vd/iMdPm MkDNxYd9pzzzfXYKWyr9wLOclobIt8+fa0R/u10L/DAtpQ9POMgs2A08upvJfQ0y 2K2H4rNbB7rL75/X/OKzq24e0Us2XojTeyS3JZJRBrAz5MR6Uia3mnVKMpEnzI6y FZkTSzz61uqaPDxDc+TpN3DjNCyo1ZJjXoJ8rfO5hlosYtq803fWCKuX3spAgzfC Bem+ZpbLHAcqGvpT16EL =vH/M -----END PGP SIGNATURE----- --R3G7APHDIzY6R/pk-- --===============2039188887== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/intel-gfx --===============2039188887==--