[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST |
Date: |
Fri, 14 Feb 2020 14:16:55 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux) |
Peter Maydell <address@hidden> writes:
> On Fri, 7 Feb 2020 at 08:33, Markus Armbruster <address@hidden> wrote:
>>
>> Peter Maydell <address@hidden> 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 <address@hidden>
>
>> > @@ -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.
- Re: [PATCH 02/29] configure: Check that sphinx-build is using Python 3, (continued)
- [PATCH 07/29] qapi/block-core.json: Use literal block for ascii art, Peter Maydell, 2020/02/06
- [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/06
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Markus Armbruster, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Max Reitz, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Kevin Wolf, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Peter Maydell, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Markus Armbruster, 2020/02/07
- Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments, Max Reitz, 2020/02/07