Re: [Qemu-devel] [PATCH v2] Man page: Add -global description

[Miroslav Rezanina]

----- Original Message -----
> From: "Peter Maydell" <address@hidden>
> To: "Miroslav Rezanina" <address@hidden>
> Cc: address@hidden
> Sent: Wednesday, March 14, 2012 7:21:30 PM
> Subject: Re: [Qemu-devel] [PATCH v2] Man page: Add -global description
>
> On 14 March 2012 08:53, Miroslav Rezanina <address@hidden>
> wrote:
> > --- a/qemu-options.hx
> > +++ b/qemu-options.hx
> > @@ -292,9 +292,13 @@ DEF("global", HAS_ARG, QEMU_OPTION_global,
> >     "                set a global default for a driver property\n",
> >     QEMU_ARCH_ALL)
> >  STEXI
> > address@hidden -global
> > address@hidden -global @address@hidden@var{value}
>
> We seem to use @var{prop}, not @var{property}, elsewhere in the docs.
>
You're right, I reused naming from DEF part...both has to be updated.

> > address@hidden -global
> > -TODO
> > +Set default value of @var{driver}'s @var{property} to @var{value},
> > e.g.:
> > +
> > address@hidden
> > +qemu -global ide-drive.physical_block_size=4096 -drive
> > file=file,if=ide,index=0
> > address@hidden example
> >  ETEXI
>
> This is missing any motivation for why you would want to actually
> use this option. How about:
>
> "In particular, you can use this to set driver properties for devices
> which
> are created automatically by the machine model. (To create a device
> which is
> not created automatically and set properties on it, use -device.)"
>
> ?
>
> That's still not great, but I think it helps a little.
>

Yeah, more use case should be stated but I do not think man page is good
place for extensive user motivation.

> (ideally if -device/-global are the new standard interface we should
> have a
> section explaining the general concepts and syntax and then
> documentation of
> how to do specific things like networking via -device, and relegate
> all the
> 'legacy' options to a section clearly marked as 'legacy' with
> pointers back
> to the new ways of doing the same thing. That would be a much bigger
> job,
> though.)
>

Agree, man page is really behind the code. However, I think documenting new
interfaces should be done first to agree on them and their usage. After new
way is known extracting old interface as legacy stuff would be easier.

> -- PMM
>


Anyway, I will resend this patch with updates you recommended.

Mirek