Re: [Qemu-devel] Qemu-devel] Poll on QEMU documentation project

[Paolo Bonzini <pbonzini@redhat.com>]

On 01/02/2017 15:36, G 3 wrote:
> On Feb 1, 2017, at 6:17 PM, Paolo Bonzini wrote:
>> The requirements for the format are:
>>
>> * support for HTML and man as output formats, optionally PDF and text
>> * support for QEMU's usual submission workflow
>> * producing documentation with a consistent look
>> * tool support and extensibility
>> * being easy to use and not too obscure
>>
>> in this order.  Based on this, the only formats we could plausibly use
>> are Texinfo (if only because that's what we use now), Markdown,
>> restructuredText, Docbook and Asciidoc.  The poll mentioned all of these
>> except Asciidoc, plus LaTeX as a "control group".
> 
> Ok. I understand.
> 
> For the above requirements of "tool support and extensibility", what do
> you mean by this? Do you mean command-line tool support? What do you
> mean by extensibility?

Basically, easily integrating QEMU-specific code in the build.  This
way, we don't need 20 different steps in the Makefile; instead a single
tool invocation will do everything from parsing the input, to extracting
documentation comments from C source, to finally generating the output.

Of course you need to find the right balance between redoing the same
work over and over (a solution purely based on Make can do that best)
and ease of use.

Paolo