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

[Peter Maydell]

On 27 January 2017 at 06:51, Markus Armbruster <address@hidden> wrote:
> "What can we cut" is the wrong question.  The right one is "what are our
> requirements".  Here's my try:
>
> HTML: required
> nroff with an macros: required
> PDF: wanted (try printing a website)
> plain text: nice to have (for me personally, more than that)
> info: nice to have
>
> If a solution we like can't provide something that's nice to have, we
> can decide to take it anyway.
>
> If a solution we like can provide something that's nice to have, we
> should let it provide, unless it turns out to be a drag.

Well, every extra documentation format:
 * increases the build time
 * increases the chances of makefile bugs
 * may require extra tooling to produce
 * either requires us to check it for problems or increases
   the chance of confusing users because that output format
   has a formatting problem that doesn't happen in the doc
   formats most people use
 * may require significant extra work to produce something
   that's actually useful: a manpage and an info doc aren't
   just the same content in a different file format, they
   should have definitely different contents and structure
   to fit what people expect a manpage or an info doc to be

So my list is:
 * HTML: required
 * PDF: nice-to-have

thanks
-- PMM