From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932079AbcF3KUO (ORCPT ); Thu, 30 Jun 2016 06:20:14 -0400 Received: from lists.s-osg.org ([54.187.51.154]:37282 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750937AbcF3KUK (ORCPT ); Thu, 30 Jun 2016 06:20:10 -0400 Date: Thu, 30 Jun 2016 07:18:13 -0300 From: Mauro Carvalho Chehab To: Markus Heiser Cc: Jonathan Corbet , Dave Airlie , Jani Nikula , Grant Likely , Keith Packard , LKML Mailing List , "linux-doc@vger.kernel.org" , Hans Verkuil , Randy Dunlap Subject: Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next Message-ID: <20160630071813.05a94cb1@recife.lan> In-Reply-To: <573D454C-2F55-4DD7-9C16-00B3897AEFB0@darmarit.de> References: <6A1AB08B-E585-42E2-A604-D5144A7BC6B4@darmarit.de> <20160629102426.08570878@lwn.net> <7B63766B-0F9E-417D-A101-13B9B092F64F@darmarit.de> <20160629115209.596ffd8b@lwn.net> <20160629175745.554c93a9@recife.lan> <573D454C-2F55-4DD7-9C16-00B3897AEFB0@darmarit.de> Organization: Samsung X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.30; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Thu, 30 Jun 2016 11:25:11 +0200 Markus Heiser escreveu: > Am 29.06.2016 um 22:57 schrieb Mauro Carvalho Chehab : > > > Em Wed, 29 Jun 2016 11:52:09 -0600 > > Jonathan Corbet escreveu: > > > >>> 2. What is the best way to ship these migrations > >>> > >>> or better I asked, what is your recommendation for a > >>> migration strategy. Jani says, that this better belongs > >>> to authors, but I have a doubt that we end with the > >>> migration in the next years, if we wait about every author. > >>> I think, supporting both infrastructures - the xml and the > >>> reST - over a long period is not the best option. What is > >>> your recommendation on this? > >> > >> I think we need to give maintainers the first shot at doing the conversion; > >> in any case, I don't think we can just force it through without their > >> cooperation. And, honestly, while we're still groping around in this > >> space, I think it's fine if we don't have lots of conversions right away. > >> The ones that go more slowly will benefit from what we learn with the easy > >> ones. > >> > >> You could certainly talk to maintainers and see if they would like > >> assistance with specific books. Helping Mauro to get his tables done > >> without going totally nuts would be a great first step, IMO. > > > > Yeah, going to each maintainer is the best way, as we're the ones > > that will be bothered if something goes wrong on the documentation > > (and code) that we maintain. > > Later if I have more time, may I will pick up those books who need > only small correction e.g. "debugobjects" .. but when the time comes > I will contact the maintainer and Jon' first. > > > In the specific case of media stuff, the first step is to get the > > flat-tree support and to put the migrated documentation on a separate > > directory. Unfortunately, I have two sets of topic branches for 4.8, > > and they both touch at the media docbook (and nothing prevents that > > similar things to happen on 4.9 or any other version). > > > > So, my plan is to keep both reST and docbook on Kernel for a while, > > until be sure that everything is properly migrated. > > > > Yet, I'm not sure if we should keep the migration scripts at the > > Kernel tree, or if the best is to keep them in separate, as I > > intend to not take more than one Kernel version to finish the > > conversion. At least for media docbook, this will be a one-time > > conversion. > > If I understood you right: the scripts, which are made the > migration itself should not committed to the kernel tree (IMHO). > Currently the scripts are available at my POC, may I could > separate them into a python package which could be installed > via python's pip. So if one wants to use this procedure of > migration, he could install the package locally, make the > conversion and after finishing, he uninstall the package. Sounds like a plan. > > > So, I really appreciate if you could send me the patches with > > the converted media documentation that you did. I'll merge it > > after Jonathan applies the flat-tree patch on his tree, and > > start reviewing and fixing the documentation over the main > > branch. > > Yes, first flat-table to Jon', then the converted media book > to Mauro, after this the man-page builder to Jon ... as long > as there are no man-pages in media it should be smoothly. OK. > But I need a bit time, hopefully, end next week you got the > media patch from me. Ok, but please notice that the end of the next week is probably too late for 4.8. Next week, we'll be on -rc6, and most maintainers freeze their trees during -rc7, except for bug fixes. Ok, as this is just documentation and should not cause regressions, I may open an exception, if it won't cause any troubles to Jon. > > -- Markus -- > > > I'll need to track the topic branch changes at the > > Docbook, to apply them again at the master tree, once they > > gets merged during the 4.8 window. Thankfully, there aren't > > complex elements on such changes (as far as I remember). > > > > If everything goes right, by -rc2 or -rc3 I'll likely be dropping > > the DocBook/media from my tree. > > > > -- > > Thanks, > > Mauro > -- Thanks, Mauro