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