On 08/15/2015 06:27 AM, Jonathan Corbet wrote: > On Fri, 14 Aug 2015 15:46:52 -0700 > Tim Bird <tim.bird@xxxxxxxxxxxxxx> wrote: > >>> It sure would be nice if changes like this were accompanied by a patch >>> fixing the additional warnings it drags in ... :) In this case I've put >>> something together for workqueue.h and will send it off shortly. >> >> My apologies. > > Sorry, hope I didn't sound grumpier than I really was. As you note, the > docs builds are a morass of warnings; it would be nice to avoid making it > worse when possible. Especially warnings that actually mean something - > like the docbook comments being wrong. It was easily fixed, anyway, no > worries. You didn't sound grumpy, but I probably came off as overly sensitive. I was embarrassed to have missed the warnings. I would like to lend a hand to clean up the warnings. And I'm interested in following up on the discussion from the ksummit list, about a possible conversion to markdown or asciidoc. I started experimenting with this by converting one of the text files in Documentation to both markdown and asciidoc, to see: 1) what additional tools needed to be installed, if any, 2) what it took to convert from plain text to the different markup languages, and 3) and what the resulting output looked like. However, I didn't quite finish. If this gets on the agenda for the kernel summit, then I'll definitely finish up this work (and maybe try it on some other files), so that there's a data point for discussing a conversion from DocBook to something else. I had the idea of maybe just doing something for the API docs completely in parallel, as a test, to determine the difficulty of conversion. But it probably would turn into one of those 80/80 things. (The first 80 percent of the project takes 80 percent of the time, and the last 20 percent takes the other 80 percent. :-) -- Tim -- 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
