From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1755219AbcIUApB (ORCPT ); Tue, 20 Sep 2016 20:45:01 -0400 Received: from tex.lwn.net ([70.33.254.29]:40753 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754971AbcIUAo6 (ORCPT ); Tue, 20 Sep 2016 20:44:58 -0400 Date: Tue, 20 Sep 2016 18:44:54 -0600 From: Jonathan Corbet To: Mauro Carvalho Chehab Cc: Linux Doc Mailing List , Mauro Carvalho Chehab , Markus Heiser , Jani Nikula , LKML , Greg KH Subject: Re: [PATCH v4 00/29] Create a book for Kernel development Message-ID: <20160920184454.0b5ae2a0@lwn.net> In-Reply-To: References: Organization: LWN.net X-Mailer: Claws Mail 3.13.2 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Mon, 19 Sep 2016 08:07:34 -0300 Mauro Carvalho Chehab wrote: > That's the 4th version of this series. It also contains a second patch series > with more ReST conversions and documentation improvements. > This patchset merges the content of a second patch series: > > [PATCH 00/17] Improve documentation for the development-process > OK, I'm applying these through 28; I'm going to hold off on #29. Thanks for separating that part out so nicely. > I opted to keep the patch changing the kernel-docs.txt changes > (patch 21/29). The patch is already written and another patch > (patch 22/29) depends on it, because there are references to > this file at Documentation/HOWTO. > > It shouldn't be hard to get rid of it, but I'm not sure if worths > the effort. As I commented, people might find useful to update > it to point to more modern documents. If people won't do it, > it can still be removed from the Kernel a the next Kernel version. I'll take them for now, since there seems to be interest in doing something with this document. I kept the applying-patches one as well. But I do think that we need to start being a bit more willing to get rid of musty old docs. We don't carry unused code because "it might be useful to somebody"; I think we should take the same approach to docs. Out-of-date or irrelevant docs are a maintenance burden, and they impose a heavy burden on the people the docs are most meant to help... A few notes: #1 didn't apply, I had to do it by hand. I suspect my late application of Marcus's work got in the way there. #2 had this: > Content-Type: text/plain; charset=true ...which threw git am for a loop; I had to fix it manually. What gives there? #4 didn't apply and had to be done by hand. #10 (CodingStyle) has a lot of ".. code-block:: c" constructs. Why are those needed? We're still using C by default for literal blocks, right? #15 (SecurityBugs) leaves the section numbers in place; did you intend that? #21 (kernel-docs.txt) had the charset=true weirdness #28 actually, I balked at applying this one, since it assumes that the great renaming is taking place, and that hasn't happened yet. So actually I only went through #27, but that took a long time - seemingly longer than it takes you to create them! :) A few of the patches still have the bare "::" lines in them; I think I'll just add a patch to fix those up real quick. Thanks, jon