On Fri, Aug 12, 2016 at 12:05:04PM +0530, Sumit Semwal wrote: > Hi Jon! > > On 11 August 2016 at 20:06, Jonathan Corbet <corbet@xxxxxxx> wrote: > > On Thu, 11 Aug 2016 16:17:56 +0530 > > Sumit Semwal <sumit.semwal@xxxxxxxxxx> 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 ... <looks> ... 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. I already tried to trick Sumit into converting the entire device-drivers.tmpl, but he didn't take the bait ;-) I think just extracting dma-buf stuff (dma_buf, fence, reservation and all that) is ok though, it is a fairly stand-alone topic. -Daniel > > > Does that make sense? > > > I do hope that my proposal above finds some merit with everyone. > > > Thanks, > > > > jon > > BR, > Sumit. > _______________________________________________ > dri-devel mailing list > dri-devel@xxxxxxxxxxxxxxxxxxxxx > https://lists.freedesktop.org/mailman/listinfo/dri-devel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- 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
