Am 07.10.2016 um 07:56 schrieb Jani Nikula <>:

> On Thu, 06 Oct 2016, Mauro Carvalho Chehab <> wrote:
>> Em Thu, 06 Oct 2016 17:21:36 +0300
>> Jani Nikula <> 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 <>:

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

But, let's hear what Jon says.

-- Markus --

To unsubscribe from this list: send the line "unsubscribe linux-media" in
the body of a message to
More majordomo info at

Reply via email to