From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:51920) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X094H-0006Aa-Rc for qemu-devel@nongnu.org; Thu, 26 Jun 2014 08:46:29 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1X094B-0006H7-Jh for qemu-devel@nongnu.org; Thu, 26 Jun 2014 08:46:21 -0400 Received: from mx1.redhat.com ([209.132.183.28]:37194) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1X094B-0006Gr-Bo for qemu-devel@nongnu.org; Thu, 26 Jun 2014 08:46:15 -0400 Date: Thu, 26 Jun 2014 08:46:11 -0400 From: Luiz Capitulino Message-ID: <20140626084611.20f771a2@redhat.com> In-Reply-To: <53AB2D71.7050704@redhat.com> References: <4b996aea34144d33f2227835dc3d064818ffb7be.1403688576.git.mprivozn@redhat.com> <53AAD523.3000604@redhat.com> <20140625155048.252833c1@redhat.com> <53AB2D71.7050704@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Eric Blake Cc: Michal Privoznik , famz@redhat.com, qemu-devel@nongnu.org, Wenchao Xia , pbonzini@redhat.com On Wed, 25 Jun 2014 14:13:37 -0600 Eric Blake wrote: > On 06/25/2014 01:50 PM, Luiz Capitulino wrote: > > >> Then again, qmp-commands.txt is generated from qmp-commands.hx, which > >> duplicates information already in qapi-schema.json (and friends, now). > >> Would it be better to just install the .json files? Is it time to > >> finally bite the bullet and figure out how to get rid of duplication by > >> dropping qmp-commands.hx, and instead listing example usage directly in > >> the qapi-schema.json file? I'm not sure if we have a good plan in place > >> for user-facing documentation, even if the move to events-as-QAPI was > >> desirable. > > > > My original plan was to generate qmp-commands.txt & qmp-evets.txt from > > the schema file(s). I'm not sure if the .json files are consumable to > > non-qemu/libvirt developers. If you think they are then I'd be fine with > > installing them. > > The .json files are what _I_ refer to (but I'm probably biased, since > I've become a vested partner in the json files in the meantime); for > someone encountering the docs with no prior experience, I'm not sure how > much value-added the qmp-commands.txt was providing. > > > > > Wrt the examples, my only concern about having them in the schema is > > that the examples are in QMP format but in the past we were also planning > > on having C support via libqmp. If what we have today is what matters, > > then we can just move the examples to the schema files. > > Putting the examples in the .json files also comes with its own > interesting issues - do you prefix every line with # comment markers (so > the examples are no longer copy-paste, but now copy-paste-modify)? Or do > we do it as top-level JSON elements, perhaps via a new item that the > generators ignore but which a doc conversion tool could consume? Maybe: > { 'example': { > 'client': > {"command": {"foo", "arguments": { "hello": "world" } } }, > 'server': > {"reply": {} } > } } > > Michal's hack at least ensures that we have event documentation, even if > the format changed compared to the 2.0 docs, and even if we don't have > time to get something better in place before 2.1 goes out. So all of > this conversation on ways to do better is nice, but if we don't get > there quickly, I could at least live with Michal's patch in the short term. I honestly don't know what's the best thing to do here. I can live with this patch too, although having some introductory comments at the top of the file saying what it is would be nicer.