[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart informa
From: |
John Snow |
Subject: |
Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information |
Date: |
Mon, 21 Sep 2015 15:23:46 -0400 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.2.0 |
On 09/17/2015 12:43 PM, Markus Armbruster wrote:
> "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.
>
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.
>
> [...]
>
- [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Daniel P. Berrange, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Peter Maydell, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Daniel P. Berrange, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Peter Maydell, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Daniel P. Berrange, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Peter Maydell, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Markus Armbruster, 2015/09/17
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information,
John Snow <=
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Markus Armbruster, 2015/09/22
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Paolo Bonzini, 2015/09/22
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Markus Armbruster, 2015/09/23
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Paolo Bonzini, 2015/09/23
- Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Daniel P. Berrange, 2015/09/23
Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, Paolo Bonzini, 2015/09/17
Re: [Qemu-devel] [PATCH] README: fill out some useful quickstart information, John Snow, 2015/09/21