Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information

[Markus Armbruster]

"Daniel P. Berrange" <address@hidden> writes:

> On Thu, Sep 17, 2015 at 01:20:43PM +0100, Peter Maydell wrote:
>> On 17 September 2015 at 13:05, Daniel P. Berrange <address@hidden> wrote:
>> > On Thu, Sep 17, 2015 at 12:32:56PM +0100, Peter Maydell wrote:
>> >> On 17 September 2015 at 12:03, Daniel P. Berrange
>> >> <address@hidden> 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.

[...]