linux-kernel - Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <87oa7d5k77.fsf@intel.com>
Date:	Tue, 07 Jun 2016 14:09:48 +0300
From:	Jani Nikula <jani.nikula@...el.com>
To:	Markus Heiser <markus.heiser@...marit.de>
Cc:	Daniel Vetter <daniel.vetter@...ll.ch>,
	Jonathan Corbet <corbet@....net>,
	Grant Likely <grant.likely@...retlab.ca>,
	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Keith Packard <keithp@...thp.com>,
	Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	linux-doc@...r.kernel.org, Hans Verkuil <hverkuil@...all.nl>
Subject: Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

On Tue, 07 Jun 2016, Markus Heiser <markus.heiser@...marit.de> wrote:
> Am 07.06.2016 um 10:59 schrieb Jani Nikula <jani.nikula@...el.com>:
>> One of the key arguments against too much splitting that hasn't been
>> mentioned is that despite all the fine output Sphinx can produce, we
>> have plenty of people who couldn't care less about running Sphinx to get
>> readable documentation. They will grep and read the plain text files
>> directly, and that's a large part of the appeal of any lightweight
>> markup.
>
> But they have read XML or compiled DocBook XML? ... Sphinx brings a
> search engine with its html.
>
>> When you split up a file into snippets that no longer tell a coherent
>> story independently, you've failed.
>
> Chapters are breaking stories?
>
>> For the .txt files under Documentation, we mostly do not want to split
>> them up any more if and when they're converted to rst. For the .tmpl
>> files under Documentation/DocBook, each rst file split off from there
>> should still be a sensible document on its own, with the filename
>> telling what it's about. This will be the main benefit of this whole
>> exercise for the people who do not care about Sphinx - instead of
>> reading (read: ignoring) DocBook XML, they can now read the rst files.
>
> Sorry but in IMO this suggestion is backward, if someone don't be able
> to build HTML documents he should at least be able to use the
> internet [1] :-o
>
> [1] http://return42.github.io/sphkerneldoc/articles/books.html

I don't think you understand the target audience very well.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center