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