"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.
> 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.
[...]
