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