From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1NXihl-0001kW-0P for qemu-devel@nongnu.org; Wed, 20 Jan 2010 17:07:13 -0500 Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1NXihg-0001er-2e for qemu-devel@nongnu.org; Wed, 20 Jan 2010 17:07:12 -0500 Received: from [199.232.76.173] (port=35224 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1NXihf-0001ec-R6 for qemu-devel@nongnu.org; Wed, 20 Jan 2010 17:07:07 -0500 Received: from mx20.gnu.org ([199.232.41.8]:19168) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1NXihf-0004OF-Bv for qemu-devel@nongnu.org; Wed, 20 Jan 2010 17:07:07 -0500 Received: from moutng.kundenserver.de ([212.227.17.9]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1NXihd-00085v-K7 for qemu-devel@nongnu.org; Wed, 20 Jan 2010 17:07:06 -0500 Message-ID: <4B577E0D.4020009@mail.berlios.de> Date: Wed, 20 Jan 2010 23:05:01 +0100 From: Stefan Weil MIME-Version: 1.0 Subject: Re: [Qemu-devel] [PATCH] Documentation: Add missing documentation for qdev related command line options References: <1263662384-1459-1-git-send-email-weil@mail.berlios.de> <4B54B749.5080304@mail.berlios.de> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Markus Armbruster Cc: QEMU Developers Markus Armbruster schrieb: > Stefan Weil writes: > >> Markus Armbruster schrieb: >>> Stefan Weil writes: >>> >>>> The command line options -device, -nodefaults, -readconfig, >>>> -writeconfig had entries for command line help, but >>>> documentation for texi and derived formats (man, html, info) >>>> was missing. >>>> >>>> This also required moving "@end table" to the end of >>>> qemu-options.hx again. >>>> >>>> Signed-off-by: Stefan Weil >>>> --- >>>> qemu-options.hx | 25 +++++++++++++++++++++---- >>>> 1 files changed, 21 insertions(+), 4 deletions(-) >>>> >>>> diff --git a/qemu-options.hx b/qemu-options.hx >>>> index e2edd71..b2d04e2 100644 >>>> --- a/qemu-options.hx >>>> +++ b/qemu-options.hx >>>> @@ -404,6 +404,12 @@ ETEXI >>>> >>>> DEF("device", HAS_ARG, QEMU_OPTION_device, >>>> "-device driver[,options] add device\n") >>>> +STEXI >>>> +@item -device @var{driver}[,@var{option}[,...]] >>>> +Add device @var{driver}. Depending on the device type, >>>> +@var{option} (typically @var{key}=@var{value}) may be useful. >>>> +ETEXI >>>> + >>> While there, would you mind improving --help for -device a bit? It's >>> too terse, and it doesn't start the help text in column 16 like the >>> other options do. >> Hi Markus, >> >> this needs a little more work. I just had a look on the code, >> and there is no online help for the possible options (key, value). > > What I had in mind was just to bring it up to par with your patch to the > texi, but... > >> If you (and especially those who have commit rights) agree, >> I could provide these three additional patches: >> >> * Add online help for properties (qemu -device driver,?) >> * Add online help for property value (qemu -device driver,property=?) >> * Update documentation for command line option -device > > ... a patch to provide that is very desirable! > > I figure the best way to document available properties and there values > is a self-documenting struct PropertyInfo: add a doc member, extend > DEFINE_PROP() & friends to set it, fix up users to pass NULL, and so > forth. We can then replace the NULL by something useful at our leisure. > >> There is already an online help for the driver (qemu -device ?). I cannot spend too much time on this, but a very basic help for "?" is implemented by the patch series I just sent to the list. The new feature was already very helpful for me, but it still can be improved, of course: the driver list contains shows too many drivers and is not nicely formatted, the help text for the values could be more user friendly, ...