From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=33528 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1ODCxM-000146-Uw for qemu-devel@nongnu.org; Sat, 15 May 2010 04:42:49 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1ODCxK-0007uu-Vz for qemu-devel@nongnu.org; Sat, 15 May 2010 04:42:48 -0400 Received: from fmmailgate02.web.de ([217.72.192.227]:44517) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1ODCxK-0007up-Ji for qemu-devel@nongnu.org; Sat, 15 May 2010 04:42:46 -0400 Message-ID: <4BEE5E84.2000503@web.de> Date: Sat, 15 May 2010 10:42:44 +0200 From: Jan Kiszka MIME-Version: 1.0 References: <1273086712-29163-1-git-send-email-lcapitulino@redhat.com> <1273086712-29163-2-git-send-email-lcapitulino@redhat.com> <4BED7FDC.7030208@siemens.com> <4BED8202.5020309@redhat.com> <4BED8224.9030604@redhat.com> <4BED8377.7040000@siemens.com> <20100514201059.282481fa@redhat.com> In-Reply-To: <20100514201059.282481fa@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="------------enig391ECDFE770BF3EEFD203487" Sender: jan.kiszka@web.de Subject: [Qemu-devel] Re: [PATCH 1/2] QMP: Introduce commands doc List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Luiz Capitulino Cc: "qemu-devel@nongnu.org" , "bazulay@redhat.com" , "juzhang@redhat.com" , Avi Kivity , "armbru@redhat.com" This is an OpenPGP/MIME signed message (RFC 2440 and 3156) --------------enig391ECDFE770BF3EEFD203487 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Luiz Capitulino wrote: > On Fri, 14 May 2010 19:08:07 +0200 > Jan Kiszka wrote: >=20 >> Avi Kivity wrote: >>> On 05/14/2010 08:01 PM, Avi Kivity wrote: >>>> On 05/14/2010 07:52 PM, Jan Kiszka wrote: >>>>>> In order not to compromise QMP adoption and make users' life easie= r, >>>>>> this commit adds a simple text documentation which fully describes= >>>>>> all QMP supported commands. >>>>>> >>>>>> This is not ideal for a number of reasons (harder to maintain, >>>>>> text-only, etc) but does improve the current situation. >>>>> Even if it's temporary - maintaining it in a separate file looks ra= ther >>>>> unhandy. >>>>> >>>>> Can't we generate the per-command documentation snippets also from >>>>> qemu-monitor.hx and merge them with a header/footer into some text = file? >>>>> That .hx file is the one anyone adding/converting commands has to t= ouch >>>>> anyway. >>>> If we do, then the generated documentation should be included in the= =20 >>>> patch changelog for review. >>>> >>> I mean, a patch introducing or modifying a monitor command. >> The snippets should be readable by themselves. I'm only proposing to >> keep them in the central file, at the same location where the others >> are. There is no difference compared to existing monitor commands, we >> just add the third documentation snippet, this time for QMP. >=20 > It's not only the snippets. We add a json type for each parameter, a > more descriptive info and notes. Only QMP commands should be shown > this way. Whatever its semantic is, technically it's a text block of a few lines that has to be added somewhere. >=20 > I'm sure there's a way to hack the qemu's doc script to do all this, > but the right solution is to move _everything_ to json and generate goo= d, > well formatted documentation from there (along with self-description). I'm not talking about The Right solution, I'm talking about a more handy temporary setup. When do you plan to refactor the command documentation that way? And how many commands will be touched in the meantime? >=20 > Also, adapting things will take time and this will delay even more thi= s > doc to be merged, which is what I'm trying to avoid. >=20 I can provide you the patch for hxtool and Makefile (a few lines), and I'm willing to split up the existing doc, just drop me a note. So nothing needs to be delayed any further. Jan --------------enig391ECDFE770BF3EEFD203487 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.9 (GNU/Linux) Comment: Using GnuPG with SUSE - http://enigmail.mozdev.org iEYEARECAAYFAkvuXoQACgkQitSsb3rl5xR48gCgpY7I291kwTjaz2A/DFkY8LtX FCoAoKr/c4GLnQEqcAmIKjtHpZL9dyok =37Oj -----END PGP SIGNATURE----- --------------enig391ECDFE770BF3EEFD203487--