Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754261AbcK1LRK (ORCPT ); Mon, 28 Nov 2016 06:17:10 -0500 Received: from mga03.intel.com ([134.134.136.65]:46629 "EHLO mga03.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753716AbcK1LRB (ORCPT ); Mon, 28 Nov 2016 06:17:01 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.31,563,1473145200"; d="scan'208";a="791616160" From: Jani Nikula To: Peter Zijlstra , Jonathan Corbet , Silvio Fricke , linux-doc@vger.kernel.org, Ming Lei , "Luis R . Rodriguez" , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup In-Reply-To: <20161128102009.GV3092@twins.programming.kicks-ass.net> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20161125215814.GA3061@worktop.programming.kicks-ass.net> <20161127165914.5b84cc65@lwn.net> <20161128072626.GT3092@twins.programming.kicks-ass.net> <20161128084442.uqfcar5qx2b7u34v@phenom.ffwll.local> <20161128102009.GV3092@twins.programming.kicks-ass.net> Date: Mon, 28 Nov 2016 13:16:45 +0200 Message-ID: <87fumb26si.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 Content-Length: 1665 Lines: 45 On Mon, 28 Nov 2016, Peter Zijlstra wrote: > On Mon, Nov 28, 2016 at 09:44:42AM +0100, Daniel Vetter wrote: > >> > >> > Why change them? What was wrong with txt to begin with? >> >> In my opinion good docs matter, and one of the key things is to be able to >> cross reference stuff. > > Well, good docs begin with useful content; and many docs lack that. > Fixing that would be a much more useful thing to do. > > In any case, I've never had any problems with typing things like: "go > read: Documentation/file.txt for more information.". Using rst we can produce decent HTML pages, and make them available at [1], in context. You don't have to read that, but it will be a lot more discoverable for other people, another important quality of good documentation. And perhaps you don't have to tell people to go read it so much. [1] https://www.kernel.org/doc/html/latest/ > Very much agreed, once a file is no longer readable with less or the > text editor of your choice, it as good doesn't exist at all. So I very > much worry about RST even supporting such heavy markup that the end > result is unreadable. The goal is to have the best of both worlds, keeping it pretty much plain text, but adding just enough consistency in formatting that you can generate other formats out of it. We don't have to and we shouldn't go overboard with the markup. Arguably you could call rst a "coding style" for plain text. We have pretty uniform C code, I don't think it's unreasonable to have a little bit of consistency in the plain text. And really, it's not much we're asking. BR, Jani. -- Jani Nikula, Intel Open Source Technology Center