From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751695AbcF2U6o (ORCPT ); Wed, 29 Jun 2016 16:58:44 -0400 Received: from lists.s-osg.org ([54.187.51.154]:60145 "EHLO lists.s-osg.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751376AbcF2U6m (ORCPT ); Wed, 29 Jun 2016 16:58:42 -0400 Date: Wed, 29 Jun 2016 17:57:45 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet Cc: Markus Heiser , 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: <20160629175745.554c93a9@recife.lan> In-Reply-To: <20160629115209.596ffd8b@lwn.net> References: <6A1AB08B-E585-42E2-A604-D5144A7BC6B4@darmarit.de> <20160629102426.08570878@lwn.net> <7B63766B-0F9E-417D-A101-13B9B092F64F@darmarit.de> <20160629115209.596ffd8b@lwn.net> 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 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. 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. 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. 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