Date: Mon, 28 Nov 2016 12:54:13 +0100
From: Peter Zijlstra <peterz@infradead.org>
To: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
        Silvio Fricke <silvio.fricke@gmail.com>, linux-doc@vger.kernel.org,
        Ming Lei <ming.lei@canonical.com>,
        "Luis R . Rodriguez" <mcgrof@kernel.org>,
        Mauro Carvalho Chehab <mchehab@kernel.org>,
        linux-kernel@vger.kernel.org,
        Jani Nikula <jani.nikula@linux.intel.com>
Subject: Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST
 markup
Message-ID: <20161128115413.GW3092@twins.programming.kicks-ass.net>
References: <cover.9b80912a8cfb55dfb55d1434ab1811fa5211eb9c.1480085951.git-series.silvio.fricke@gmail.com>
 <e955eb19b9742fa8f92b42d35fdaf3332ae08826.1480085951.git-series.silvio.fricke@gmail.com>
 <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>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20161128090855.589f9357@vento.lan>
User-Agent: Mutt/1.5.23.1 (2014-03-12)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1306
Lines: 35

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_


> 	:ref:`Documentation/admin-guide/serial-console.rst <serial_console>`

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.

> - 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 ^].