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

[Peter Maydell]

On 16 February 2017 at 13:21, Marc-André Lureau
 wrote:
> 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.

True. On the other hand we don't use Caution Important Tip
or Warning, and we use a mix of Note (handled specially)
and Notes (not)...

thanks
-- PMM

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

[Marc-André Lureau]

Hi

On Thu, Feb 16, 2017 at 4:11 PM Peter Maydell 
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

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

[Peter Maydell]

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