On Fri, 7 Feb 2020 at 08:33, Markus Armbruster <arm...@redhat.com> wrote: > > Peter Maydell <peter.mayd...@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.mayd...@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. thanks -- PMM
