Re: [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 7 Feb 2020 at 08:33, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > rST format requires a blank line before the start of a bulleted
>> > or enumerated list. Two places in qapi-schema.json were missing
>> > this blank line.
>> >
>> > Some places were using an indented line as a sort of single-item
>> > bulleted list, which in the texinfo output comes out all run
>> > onto a single line; use a real bulleted list instead.
>> >
>> > Some places unnecessarily indented lists, which confuses rST.
>> >
>> > guest-fstrim:minimum's documentation was indented the
>> > right amount to share a line with @minimum, but wasn't
>> > actually doing so.
>> >
>> > The indent on the bulleted list in the guest-set-vcpus
>> > Returns section meant rST misindented it.
>> >
>> > Changes to the generated texinfo are very minor (the new
>> > bulletted lists, and a few extra blank lines).
>> >
>> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>
>> > @@ -767,17 +771,17 @@
>> >  # Returns: The length of the initial sublist that has been successfully
>> >  #          processed. The guest agent maximizes this value. Possible cases:
>> >  #
>> > -#          - 0:              if the @vcpus list was empty on input. Guest state
>> > -#                            has not been changed. Otherwise,
>> > -#          - Error:          processing the first node of @vcpus failed for the
>> > -#                            reason returned. Guest state has not been changed.
>> > -#                            Otherwise,
>> > +#          - 0: if the @vcpus list was empty on input. Guest state
>> > +#            has not been changed. Otherwise,
>> > +#          - Error: processing the first node of @vcpus failed for the
>> > +#            reason returned. Guest state has not been changed.
>> > +#            Otherwise,
>> >  #          - < length(@vcpus): more than zero initial nodes have been processed,
>> > -#                            but not the entire @vcpus list. Guest state has
>> > -#                            changed accordingly. To retrieve the error
>> > -#                            (assuming it persists), repeat the call with the
>> > -#                            successfully processed initial sublist removed.
>> > -#                            Otherwise,
>> > +#            but not the entire @vcpus list. Guest state has
>> > +#            changed accordingly. To retrieve the error
>> > +#            (assuming it persists), repeat the call with the
>> > +#            successfully processed initial sublist removed.
>> > +#            Otherwise,
>> >  #          - length(@vcpus): call successful.
>>
>> Source readability suffers a bit here.
>>
>> Can we break the line after the colon?
>>
>>    #          - 0:
>>    #            if the @vcpus list was empty on input. Guest state has
>>    #            not been changed. Otherwise,
>>
>> Or would a definition list be a better fit?
>
> A definition list does produce nicer rendering in the rST, but
> it breaks the rendering in the texinfo (which interprets the
> indent of a rST definition list as meaninglist and renders it
> all as one long run-on paragraph). For the purposes of this
> initial cleanup, I'll put in the newlines you suggest, which
> have no effect on rendering output for either texinfo or rST.

Okay.  We can switch to definition lists later.