Re: [Qemu-devel] [PULL v2 000/180] QAPI patches for 2017-01-16

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On 17 January 2017 at 08:31, Markus Armbruster <armbru@redhat.com> wrote:
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>> This seems to trigger some warnings from older makeinfo versions:
>>>
>>> On the Fedora 20 ppc64be box and Ubuntu 14.04.5 LTS aarch64 box
>>> (Ubuntu: makeinfo (GNU texinfo) 5.2;
>>>  Fedora: makeinfo (GNU texinfo) 5.1)
>>
>> Nobody should be using F20 by now, but the Ubuntu LTS is still legit.
>
> The F20 box is the GCC compile farm's ppc64be box, so I'm not going
> to drop it from the build system list I'm afraid.
>
>>> /home/pm215/qemu/docs/qemu-ga-ref.texi:41: warning: undefined flag: VERSION
>>> /home/pm215/qemu/docs/qemu-ga-ref.texi:41: warning: undefined flag: VERSION
>>> /home/pm215/qemu/docs/qemu-qmp-ref.texi:41: warning: undefined flag: VERSION
>>> /home/pm215/qemu/docs/qemu-qmp-ref.texi:41: warning: undefined flag: VERSION
>>
>> This is supposed to be defined in Makefile:
>>
>>     MAKEINFO=makeinfo -D 'VERSION $(VERSION)'
>>
>> Hrrm, Texinfo's NEWS file has for 6.0:
>>
>> * texi2any:
>>   [...]
>>   . -D'var val' on the command line works as intended again.
>>
>> I tried to find out more about this fix, but the Texinfo repository's
>> commit log is useless.
>>
>> I can reproduce the warning with 6.2 by running makeinfo without -D.
>> Curiously, output isn't affected.  Looks like @subtitle is ignored by
>> makeinfo.
>
> That suggests we should be putting the VERSION information
> somewhere else so it actually appears in the output :-)
>
> Maybe writing the VERSION info to a file as a @set command
> (and then including that file in the texi) would work ?

Right now, that'll make no difference whatsoever, because the programs
that choke on -D generate no output for the commands using the variable
defined with -D.  All they do is gripe.

Three possible solutions, in increasing order of complexity:

1. Live with the warning from old versions.  If a new version comes
around that does something with @subtitle, it'll just work.

2. Suppress the warning with @iftex-hammer.  No change in output now.
If a new version comes around that does something with @subtitle, we
won't profit unless we take out the @iftex.

3. Replace -D by @set, either by preprocessing .texi, or by including a
generated snippet.  No change in output now.  If a new version comes
around that does something with @subtitle, it'll just work.

My order of preference is aligned with decreasing complexity, i.e. first
1., then 2., then 3.

Please tell me what you want.

If you want 3., I can certainly live with it, but I'd rather do 1. or
2. now, to get my rather conflict-prone pull request in, then do 3. as a
follow-up patch.

>> Possible work-around I could squash in:
>>
>> diff --git a/docs/qemu-qmp-ref.texi b/docs/qemu-qmp-ref.texi
>> index 818e525..e0f2454 100644
>> --- a/docs/qemu-qmp-ref.texi
>> +++ b/docs/qemu-qmp-ref.texi
>> @@ -38,7 +38,9 @@ along with this manual.  If not, see http://www.gnu.org/licens
>> es/.
>>
>>  @titlepage
>>  @title QMP Reference Manual
>> +@iftex @c Work around bug in Texinfo prior to 6.0
>>  @subtitle QEMU version @value{VERSION}
>> +@end iftex
>>  @page
>>  @vskip 0pt plus 1filll
>>  @insertcopying
>>
>> Marc-André, what do you think?
>>
>>> On OSX (makeinfo (GNU texinfo) 4.8):
>>
>> That's from 2004.  Just sayin'.
>
> I assume it's the last GPLv2 version...
>
>>> ./qemu-options.texi:60: warning: unlikely character [ in @var.
>>> ./qemu-options.texi:60: warning: unlikely character ] in @var.
>>> ./qemu-options.texi:61: warning: unlikely character [ in @var.
>>> ./qemu-options.texi:61: warning: unlikely character ] in @var.
>>
>> Generated qemu-options.texi did not change (I checked).
>>
>> The offending lines are
>>
>>     @item -numa node[,mem=@var{size}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
>>     @itemx -numa node[,memdev=@var{id}][,cpus=@var{cpu[-cpu]}][,nodeid=@var{node}]
>>
>> which are generated from qemu-options.hx's
>>
>>     DEF("numa", HAS_ARG, QEMU_OPTION_numa,
>>         "-numa node[,mem=size][,cpus=cpu[-cpu]][,nodeid=node]\n"
>>         "-numa node[,memdev=id][,cpus=cpu[-cpu]][,nodeid=node]\n", QEMU_ARCH_ALL)
>>
>> by scripts/hxtool.
>>
>> This use of @var{} is perhaps questionable, but nothing changed around
>> here for many moons.  Are you sure this is new in my pull request?
>
> Yep, definitely new. With current master:
>
> bash-3.2$ touch qemu-options.hx
> bash-3.2$ make -C build/all
>   GEN     qemu-options.def
>   GEN     qemu-options.texi
>   GEN     qemu-doc.html
> /Users/pm215/src/qemu-for-merges/qemu-doc.texi:7: warning:
> unrecognized encoding name `UTF-8'.
>
> but no warnings about unlikely characters.

The problem of having [] within @var certainly predates this series.  I
can't see how the series brings it to the surface in the form of
warnings.  I don't have access to OS-X myself.  I tried to reproduce
with a locally compiled 4.8 I downloaded from gnu.org, no luck.  Perhaps
I'm doing it wrong.  Please send me a build log, preferably with V=1.