Message ID | 1263662384-1459-1-git-send-email-weil@mail.berlios.de |
---|---|
State | New |
Headers | show |
Stefan Weil <weil@mail.berlios.de> 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 <weil@mail.berlios.de> > --- > 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. > DEF("name", HAS_ARG, QEMU_OPTION_name, [...] > +STEXI > +@item -writeconfig @var{file} > +Write device configuration to @var{file}. > +ETEXI > + > +HXCOMM This is the last statement. Insert new options before this line! > +STEXI > +@end table > +ETEXI Neat, thanks!
Markus Armbruster schrieb: > Stefan Weil <weil@mail.berlios.de> 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 <weil@mail.berlios.de> >> --- >> 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). 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 There is already an online help for the driver (qemu -device ?). Regards, Stefan
Stefan Weil <weil@mail.berlios.de> writes: > Markus Armbruster schrieb: >> Stefan Weil <weil@mail.berlios.de> 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 <weil@mail.berlios.de> >>> --- >>> 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 ?).
On Mon, Jan 18, 2010 at 08:32:25PM +0100, Stefan Weil wrote: > Markus Armbruster schrieb: > > Stefan Weil <weil@mail.berlios.de> 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 <weil@mail.berlios.de> > >> --- > >> 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). > > 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 > > There is already an online help for the driver (qemu -device ?). > > Regards, > > Stefan > Yes, this was on list of things to be fixed for a long time now. Some more things that need looking into: . -device ? itself is undocumented . - device ? currently prints system devices as well let's only print these that have a description and add ?? to list all devices . -netdev has undocumented options as well . we should have a flag to dump all options in one go, for ease of searching
On 01/16/2010 11:19 AM, Stefan Weil wrote: > 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<weil@mail.berlios.de> > Applied. Thanks. Regards, Anthony Liguori > --- > 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 > + > DEF("name", HAS_ARG, QEMU_OPTION_name, > "-name string1[,process=string2]\n" > " set the name of the guest\n" > @@ -1905,6 +1911,8 @@ ETEXI > DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ > "-nodefaults don't create default devices\n") > STEXI > +@item -nodefaults > +Don't create default devices. > ETEXI > > #ifndef _WIN32 > @@ -1927,10 +1935,6 @@ Immediately before starting guest execution, drop root privileges, switching > to the specified user. > ETEXI > > -STEXI > -@end table > -ETEXI > - > #if defined(TARGET_SPARC) || defined(TARGET_PPC) > DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, > "-prom-env variable=value\n" > @@ -1946,6 +1950,19 @@ DEF("old-param", 0, QEMU_OPTION_old_param, > #endif > DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, > "-readconfig<file>\n") > +STEXI > +@item -readconfig @var{file} > +Read device configuration from @var{file}. > +ETEXI > DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, > "-writeconfig<file>\n" > " read/write config file\n") > +STEXI > +@item -writeconfig @var{file} > +Write device configuration to @var{file}. > +ETEXI > + > +HXCOMM This is the last statement. Insert new options before this line! > +STEXI > +@end table > +ETEXI >
Markus Armbruster schrieb: > Stefan Weil <weil@mail.berlios.de> writes: > >> Markus Armbruster schrieb: >>> Stefan Weil <weil@mail.berlios.de> 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 <weil@mail.berlios.de> >>>> --- >>>> 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, ...
Stefan Weil <weil@mail.berlios.de> writes: > Markus Armbruster schrieb: >> Stefan Weil <weil@mail.berlios.de> writes: >> >>> Markus Armbruster schrieb: [...] >>>> 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, ... It's a start. Many thanks!
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 + DEF("name", HAS_ARG, QEMU_OPTION_name, "-name string1[,process=string2]\n" " set the name of the guest\n" @@ -1905,6 +1911,8 @@ ETEXI DEF("nodefaults", 0, QEMU_OPTION_nodefaults, \ "-nodefaults don't create default devices\n") STEXI +@item -nodefaults +Don't create default devices. ETEXI #ifndef _WIN32 @@ -1927,10 +1935,6 @@ Immediately before starting guest execution, drop root privileges, switching to the specified user. ETEXI -STEXI -@end table -ETEXI - #if defined(TARGET_SPARC) || defined(TARGET_PPC) DEF("prom-env", HAS_ARG, QEMU_OPTION_prom_env, "-prom-env variable=value\n" @@ -1946,6 +1950,19 @@ DEF("old-param", 0, QEMU_OPTION_old_param, #endif DEF("readconfig", HAS_ARG, QEMU_OPTION_readconfig, "-readconfig <file>\n") +STEXI +@item -readconfig @var{file} +Read device configuration from @var{file}. +ETEXI DEF("writeconfig", HAS_ARG, QEMU_OPTION_writeconfig, "-writeconfig <file>\n" " read/write config file\n") +STEXI +@item -writeconfig @var{file} +Write device configuration to @var{file}. +ETEXI + +HXCOMM This is the last statement. Insert new options before this line! +STEXI +@end table +ETEXI
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 <weil@mail.berlios.de> --- qemu-options.hx | 25 +++++++++++++++++++++---- 1 files changed, 21 insertions(+), 4 deletions(-)