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

[Paolo Bonzini <pbonzini@redhat.com>]

On 01/02/2017 14:50, G 3 wrote:
> I was thinking maybe we should add Rich Text Format, or maybe even a
> word processing format like OpenOffice, or Microsoft Word to the list of
> possible formats. These formats are super easy to use. No formatting
> rules to have to learn. All the user needs to do is just type up their
> contribute to the documentation in a word processor. The word processor
> would do all the formatting work. Tables, links, stylized text are all
> possible. This would allow us to export to other formats like HTML, PDF,
> and ascii text.

That's exactly what we _don't_ want.

We need documentation to be consistent.  RTF, OpenOffice, etc. are
presentation-based format (or at least 99% users use them as such), and
this automatically disqualifies them.  We don't want our documentation
to be a mixture of Arial, Times New Roman and Comic Sans depending on
the user that's contributing.  Besides, conversion of word processor
documents to HTML usually looks terrible.

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

Paolo