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

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:

> 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 ..." ?

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!