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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAKMK7uHR71eswoTNYZMPrD8Mk67qzTmqe2Mr5ai6HN62hoKp_A@mail.gmail.com>
Date:	Tue, 9 Aug 2016 12:00:58 +0200
From:	Daniel Vetter <daniel.vetter@...ll.ch>
To:	Christoph Hellwig <hch@...radead.org>
Cc:	Jani Nikula <jani.nikula@...el.com>,
	Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org,
	Linux Kernel Mailing List <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH 03/10] docs: sphinxify sparse.txt and move to dev-tools

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

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