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

[Jani Nikula <jani.nikula@intel.com>]

On Tue, 07 Jun 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 07.06.2016 um 10:59 schrieb Jani Nikula <jani.nikula@intel.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