Re: [PATCH 0/4] reST-directive kernel-cmd / include contentent from scripts

[Jonathan Corbet <corbet@lwn.net>]

On Tue, 11 Oct 2016 09:26:48 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

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

Sigh.

I've been shunting this discussion aside while I dug out from other
things.  Now I've pushed through the whole thing; I'm still not sure what
I think is the best thing to do.

kernel-cmd scares me.  It looks like the ioctl() of documentation
building; people will be able to add all kinds of wild things and it will
take a lot of attention to catch them.  I think we could make things
pretty messy in a real hurry.  And yes, I do think we should consider the
security aspects of it; we're talking about adding another shell
code-execution context in the kernel build, and that can only make things
harder to audit.

OTOH, forcing things into dedicated Sphinx extensions doesn't necessarily
fix the problem.  We're adding system calls rather than ioctl() commands,
let's say, but we're still adding long-term maintenance complications.

How many special-case commands are we going to need to run?  Does it
really need to go beyond what parse-headers is doing now?  Let's really
think about what the other use cases might be and whether we can do
without them. I'm still thoroughly unconvinced about the utility of
incorporating, say, the MAINTAINERS file into the formatted docs, for
example, so I'm not yet convinced that making that easier to do is
something we need.

Not much clarity here, sorry.

jon