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

[Markus Armbruster <armbru@redhat.com>]

Marc-André Lureau <marcandre.lureau@gmail.com> writes:

> Hi
>
> On Tue, Jan 17, 2017 at 12:34 PM Markus Armbruster <armbru@redhat.com>
> wrote:
>
>> 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/ <http://www.gnu.org/licenses/>.
>>
>>  @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?
>>
>
> Since title @subtitle is being ignored by makeinfo, that looks fine.
> However, I think I would prefer rather have the warning since it's a
> makeinfo bug on old versions and it can be ignored. Hopefully, this thread
> can easily be found for reference (update commit message too?). Either way,
> I don't mind. Thanks

My proposed work-around suppresses the warning we get from old versions
of makeinfo, but might degrade the title page with future versions of
makeinfo.

Peter, what's your preference?