Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru> writes: > On 28.04.23 12:34, Markus Armbruster wrote: >> Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru> writes: >> >>> On 27.04.23 12:53, Markus Armbruster wrote: >>>> Signed-off-by: Markus Armbruster <arm...@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 ..." ?
Yes, because that'll be factually wrong :) Happy to explain further once the patches are on the 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) Thanks!
