From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751807AbcF3JAW (ORCPT ); Thu, 30 Jun 2016 05:00:22 -0400 Received: from smtp2.goneo.de ([85.220.129.33]:45522 "EHLO smtp2.goneo.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750937AbcF3JAP convert rfc822-to-8bit (ORCPT ); Thu, 30 Jun 2016 05:00:15 -0400 X-Spam-Flag: NO X-Spam-Score: -2.786 Content-Type: text/plain; charset=us-ascii Mime-Version: 1.0 (Mac OS X Mail 6.6 \(1510\)) Subject: Re: [GIT PULL] doc: sphinx-4.8 DocBook to reST movement on Jon's docs-next From: Markus Heiser In-Reply-To: <20160629115209.596ffd8b@lwn.net> Date: Thu, 30 Jun 2016 10:53:15 +0200 Cc: Mauro Carvalho Chehab , Dave Airlie , Jani Nikula , Grant Likely , Keith Packard , LKML Mailing List , "linux-doc@vger.kernel.org" , Hans Verkuil , Randy Dunlap Content-Transfer-Encoding: 8BIT Message-Id: References: <6A1AB08B-E585-42E2-A604-D5144A7BC6B4@darmarit.de> <20160629102426.08570878@lwn.net> <7B63766B-0F9E-417D-A101-13B9B092F64F@darmarit.de> <20160629115209.596ffd8b@lwn.net> To: Jonathan Corbet X-Mailer: Apple Mail (2.1510) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Jonathan, Am 29.06.2016 um 19:52 schrieb Jonathan Corbet : > On Wed, 29 Jun 2016 19:35:46 +0200 > Markus Heiser wrote: > >>> I would love it if you would take the flat-table and man-page work, >>> separate them out, and make them work with the *existing* Sphinx-based >>> scheme. If you can do it soon, we can maybe get it into 4.8. Can you >>> focus on that for now, please? >> >> Yes, I will send you flat-table request in the next days. > > I'm glad to hear that. One request: please post it as a patch, rather than > as a pull request; that makes it easier for everybody to review it. > >>> As for the rest, what we have now is certainly far from perfect; we're >>> figuring a lot of this out as we go. Incremental improvements are >>> welcome, and each will be evaluated independently. Please help us to >>> make the kernel's documentation better that way. >> >> I'am willing to do so, but I need some help / suggestions: >> >> 1. I have this extensions in the scripts/site-python/linuxdoc. >> What do you recommend, how could I split this up in a patch >> series which is more evaluated. >> >> .. I wrote to Jani, that my approach was chaotic in the past >> and I'am sorry for this. But now I'am sitting in front of this >> bulk of source and I'am bit helpless how to split ... I will >> try to make it more elaborate, but it will be helpfull if >> you point me the right direction ... > > Try to break it down as much as possible so that each patch represents a > single logical change. Each bit that you can break out reduces the problem > space a bit, and often helps with the rest. If possible, I'd like to > suggest starting with the man-page generation, since that's a hole in the > current system. I'll have to fill it if you don't :) Give me a bit time, I will do it. At first flat-table, then man-page. > Please note that I'd really like to see this stuff done without big changes > like the wholesale replacement of kernel-doc with a version in a different > language. Someday we might want to make a change like that, but one step > at a time. mmh, OK ... it will be "the long run" for me ... I will take it (again). The replacement makes many things much easier and has this big features; to parse only once (not on every kernel-doc directive / one error log, not n times same error messages) and a rich interface to control the reST output fine grained ( and Snippets, and a NullTranslator as a lint for free and .. and) ... it is a good working base ... no need for breadcrumbs or other tricky workarounds ... OK, I will start improving the perl script insofar it is needed (the reST out has to be more structural, you will see it / if it comes to the man-page builder) ... may be later I could persuade you, that it is a "dead end street" ... if the language python is the problem, I could maintain these modules (15 years practice). Regards --Markus-- >> 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. > > That said, if you're wanting to convert documents, there is a set of older > ones in the docbook directory that have no current maintainer and will > never move over on their own. kernel-hacking.tmpl is an obvious example. > The problem with these, of course, is that they are *way* out of date in > general, and really need attention beyond just a format conversion. I > won't say one has to happen before the other, but I am unsure that we will > really benefit from convert-and-forget-again efforts. > > Thanks, > > jon