From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:46868) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WztZn-0006Iu-3K for qemu-devel@nongnu.org; Wed, 25 Jun 2014 16:13:56 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WztZd-0005Ac-NN for qemu-devel@nongnu.org; Wed, 25 Jun 2014 16:13:51 -0400 Received: from mx1.redhat.com ([209.132.183.28]:12635) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WztZd-0005AP-Ei for qemu-devel@nongnu.org; Wed, 25 Jun 2014 16:13:41 -0400 Message-ID: <53AB2D71.7050704@redhat.com> Date: Wed, 25 Jun 2014 14:13:37 -0600 From: Eric Blake MIME-Version: 1.0 References: <4b996aea34144d33f2227835dc3d064818ffb7be.1403688576.git.mprivozn@redhat.com> <53AAD523.3000604@redhat.com> <20140625155048.252833c1@redhat.com> In-Reply-To: <20140625155048.252833c1@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="VnHHrm2OMBhknJpLJPXfDpCTdlEC6ueJ5" Subject: Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Luiz Capitulino Cc: Michal Privoznik , famz@redhat.com, qemu-devel@nongnu.org, Wenchao Xia , pbonzini@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --VnHHrm2OMBhknJpLJPXfDpCTdlEC6ueJ5 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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 b= y >> dropping qmp-commands.hx, and instead listing example usage directly i= n >> the qapi-schema.json file? I'm not sure if we have a good plan in pla= ce >> for user-facing documentation, even if the move to events-as-QAPI was >> desirable. >=20 > 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 wit= h > 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. >=20 > 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 planni= ng > 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 ter= m. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --VnHHrm2OMBhknJpLJPXfDpCTdlEC6ueJ5 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJTqy1xAAoJEKeha0olJ0NqBhQIAJXtBWEn9XS0VoOzFDLg6HaM DVlCbvMik8nEohQ2V4i4O6vB1NeJDB/mTLiQOFoYjEWd14G8xUoSVcJ68heByFVk X6LwSh7VEOus2f87gA+6AgxMlfBblqtGyIfPL82duDdgBVb7lufotr3crXGcMZBA nQAIfMGzZ1uBCjexHmAWgF4ds1WzeQRSuPSdSG9tONUzR5/NaaXeEhl8nQiqb8bw GALCdN0ZQQZslnw0g3DVWcqz0gI2VfcPsQNm2fm9Ji2uO7ZPYRE1PY8QmuzqIzYF u2S8uhilJTD9q2vIZfRRacJONdcmtdCiCjtOAzDZyGmhC7aOV9l0/3wamgXX4tk= =SqIV -----END PGP SIGNATURE----- --VnHHrm2OMBhknJpLJPXfDpCTdlEC6ueJ5--