qemu-devel
[Top][All Lists]
Advanced

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

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


From: Marc-André Lureau
Subject: Re: [Qemu-devel] problems with qapi2texi.py (use of @quotation)
Date: Thu, 16 Feb 2017 13:21:39 +0000

Hi

On Thu, Feb 16, 2017 at 4:11 PM Peter Maydell <address@hidden>
wrote:

> 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,
>

I am not so sure,
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040quotation.html#index-quotation

Explicitely mention that @quotation recongnizes Caution, Important, Note,
Tip & Warning (and appropriately translates to docbook), and other
arguments are accepted.

It doesn't say if other markup/commands are forbidden/discouraged inside
@quotation.

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.
>
>
That's fine for me, though we will probably lose the docbook semantic
translation and will instead have to deal with styling, but since our
source content is not texinfo, and texinfo is only intermediary step here,
I don't think we care much. I'll try to find a solution, I'd be happy to
hear any texinfo expert about ideas though ;)
-- 
Marc-André Lureau


reply via email to

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