Am 07.06.2016 um 13:09 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > On Tue, 07 Jun 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: >> Am 07.06.2016 um 10:59 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: >>> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
