Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST markup

From: Peter Zijlstra
Date: Mon Nov 28 2016 - 06:54:34 EST


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