[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pit
From: |
Markus Armbruster |
Subject: |
Re: [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls |
Date: |
Fri, 28 Apr 2023 11:34:02 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) |
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
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?
[...]
- [PATCH v2 15/16] qapi: Format since information the conventional way: (since X.Y), (continued)
- [PATCH v2 15/16] qapi: Format since information the conventional way: (since X.Y), Markus Armbruster, 2023/04/25
- [PATCH v2 16/16] qapi storage-daemon/qapi: Fix documentation section structure, Markus Armbruster, 2023/04/25
- [PATCH v2 12/16] qapi: Fix argument documentation markup, Markus Armbruster, 2023/04/25
- [PATCH v2 06/16] qapi: @foo should be used to reference, not ``foo``, Markus Armbruster, 2023/04/25
- [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls, Markus Armbruster, 2023/04/27
- [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls, Markus Armbruster, 2023/04/27