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: <4BD35C41-8A95-499A-8792-B1D5C0D59C38@darmarit.de>
Date:	Tue, 7 Jun 2016 17:13:13 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Jani Nikula <jani.nikula@...el.com>
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


Am 07.06.2016 um 13:09 schrieb Jani Nikula <jani.nikula@...el.com>:

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

May be, help me .. I can't see the use case ... is emac's incremental search
your use case? ... possibly we are talking past each other

* chunking is my recommendation on books, e.g. chapters is a good point 
  to split a book .. beside: books which make use of the kernel-doc directive
  are not *well grep-able* in their reST format ..

* not every .txt file should be chunked ... and folders with the 00-INDEX
  are already chunked.

The only thing I want to say is, that I recommend chunking, but 
at the end it should be an author decision, not a handicap of the 
build system.

-- Markus --

> 
> BR,
> Jani.
> 
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center