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

[Markus Armbruster]

Stefan Hajnoczi <address@hidden> writes:

> 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

Yes.  The increase can range from "lost in the noise" through "painful"
to "prohibitive".  The more pain, the more gain we need to show to
justify.

Right now, documentation formatting is a drop in the compilation time
bucket.

>>  * increases the chances of makefile bugs

Yes.  Those can be a pain to debug, such as when you don't realize it's
a Makefile bug (instead of say a long-obsolete version of a tool playing
tricks on you on a platform you can't access).

Fortunately, such bugs get created mostly when we're messing with the
doc toolchain, which should be rare.

Right now, documentation formatting is a drop in the Makefile complexity
bucket.

>>  * may require extra tooling to produce

Again, the more pain, the more gain we need to show.

Right now, our build requirements for documentation are a drop in the
build requirements bucket on Linux.  Can't judge other hosts.

>>  * 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

Yes, formatting issues specific to the output format are possible.
Probably more likely when producing it involves options or tools that
aren't in common 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

Yes, but isn't that a solved problem for us?

Any proposal that "unsolves" it needs to justify the pain by showing
commensurate gain.

>> So my list is:
>>  * HTML: required
>>  * PDF: nice-to-have
>
> We also need to produce man pages for the command-line tools.

That's what I meant by "nroff with an macros".  Hard requirement.