qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Qemu-devel] problems with qapi2texi.py (use of @quotation)


From: Peter Maydell
Subject: [Qemu-devel] problems with qapi2texi.py (use of @quotation)
Date: Thu, 16 Feb 2017 12:09:06 +0000

When we build qemu-qmp-ref.txt this causes texinfo to complain several
times:
"Negative repeat count does nothing at
/usr/share/texinfo/Texinfo/Convert/Line.pm line 124."

I dug into what's happening here a bit, and I think the problem is
that we're generating bogus texinfo.

In particular I think they're the result of the three places where
we try to have an enumerated list inside a Notes section, which
generate texi like this:

@quotation Notes
@enumerate
@item
The 'query-migrate' command should be used to check migration's progress
and final result (this information is provided by the 'status' member)

@item
All boolean arguments default to false

@item
The user Monitor's "detach" argument is invalid in QMP and should not
be used
@end enumerate

@end quotation

This is definitely not what @quotation is supposed to be used for,
and I think the nested indentation (since @enumerate also indents)
is confusing things.

It also doesn't display correctly, because the "Notes" text disappears
entirely in the HTML version because it thinks there's no actual
quotation text.

Similarly, all the Examples lose the "Examples" heading text because
they're an @example inside a @quotation and the @quotation handling
thinks there's no actual quotation text.

The text file output formatting is also not good, for instance:

          Notes: 1. The 'query-migrate' command should be used to check
               migration's progress and final result (this information
               is provided by the 'status' member)

            2. All boolean arguments default to false

            3. The user Monitor's "detach" argument is invalid in QMP
               and should not be used

          Example: -> { "execute": "migrate", "arguments": { "uri":
"tcp:0:4446" } }
               <- { "return": {} }

where the lack of a line break after "Example:" and "Notes:"
means things don't line up right.

I think the best fix for all these problems is to stop misusing
@quotation for doing something other than printing quotations,
and use something that just formats the "Notes", "Examples",
etc lines the way we want. I don't know enough texinfo to
suggest what that should be, though.

thanks
-- PMM



reply via email to

[Prev in Thread] Current Thread [Next in Thread]