Date: Mon, 28 Nov 2016 13:14:46 -0200
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Daniel Vetter <daniel@ffwll.ch>
Cc: Peter Zijlstra <peterz@infradead.org>,
        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: <20161128131446.5e00d478@vento.lan>
In-Reply-To: <20161128134645.7jie7ph3kyxlsyvq@phenom.ffwll.local>
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>
        <20161128115413.GW3092@twins.programming.kicks-ass.net>
        <20161128134645.7jie7ph3kyxlsyvq@phenom.ffwll.local>
Organization: Samsung
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 1752
Lines: 44

Em Mon, 28 Nov 2016 14:46:45 +0100
Daniel Vetter <daniel@ffwll.ch> escreveu:

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

Yep. Maybe we could later add a Sphinx extension that would add support
for /italic/ and _underlined_ traditional convention. IMHO, it was a
bad decision from Sphinx developers to not support underlined texts.

> 
> > > 	: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.

``fixed-width`` is worse than "fixed-width", but on the other hand
it won't require to add escape codes for " character, if used on
some context where fixed width fonts is not required. So, at least for
me, ``fixed-width`` is acceptable.

Regards,
Mauro