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

[Marc-André Lureau]

Hi

On Tue, Jan 17, 2017 at 12:34 PM Markus Armbruster <address@hidden>
wrote:

> Peter Maydell <address@hidden> writes:
>
> > On 16 January 2017 at 09:33, Markus Armbruster <address@hidden>
> 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
> address@hidden @c Work around bug in Texinfo prior to 6.0
>  @subtitle QEMU version @value{VERSION}
> address@hidden 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


> > 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[,address@hidden,address@hidden,address@hidden
>     @itemx -numa
> node[,address@hidden,address@hidden,address@hidden
>
> 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
>
> --
Marc-André Lureau