Re: sequence diagrams in rst documentation

[Johannes Berg <johannes@sipsolutions.net>]

On Tue, 2016-10-18 at 15:51 +0200, Markus Heiser wrote:
> Here are my thoughts ...
> 
> Every extension which is not a part of the sphinx distro brings new
> external dependencies 

I agree.

> and the development of such extensions is IMO
> far of kernel development's scope.

Arguably, having good documentation *is* in the scope of kernel
development.

Also, it could be argued that shipping a module in the kernel sources
would be more reliable than having to require it being externally
installed, like the GCC plugins perhaps.

> ATM, there are not many use cases for diagram generators, so why not
> be KISS and creating diagrams with the favorite tool only adding the
> resulting (e.g.) PNG to the Kernel's source?

*Only* adding the PNG would be awful, I'd have to keep track of the
corresponding source elsewhere, and perhaps couldn't even GPL it
because then I couldn't distribute the PNG without corresponding
source...

Adding the source text would really be the only practical choice, but
doing so makes it easy to mismatch things, and also very easy to use
proprietary services for it that may go away at any time, etc.

> Before we add new dependencies / complexity, we should get rid
> of the DocBook build.

That argument is ... completely bogus, politely said.

I'm not going to (be able to) do anything about all the docbooks that
exist, and have in fact converted the one docbook that I know anything
about. Holding back the development of documentation in one subsystem
because another subsystem hasn't converted is a garbage argument.

johannes