Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932901AbcK1ONX (ORCPT ); Mon, 28 Nov 2016 09:13:23 -0500 Received: from mail-wj0-f193.google.com ([209.85.210.193]:35686 "EHLO mail-wj0-f193.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932745AbcK1ONN (ORCPT ); Mon, 28 Nov 2016 09:13:13 -0500 Date: Mon, 28 Nov 2016 15:13:14 +0100 From: Daniel Vetter To: Peter Zijlstra Cc: Jonathan Corbet , Silvio Fricke , linux-doc@vger.kernel.org, Ming Lei , "Luis R . Rodriguez" , Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jani Nikula Subject: Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup Message-ID: <20161128141314.o6favw3o6eo3weww@phenom.ffwll.local> Mail-Followup-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, Jani Nikula 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> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20161128102009.GV3092@twins.programming.kicks-ass.net> X-Operating-System: Linux phenom 4.8.0-1-amd64 User-Agent: NeoMutt/20161104 (1.7.1) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 3273 Lines: 70 Hi Peter, On Mon, Nov 28, 2016 at 11:20:09AM +0100, 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. Fully agreed, pretty looking docs that don't exist aren't useful at all ;-) Personally I'm pretty happy with typing .rst plain-text, since I mostly ignore all the fancy stuff. Using .rst has also made the in-source kerneldoc a lot more useful, e.g. vtables can now be documented in a reasonable manner and the generated output still looks decent. For an example see include/drm/drm_modeset_helper_vtables.h. > In any case, I've never had any problems with typing things like: "go > read: Documentation/file.txt for more information.". > > Also, what text editor supports cross references at all then? With the > filename I can use 'gf' in vim to open it up in a new buffer and go read > that. Yeah agreed, anything that requires more work for typing docs isn't really useful. The nice thing about the kernel's sphinx toolchain is that a big pile of these references (not all of them yet) are autogenerated. That is of course of 0 use for old hats like us who just browse it all using vim and gf and ^] and all maybe a quickfix list of hits. But in my experience having something pretty to click around in is rather useful for newbies. At least that's been my experience with the drm docs, I have much less to explain on mails and chat since we've started with this all. And excessive amounts of cross-references seem to help a lot in guiding the blind ;-) Anyway, my goal at least is to keep all the plain-text usage perfectly fine, while giving newbies something pretty in there browsers. > > Another concern some core kernel folks raised is that the .rst markup was > > too heavy-handed, and makes the text much harder to read. Christoph called > > it "cat spew". That can be fixed with a much lighter-handed conversion > > (and 2nd patch iteration was acceptable for Christoph). > > 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. > > Basically, if a file isn't usable from within a 'normal' text editor, it > doesn't exist. Yup agreed. Personally I prefer a _much_ more light-handed appraoch with rst markup. Essentially none, except the few things needed to glue all the various docs into a somewhat coherent whole. And I think that's also more-or-less the consensus among many core kernel hackers. Jon, should we document that we want a very light-handed approach to rst markup in kernel docs? This has come up a few times now, and irrespective of what exactly we're going to do with atomic_ops.txt I think it would help with making txt->rst conversions palatable to the core kernel community. And it's knida my own preference too ... Thanks, Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch