Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932970AbcK1Nqz (ORCPT ); Mon, 28 Nov 2016 08:46:55 -0500 Received: from mail-wj0-f196.google.com ([209.85.210.196]:33586 "EHLO mail-wj0-f196.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932253AbcK1Nqp (ORCPT ); Mon, 28 Nov 2016 08:46:45 -0500 Date: Mon, 28 Nov 2016 14:46:45 +0100 From: Daniel Vetter To: Peter Zijlstra Cc: Mauro Carvalho Chehab , 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: <20161128134645.7jie7ph3kyxlsyvq@phenom.ffwll.local> Mail-Followup-To: Peter Zijlstra , Mauro Carvalho Chehab , 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> <20161128090855.589f9357@vento.lan> <20161128115413.GW3092@twins.programming.kicks-ass.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20161128115413.GW3092@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: 2171 Lines: 53 On Mon, Nov 28, 2016 at 12:54:13PM +0100, Peter Zijlstra wrote: > On Mon, Nov 28, 2016 at 09:08:55AM -0200, Mauro Carvalho Chehab wrote: > > - use *foo* (for italics) or **foo** (for bold) instead of _foo_; > > That's daft, and also you're wrong. The normal convention is: > > /italic/ > *bold* > _underlined_ I dont think anything is lost if we don't use the rst flavour but keep the traditional one. The html output meant for newbies looks a bit more funny, but if that means the old guard is more likely to type the docs then that's more than worth it. > > :ref:`Documentation/admin-guide/serial-console.rst ` > > That seems to work, as in 'gf' doesn't get confused by the spurious > characters attached. Is there any way to enforce that? > > > - if you have something that you want to use a monotonic font on > > PDF/LaTeX/HTML, use ``foo``. > > Bit weird, somewhere in the typewriter age they invented the " symbol so > we didn't have to type double quotes anymore. "Quote" just gives you a quote, not fixed-width. The `` noise is what upset Christoph, and I think it's perfectly fine to not use them. > > - if you use special characters like '*' in the middle of the text > > (outsize a literal block), prepend with a \ in order to escape > > parsing it. > > That's a bit inconvenient I suppose. > > > Btw, a lot of editors recognize ReST files and are capable of > > parsing the ReST tags while displaying the file, including vim > > and emacs, using different colors and/or bold to display those tags. > > So, even for text-editing, converting to ReST brings improvements. > > Doesn't seem to really work though; if I open > Documentation/development-process/1.Intro.rst the :ref:s at the start of > the document don't work with the regular 'follow-ref' key combo of ^]. For that we need to integrate some rst/sphinx ctags generator into the kernel's ctags target. Not sure we want to do that (it might upset people who want to follow to a C symbol with clashing naming), at least not by default. But if this desired we can make it happen. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch