From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752508AbcHLGf2 (ORCPT ); Fri, 12 Aug 2016 02:35:28 -0400 Received: from mail-wm0-f53.google.com ([74.125.82.53]:37375 "EHLO mail-wm0-f53.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752408AbcHLGf0 (ORCPT ); Fri, 12 Aug 2016 02:35:26 -0400 MIME-Version: 1.0 In-Reply-To: <20160811083652.55371952@lwn.net> References: <1470912480-32304-1-git-send-email-sumit.semwal@linaro.org> <20160811083652.55371952@lwn.net> From: Sumit Semwal Date: Fri, 12 Aug 2016 12:05:04 +0530 Message-ID: Subject: Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup To: Jonathan Corbet Cc: "linux-media@vger.kernel.org" , DRI mailing list , Linaro MM SIG Mailman List , linux-doc@vger.kernel.org, LKML Content-Type: text/plain; charset=UTF-8 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Jon! On 11 August 2016 at 20:06, Jonathan Corbet wrote: > On Thu, 11 Aug 2016 16:17:56 +0530 > Sumit Semwal wrote: > >> Convert dma-buf documentation over to sphinx; also cleanup to >> address sphinx warnings. >> >> While at that, convert dma-buf-sharing.txt as well, and make it the >> dma-buf API guide. > > Thanks for working to improve the documentation! I do have a few overall > comments... > Thank you for your review, and comments; my responses are inline. > - The two comment fixes are a separate thing that should go straight to > the dma-buf maintainer, who is ... ... evidently somebody > familiar to you :) I assume you'll merge those two directly? > Yes, of course :) - I will merge them directly, and will remove them from v2 of this series. > - It looks like you create a new RST document but leave the old one in > place. Having two copies of the document around can only lead to > confusion, so I think the old one should go. > Agreed on this as well; will correct it. > - I really wonder if we want to start carving pieces out of > device-drivers.tmpl in this way. I guess I would rather see the > conversion of that book and the better integration of the other docs > *into* it. One of the goals of this whole thing is to unify our > documentation, not to reinforce the silos. > I should've mentioned it in the cover letter - my intention of taking the dma-buf pieces out was to focus on these first while moving to sphinx. My proposal would be, if all the device driver section owners could take the relevant pieces, convert them to sphinx (ironing out warnings etc in the process), then we can again 'bind' them together into the device drivers book in rst format. This breaks the documentation conversion task into manageable pieces that can be handled independently, and gives everyone flexibility to work on their schedules. This should also help in a good technical re-look at the content by subsystem developers, and make any documentation updates as required. The beauty of sphinx should allow us this, I think? Just my 2 cents. > Does that make sense? > I do hope that my proposal above finds some merit with everyone. > Thanks, > > jon BR, Sumit. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sumit Semwal Subject: Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup Date: Fri, 12 Aug 2016 12:05:04 +0530 Message-ID: References: <1470912480-32304-1-git-send-email-sumit.semwal@linaro.org> <20160811083652.55371952@lwn.net> Mime-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Return-path: Received: from mail-wm0-x22b.google.com (mail-wm0-x22b.google.com [IPv6:2a00:1450:400c:c09::22b]) by gabe.freedesktop.org (Postfix) with ESMTPS id 153BF6EA76 for ; Fri, 12 Aug 2016 06:35:26 +0000 (UTC) Received: by mail-wm0-x22b.google.com with SMTP id i5so12274903wmg.0 for ; Thu, 11 Aug 2016 23:35:26 -0700 (PDT) In-Reply-To: <20160811083652.55371952@lwn.net> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dri-devel-bounces@lists.freedesktop.org Sender: "dri-devel" To: Jonathan Corbet Cc: Linaro MM SIG Mailman List , linux-doc@vger.kernel.org, LKML , DRI mailing list , "linux-media@vger.kernel.org" List-Id: dri-devel@lists.freedesktop.org SGkgSm9uIQoKT24gMTEgQXVndXN0IDIwMTYgYXQgMjA6MDYsIEpvbmF0aGFuIENvcmJldCA8Y29y YmV0QGx3bi5uZXQ+IHdyb3RlOgo+IE9uIFRodSwgMTEgQXVnIDIwMTYgMTY6MTc6NTYgKzA1MzAK PiBTdW1pdCBTZW13YWwgPHN1bWl0LnNlbXdhbEBsaW5hcm8ub3JnPiB3cm90ZToKPgo+PiBDb252 ZXJ0IGRtYS1idWYgZG9jdW1lbnRhdGlvbiBvdmVyIHRvIHNwaGlueDsgYWxzbyBjbGVhbnVwIHRv Cj4+IGFkZHJlc3Mgc3BoaW54IHdhcm5pbmdzLgo+Pgo+PiBXaGlsZSBhdCB0aGF0LCBjb252ZXJ0 IGRtYS1idWYtc2hhcmluZy50eHQgYXMgd2VsbCwgYW5kIG1ha2UgaXQgdGhlCj4+IGRtYS1idWYg QVBJIGd1aWRlLgo+Cj4gVGhhbmtzIGZvciB3b3JraW5nIHRvIGltcHJvdmUgdGhlIGRvY3VtZW50 YXRpb24hICBJIGRvIGhhdmUgYSBmZXcgb3ZlcmFsbAo+IGNvbW1lbnRzLi4uCj4KVGhhbmsgeW91 IGZvciB5b3VyIHJldmlldywgYW5kIGNvbW1lbnRzOyBteSByZXNwb25zZXMgYXJlIGlubGluZS4K Cj4gIC0gVGhlIHR3byBjb21tZW50IGZpeGVzIGFyZSBhIHNlcGFyYXRlIHRoaW5nIHRoYXQgc2hv dWxkIGdvIHN0cmFpZ2h0IHRvCj4gICAgdGhlIGRtYS1idWYgbWFpbnRhaW5lciwgd2hvIGlzIC4u LiA8bG9va3M+IC4uLiBldmlkZW50bHkgc29tZWJvZHkKPiAgICBmYW1pbGlhciB0byB5b3UgOikg IEkgYXNzdW1lIHlvdSdsbCBtZXJnZSB0aG9zZSB0d28gZGlyZWN0bHk/Cj4KWWVzLCBvZiBjb3Vy c2UgOikgLSBJIHdpbGwgbWVyZ2UgdGhlbSBkaXJlY3RseSwgYW5kIHdpbGwgcmVtb3ZlIHRoZW0K ZnJvbSB2MiBvZiB0aGlzIHNlcmllcy4KCj4gIC0gSXQgbG9va3MgbGlrZSB5b3UgY3JlYXRlIGEg bmV3IFJTVCBkb2N1bWVudCBidXQgbGVhdmUgdGhlIG9sZCBvbmUgaW4KPiAgICBwbGFjZS4gIEhh dmluZyB0d28gY29waWVzIG9mIHRoZSBkb2N1bWVudCBhcm91bmQgY2FuIG9ubHkgbGVhZCB0bwo+ ICAgIGNvbmZ1c2lvbiwgc28gSSB0aGluayB0aGUgb2xkIG9uZSBzaG91bGQgZ28uCj4KQWdyZWVk IG9uIHRoaXMgYXMgd2VsbDsgd2lsbCBjb3JyZWN0IGl0LgoKPiAgLSBJIHJlYWxseSB3b25kZXIg aWYgd2Ugd2FudCB0byBzdGFydCBjYXJ2aW5nIHBpZWNlcyBvdXQgb2YKPiAgICBkZXZpY2UtZHJp dmVycy50bXBsIGluIHRoaXMgd2F5LiAgSSBndWVzcyBJIHdvdWxkIHJhdGhlciBzZWUgdGhlCj4g ICAgY29udmVyc2lvbiBvZiB0aGF0IGJvb2sgYW5kIHRoZSBiZXR0ZXIgaW50ZWdyYXRpb24gb2Yg dGhlIG90aGVyIGRvY3MKPiAgICAqaW50byogaXQuICBPbmUgb2YgdGhlIGdvYWxzIG9mIHRoaXMg d2hvbGUgdGhpbmcgaXMgdG8gdW5pZnkgb3VyCj4gICAgZG9jdW1lbnRhdGlvbiwgbm90IHRvIHJl aW5mb3JjZSB0aGUgc2lsb3MuCj4KSSBzaG91bGQndmUgbWVudGlvbmVkIGl0IGluIHRoZSBjb3Zl ciBsZXR0ZXIgLSBteSBpbnRlbnRpb24gb2YgdGFraW5nCnRoZSBkbWEtYnVmIHBpZWNlcyBvdXQg d2FzIHRvIGZvY3VzIG9uIHRoZXNlIGZpcnN0IHdoaWxlIG1vdmluZyB0bwpzcGhpbnguCgpNeSBw cm9wb3NhbCB3b3VsZCBiZSwgaWYgYWxsIHRoZSBkZXZpY2UgZHJpdmVyIHNlY3Rpb24gb3duZXJz IGNvdWxkCnRha2UgdGhlIHJlbGV2YW50IHBpZWNlcywgY29udmVydCB0aGVtIHRvIHNwaGlueCAo aXJvbmluZyBvdXQgd2FybmluZ3MKZXRjIGluIHRoZSBwcm9jZXNzKSwgdGhlbiB3ZSBjYW4gYWdh aW4gJ2JpbmQnIHRoZW0gdG9nZXRoZXIgaW50byB0aGUKZGV2aWNlIGRyaXZlcnMgYm9vayBpbiBy c3QgZm9ybWF0LgpUaGlzIGJyZWFrcyB0aGUgZG9jdW1lbnRhdGlvbiBjb252ZXJzaW9uIHRhc2sg aW50byBtYW5hZ2VhYmxlIHBpZWNlcwp0aGF0IGNhbiBiZSBoYW5kbGVkIGluZGVwZW5kZW50bHks IGFuZCBnaXZlcyBldmVyeW9uZSBmbGV4aWJpbGl0eSB0bwp3b3JrIG9uIHRoZWlyIHNjaGVkdWxl cy4KClRoaXMgc2hvdWxkIGFsc28gaGVscCBpbiBhIGdvb2QgdGVjaG5pY2FsIHJlLWxvb2sgYXQg dGhlIGNvbnRlbnQgYnkKc3Vic3lzdGVtIGRldmVsb3BlcnMsIGFuZCBtYWtlIGFueSBkb2N1bWVu dGF0aW9uIHVwZGF0ZXMgYXMgcmVxdWlyZWQuClRoZSBiZWF1dHkgb2Ygc3BoaW54IHNob3VsZCBh bGxvdyB1cyB0aGlzLCBJIHRoaW5rPyBKdXN0IG15IDIgY2VudHMuCgo+IERvZXMgdGhhdCBtYWtl IHNlbnNlPwo+CkkgZG8gaG9wZSB0aGF0IG15IHByb3Bvc2FsIGFib3ZlIGZpbmRzIHNvbWUgbWVy aXQgd2l0aCBldmVyeW9uZS4KCj4gVGhhbmtzLAo+Cj4gam9uCgpCUiwKU3VtaXQuCl9fX19fX19f X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fCmRyaS1kZXZlbCBtYWlsaW5n IGxpc3QKZHJpLWRldmVsQGxpc3RzLmZyZWVkZXNrdG9wLm9yZwpodHRwczovL2xpc3RzLmZyZWVk ZXNrdG9wLm9yZy9tYWlsbWFuL2xpc3RpbmZvL2RyaS1kZXZlbAo=