Re: [PATCH] doc: Add more workqueue functions to the documentation

[Tim Bird <tim.bird@sonymobile.com>]

On 08/15/2015 06:27 AM, Jonathan Corbet wrote:
> On Fri, 14 Aug 2015 15:46:52 -0700
> Tim Bird <tim.bird@sonymobile.com> 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