On 09/17/2015 12:43 PM, Markus Armbruster wrote: > "Daniel P. Berrange" <berra...@redhat.com> writes: > >> On Thu, Sep 17, 2015 at 01:20:43PM +0100, Peter Maydell wrote: >>> On 17 September 2015 at 13:05, Daniel P. Berrange <berra...@redhat.com> >>> wrote: >>>> On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote: >>>>> On 17 September 2015 at 12:03, Daniel P. Berrange >>>>> <berra...@redhat.com> wrote: >>>> >>>>>> +Building >>>>>> +======== >>>>>> + >>>>>> +QEMU is multi-platform software intended to be buildable on >>>>>> all modern Linux >>>>>> +platforms, OS-X, Win32 (via the Mingw64 toolchain) and a >>>>>> variety of other >>>>>> +UNIX targets. The simple process to build QEMU is >>>>> >>>>> This whole section seems to be duplicating our existing build >>>>> documentation (which is in qemu-doc.texi in the 'compilation' >>>>> section). We should document how to build QEMU in exactly one >>>>> place, not two (though I can see the rationale for that one >>>>> place not being in a .texi file.) >>>> >>>> The problem I have with refering people to qemu-doc.html, >>>> is that in order to order to view the docs on how to build >>>> QEMU, you first have to build QEMU, or enjoy reading the >>>> .texi source code :-) Though that doc does get exposed >>>> via the website too, it is nice to not rely on people having >>>> internet access all the time. >>>> >>>> The qemu-doc.html chapter 6 is a bit more detailed in what >>>> it descibes. I tend to view the instructions we put in the >>>> README file as the minimal quick-start, and then point to >>>> the comprehensive docs as a detailed reference on the matter. >>> >>> I don't think we should have two places at all. If a "quick >>> start" is useful it should be at the start of the one document >>> we have on building QEMU. >> >> How about splitting "Chapter 6 Compilation" out of the qemu-doc.texi >> file into a standalone file, in a format that is friendly to read >> without needing generating first. > > Do we want a "Compilation" chapter in qemu-doc, or do we want it to be a > separate document? "Both" is a legitimate answer. Multiple documents > can be generated from a single source. > > Must the separate document be available right after unpacking a tarball? > "Yes" doesn't mean we can't generate it --- projects include generated > files in tarballs all the time, e.g. Autoconf-generated configure. > > Must the separate document be available right after git-clone? "Yes" > doesn't mean we can't generate it, only that we have to commit a > generated file, which is a bit awkward. > > Personally, I wouldn't bother. People capable of git-clone are capable > of finding and running a bootstrap script. Common with projects using > Autoconf that don't commit the generated configure. >
OK, but I'd spell it out: "To build QEMU, you'd generally [some basic steps that have generally worked for a long time], but for up-to-date authoritative information, please do: mkdir path_to/build_dir cd path_to/build_dir ../../configure make qemu-doc.html" We wind up documenting how to almost do a build anyway. So I think we'd need to make the qemu-doc file one we can generate without needing to get through the sometimes-arduous configure step first. Or at least, split out the build information into something that can be generated in a standalone fashion. My personal preference is, like in my above example, to give a brief "Here's what usually works" blurb as a quick-start that will hopefully work for most people, followed by a link to a more authoritative document that takes more mental energy to parse (or even to conjure into existence) than the quick blurb. At this point though, we're already being a huge pain in the ass. I'm in favor of a statically available "Here's how to build" that we don't need to generate, but I won't insist on it if there are some strong reasons that we need to auto-generate simple build information. --js >> Perhaps using something like >> Markdown[1] would be a suitable thing, as that is essentially plain >> text with a little extra punctuation, so it is easily readable as >> source, as well as allowing reasonably pleasant HTML generation >> allowing us to publish it to the website too ? > > Texinfo isn't exactly the greatest markup system, but it works, and it > can generate reasonably pleasant HTML. Ditto PDF and plain text. > > Why not extract the existing chapter into a separate .texi, include it > from the user manual, include it from a trivial .texi master file, > format the latter to plain text with something like > > $ texi2any --plaintext -I . how-to-build.texi >HOW-TO-BUILD > > No need for redoing the markup. > > [...] >
