Re: Kernel docs: muddying the waters a bit

[Mauro Carvalho Chehab]

Em Thu, 5 May 2016 07:02:10 -0600
Jonathan Corbet <corbet@xxxxxxx> escreveu:

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

Yeah, if we take the big picture, I'm pretty sure that there are more
stuff written using kerneldoc. However, what is written at the 
kerneldoc comments don't use DocBook markup, but its own markup
language.

Assuming that we'll keep using kerneldoc script to convert from the
Kerneldoc NANO markup, it means that any changes at the kerneldoc
backend to use DocBook/Markdown/asciidoc/reST/... won't change anything
for the developers nor will require them to actually use the new markups.
So, they can gradually start using new markups as they wish/learn, if
they want to improve the documentation. Lazy developers could just ignore
reST if they want, as everything will work as before.

However, for the files written directly in DocBook, there's no option:
at the moment the doc is converted, the developer will need to submit
patches using the new markup language. So, we need to be sure that
such transition will happen in a way that won't cause more harm than
needed.  I would prefer to convert all of them at one, on a single Kernel
release (or two), in order to minimize the impact for the developers.

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

Yeah, I understand.

Regards,
Mauro