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

[Stefan Hajnoczi]

On Fri, Jan 27, 2017 at 10:08:49AM +0000, Peter Maydell wrote:
> 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

We also need to produce man pages for the command-line tools.

Stefan

signature.asc
Description: PGP signature