Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

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.

Thanks,

jon