Peter Maydell <peter.mayd...@linaro.org> writes:
> On 16 January 2017 at 09:33, Markus Armbruster <arm...@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
