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
