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

[John Snow <jsnow@redhat.com>]

On 09/17/2015 12:43 PM, Markus Armbruster wrote:
> "Daniel P. Berrange" <berrange@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 <berrange@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
>>>>> <berrange@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.
> 
> [...]
>