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 16 January 2017 at 09:33, Markus Armbruster <armbru@redhat.com> wrote:
>> This is Marc-André's "[PATCH v8 00/21] qapi doc generation (whole
>> version, squashed)" with a few commit messages tweaked, and "[PATCH v8
>> 14/21] (SQUASHED) move doc to schema" unsquashed into 161 patches.
>>
>> We did all the respins with in this squashed form to reduce noise.
>> However, since the unsquashed form is better suited for review, and
>> probably nicer if we have to revisit this part of the work down the
>> road, I'm proposing to merge this unsquashed.
>>
>> If you want me to post the unsquashed patches, I'm happy to redo this
>> pull request.
>>
>> If you'd rather pull the squashed version, likewise.
>>
>> I'm afraid this is a bit of a doc conflict magnet.  The sooner we can
>> get it in, the easier for Marc-André and me.
>>
>> v2:
>> * Rebased (v1 conflicts with commit e1ff3c6)
>> * test-qapi.py tweaked to avoid trailing empty lines in .out
>>
>> The following changes since commit b6af8ea60282df514f87d32e36afd1c9aeee28c8:
>>
>>   Merge remote-tracking branch 'remotes/ehabkost/tags/x86-and-machine-pull-request' into staging (2017-01-13 14:38:21 +0000)
>>
>> are available in the git repository at:
>>
>>   git://repo.or.cz/qemu/armbru.git tags/pull-qapi-2017-01-16
>>
>> for you to fetch changes up to 56e8bdd46a8a42d89b0afea9da83ae7679cc0439:
>>
>>   build-sys: add qapi doc generation targets (2017-01-16 10:11:43 +0100)
>>
>> ----------------------------------------------------------------
>> QAPI patches for 2017-01-16
>
> 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.

> /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.

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'.

> ./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?

> (OSX also has the long standing warning
> /Users/pm215/src/qemu-for-merges/qemu-doc.texi:7: warning:
> unrecognized encoding name `UTF-8'.
> but you can ignore that since it's been that way for years
> and is because osx's makeinfo is ancient.)
>
> thanks
> -- PMM