Stefan Hajnoczi <stefa...@gmail.com> writes: > On Fri, Jan 27, 2017 at 10:08:49AM +0000, Peter Maydell wrote: >> On 27 January 2017 at 06:51, Markus Armbruster <arm...@redhat.com> 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.
