Re: Kernel docs: muddying the waters a bit

From: Jonathan Corbet
Date: Thu May 05 2016 - 09:02:23 EST

On Wed, 4 May 2016 14:57:38 -0300
Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx> wrote:

> Also, media documentation is not just one more documentation. It is
> the biggest one we have, and that has more changes than any other
> documentation under Documentation/DocBook:
> $ git lg --since 01/01/2015 ` ls *.tmpl|grep -v media`|wc -l
> 116
> $ git lg --since 01/01/2015 ` ls *.tmpl|grep media` `find media/ -type f`|wc -l
> 179
> It also is more than twice the size of the other DocBook docs:
> $ wc -l $(ls *.tmpl|grep media) `find media/ -type f`|tail -1
> 82275 total
> $ wc -l $(ls *.tmpl|grep -v media)|tail -1
> 29568 total
> E. g. media corresponds to 60% of the number of patches and 73% of
> the DocBook stuff.

These numbers are not entirely representative, I have to say. You're
ignoring the kerneldoc comments - which is what much of the "DocBook"
documents are made of, and which is the focus of much of this activity. If
you could find a way to count those, you'd get a different picture.

But I don't think that really matters; there doesn't seem to be *that* much
disagreement here.

The media book is important; we want it to be a part of the overall kernel
documentation suite and not stuck in some DocBook ghetto. I agree that we
should have an idea for a plausible path for *all* of our documentation.
But I'm also concerned about delaying this work yet again; we have
developers trying to push forward with improved documentation, and they've
had to wait a year for this stuff - so far.