From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754741AbcFGLJz (ORCPT ); Tue, 7 Jun 2016 07:09:55 -0400 Received: from mga03.intel.com ([134.134.136.65]:20055 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753989AbcFGLJw (ORCPT ); Tue, 7 Jun 2016 07:09:52 -0400 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.26,432,1459839600"; d="scan'208";a="996875691" From: Jani Nikula To: Markus Heiser Cc: Daniel Vetter , Jonathan Corbet , Grant Likely , Mauro Carvalho Chehab , Keith Packard , Linux Kernel Mailing List , linux-doc@vger.kernel.org, Hans Verkuil Subject: Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation In-Reply-To: <6DDE872E-1D1E-434C-A618-A844875EB70F@darmarit.de> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <1465230745-31358-1-git-send-email-markus.heiser@darmarIT.de> <87wpm15q7q.fsf@intel.com> <6DDE872E-1D1E-434C-A618-A844875EB70F@darmarit.de> User-Agent: Notmuch/0.22+12~gbdd9442 (http://notmuchmail.org) Emacs/24.4.1 (x86_64-pc-linux-gnu) Date: Tue, 07 Jun 2016 14:09:48 +0300 Message-ID: <87oa7d5k77.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Tue, 07 Jun 2016, Markus Heiser wrote: > Am 07.06.2016 um 10:59 schrieb Jani Nikula : >> One of the key arguments against too much splitting that hasn't been >> mentioned is that despite all the fine output Sphinx can produce, we >> have plenty of people who couldn't care less about running Sphinx to get >> readable documentation. They will grep and read the plain text files >> directly, and that's a large part of the appeal of any lightweight >> markup. > > But they have read XML or compiled DocBook XML? ... Sphinx brings a > search engine with its html. > >> When you split up a file into snippets that no longer tell a coherent >> story independently, you've failed. > > Chapters are breaking stories? > >> For the .txt files under Documentation, we mostly do not want to split >> them up any more if and when they're converted to rst. For the .tmpl >> files under Documentation/DocBook, each rst file split off from there >> should still be a sensible document on its own, with the filename >> telling what it's about. This will be the main benefit of this whole >> exercise for the people who do not care about Sphinx - instead of >> reading (read: ignoring) DocBook XML, they can now read the rst files. > > Sorry but in IMO this suggestion is backward, if someone don't be able > to build HTML documents he should at least be able to use the > internet [1] :-o > > [1] http://return42.github.io/sphkerneldoc/articles/books.html I don't think you understand the target audience very well. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center