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

[Peter Maydell]

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.

thanks
-- PMM