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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
