Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls

[Vladimir Sementsov-Ogievskiy]

On 28.04.23 12:34, Markus Armbruster wrote:
> Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:
>
> > On 27.04.23 12:53, Markus Armbruster wrote:
> > > Signed-off-by: Markus Armbruster <armbru@redhat.com>
> > > ---
> > >    docs/devel/qapi-code-gen.rst | 53 ++++++++++++++++++++++++++++++++++++
> > >    1 file changed, 53 insertions(+)
> > > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> > > index d81aac7a19..14983b074c 100644
> > > --- a/docs/devel/qapi-code-gen.rst
> > > +++ b/docs/devel/qapi-code-gen.rst
> > > @@ -1059,6 +1059,59 @@ For example::
> > >       'returns': ['BlockStats'] }
> > >      +Markup pitfalls
> > > +~~~~~~~~~~~~~~~
> > > +
> > > +A blank line is required between list items and paragraphs.  Without
> > > +it, the list may not be recognized, resulting in garbled output.  Good
> > > +example::
> > > +
> > > + # An event's state is modified if:
> > > + #
> > > + # - its name matches the @name pattern, and
> > > + # - if @vcpu is given, the event has the "vcpu" property.
> > > +
> > > +Without the blank line this would be a single paragraph.
> > > +
> > > +Indentation matters.  Bad example::
> > > +
> > > + # @none: None (no memory side cache in this proximity domain,
> > > + #              or cache associativity unknown)
> > > +
> > > +The description is parsed as a definition list with term "None (no
> > > +memory side cache in this proximity domain," and definition "or cache
> > > +associativity unknown)".
> >
> > May be add good example of indentation as well
>
> Patches I'm about to post will fill up this pitfall.  They change the
> text to:
>
>       # @none: None (no memory side cache in this proximity domain,
>       #              or cache associativity unknown)
>       #     (since 5.0)
>
>      The last line's de-indent is wrong.  The second and subsequent lines

So you want to drop "The description is parsed as a definition list ..." ?

>      need to line up with each other, like this::
>
>       # @none: None (no memory side cache in this proximity domain,
>       #     or cache associativity unknown)
>       #     (since 5.0)
>
> Good enough?

Example of good indent is good)

--
Best regards,
Vladimir