[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20161128134645.7jie7ph3kyxlsyvq@phenom.ffwll.local>
Date: Mon, 28 Nov 2016 14:46:45 +0100
From: Daniel Vetter <daniel@...ll.ch>
To: Peter Zijlstra <peterz@...radead.org>
Cc: Mauro Carvalho Chehab <mchehab@...pensource.com>,
Jonathan Corbet <corbet@....net>,
Silvio Fricke <silvio.fricke@...il.com>,
linux-doc@...r.kernel.org, Ming Lei <ming.lei@...onical.com>,
"Luis R . Rodriguez" <mcgrof@...nel.org>,
Mauro Carvalho Chehab <mchehab@...nel.org>,
linux-kernel@...r.kernel.org,
Jani Nikula <jani.nikula@...ux.intel.com>
Subject: Re: [PATCH v3 2/4] Documentation/atomic_ops.txt: convert to ReST
markup
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 <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.
"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
Powered by blists - more mailing lists