Re: [Qemu-trivial] [Qemu-devel] [PATCH 1/1] Add -incoming help text

[Markus Armbruster <armbru@redhat.com>]

Michael Tokarev <mjt@tls.msk.ru> writes:

> 29.05.2015 21:52, Dr. David Alan Gilbert (git) wrote:
>> From: "Dr. David Alan Gilbert" <dgilbert@redhat.com>
>> 
>> The help/man text for
>> 
>> -incoming defer
>> 
>> didn't make it through the merge of the code that implemented it.
>> 
>> Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
>> ---
>>  qemu-options.hx | 6 +++++-
>>  1 file changed, 5 insertions(+), 1 deletion(-)
>> 
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index dad49cf..3085412 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -3238,7 +3238,9 @@ DEF("incoming", HAS_ARG, QEMU_OPTION_incoming, \
>>      "-incoming fd:fd\n" \
>>      "-incoming exec:cmdline\n" \
>>      "                accept incoming migration on given file descriptor\n" \
>> -    "                or from given external command\n",
>> +    "                or from given external command\n" \
>> +    "-incoming defer\n" \
>> +    "                wait for the URI to be specified via migrate_incoming\n",
>>      QEMU_ARCH_ALL)
>>  STEXI
>>  @item -incoming tcp:[@var{host}]:@var{port}[,to=@var{maxport}][,ipv4][,ipv6]
>> @@ -3254,6 +3256,8 @@ Accept incoming migration from a given filedescriptor.
>>  
>>  @item -incoming exec:@var{cmdline}
>>  Accept incoming migration as an output from specified external command.
>> +@item -incoming defer
>> +Wait for the URI to be specified via migrate_incoming.
>
> I wonder what's the reason of mentioning it twice with
> such a short and _identical_ text each time...

Because that's the way our documentation works.

The first hunk patches the fourth argument of DEF(), which goes into
-help.

The second hunk patches STEXI..ETEXI, which goes via qemu-options.texi
into qemu.1 and qemu-doc.{dvi,info,html,pdf}.

>                                                 Maybe
> it's a good idea to reword the second message a bit.
> Because actually it is not clear what does the whole
> thing mean, what qemu will do when starting? Will it
> accept other commands?

You're right in that .texi allows more verbose explanations than -help.

David's text looks okay to me as is.  Perhaps your questions inspire
further improvements.