Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

[Daniel Vetter]

On Tue, Aug 9, 2016 at 10:31 AM, Christoph Hellwig <hch@xxxxxxxxxxxxx> 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.

We've been bikeshedding on the exact kind of light markup since over a
year now. Current one is rst, with pretty much uniform support among
the folks who cared that it's the least offensive of the bunch. I
think it can be made slightly less invasive by trading in a bit of the
noise in the sourc for warnings from the html generators (and less
pretty html output), but that's pretty close to nothing already.

The only other option with less markup is markdown, but the only
reason it's less invasive is that I can't really do anything at all.
Definitely no sensible way to pull in things like kernel-doc or the
uapi headers media needs.

Jon, can you please try to respin the patch with fewer changes, but
(probably) more rst warnings?
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch