From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
	id S932561AbcHIWxu (ORCPT <rfc822;w@1wt.eu>);
	Tue, 9 Aug 2016 18:53:50 -0400
Received: from tex.lwn.net ([70.33.254.29]:49217 "EHLO vena.lwn.net"
	rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP
	id S932461AbcHIWxp (ORCPT <rfc822;linux-kernel@vger.kernel.org>);
	Tue, 9 Aug 2016 18:53:45 -0400
Date: Tue, 9 Aug 2016 16:53:43 -0600
From: Jonathan Corbet <corbet@lwn.net>
To: Christoph Hellwig <hch@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>,
        Jani Nikula <jani.nikula@intel.com>, linux-doc@vger.kernel.org,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools
Message-ID: <20160809165343.400c3c5e@lwn.net>
In-Reply-To: <20160809083106.GA25504@infradead.org>
References: <20160808233502.16950-1-corbet@lwn.net>
	<20160808233502.16950-4-corbet@lwn.net>
	<20160809080736.GA15461@infradead.org>
	<87lh06xsk9.fsf@intel.com>
	<20160809082209.GA7553@infradead.org>
	<CAKMK7uHY_Af3rotw5a22zU_de6d7XEdU8jZWnJAMyFgO45f_1Q@mail.gmail.com>
	<20160809083106.GA25504@infradead.org>
Organization: LWN.net
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Tue, 9 Aug 2016 01:31:06 -0700
Christoph Hellwig <hch@infradead.org> wrote:

> On Tue, Aug 09, 2016 at 10:28:38AM +0200, Daniel Vetter wrote:
> > The point is to make the docs more discoverable by being able to
> > cross-link them. Old hats like us don't need that, but it definitely
> > has value in bringing new folks on board.  
> 
> But do that in a way that keeps the old hats happy.  The crazy use of
> punctuation and the weird quotes is an absolute no-go.

As others have noted, the long-term goal is to turn our disorganized
documentation hairball into something more approachable, maintainable, and
integrated; this is a step in that direction.

I take it you object to the ``literal quotes`` which render in a monospace
font?  That's the bulk of the changes there.  I can certainly take them
out if you really think "__bitwise" looks better than ``__bitwise``; it
will adversely affect the resulting pages, but so be it.

jon