Am 07.10.2016 um 07:56 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > On Thu, 06 Oct 2016, Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> wrote: >> Em Thu, 06 Oct 2016 17:21:36 +0300 >> Jani Nikula <jani.nikula@xxxxxxxxx> escreveu: >>> We've seen what happens when we make it easy to add random scripts to >>> build documentation. We've worked hard to get rid of that. In my books, >>> one of the bigger points in favor of Sphinx over AsciiDoc(tor) was >>> getting rid of all the hacks required in the build. Things that broke in >>> subtle ways. >> >> I really can't see what scripts it get rids. > > Really? You don't see why the DocBook build was so fragile and difficult > to maintain? That scares me a bit, because then you will not have > learned why we should at all costs avoid adding random scripts to > produce documentation. For me, disassembling the DocBok build was hard and bothersome, I don't want this back. IMO: old hats are productive with perl and they won't adapt another interpreter language (like python) for scripting. This series -- the kernel-cmd -- directive avoid that they build fragile and difficult to maintain Makefile constructs, calling their perl scripts. Am 06.10.2016 um 16:21 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > This is connected to the above: keeping documentation buildable with > sphinx-build directly will force you to avoid the Makefile hacks. Thats why I think, that the kernel-cmd directive is a more *straight- forward* solution, helps to **avoid** complexity while not everyone has to script in python ... > Case in point, parse-headers.pl was added for a specific need of media > documentation, and for the life of me I can't figure out by reading the > script what good, if any, it would be for gpu documentation. I call > *that* unmaintainable. If one adds a script like parse-headers.pl to the Documentation/sphinx folder, he/she also has to add a documentation to the kernel-documentation.rst If the kernel-cmd directive gets acked, I will add a description to kernel-documentation.rst and I request Mauro to document the parse-headers.pl also. But, let's hear what Jon says. -- Markus -- -- 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
