[Qemu-devel] [RFC PATCH 03/32] qapi2texi: Fix for examples containing '@'

[Markus Armbruster <armbru@redhat.com>]

Instead of quoting example text so that the @example environment shows
it verbatim, simply use the @verbatim environment.

Examples are no longer indented in output, because makeinfo doesn't
indent @verbatim, unlike @example.
TODO keep indentation somehow?

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 scripts/qapi2texi.py            | 12 +++++-------
 tests/qapi-schema/doc-good.json |  2 +-
 tests/qapi-schema/doc-good.out  |  2 +-
 tests/qapi-schema/doc-good.texi | 16 ++++++++--------
 4 files changed, 15 insertions(+), 17 deletions(-)

diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
index 92e2af2cd6..1500afc553 100755
--- a/scripts/qapi2texi.py
+++ b/scripts/qapi2texi.py
@@ -52,13 +52,11 @@ def subst_braces(doc):
 
 
 def texi_example(doc):
-    """Format @example"""
-    # TODO: Neglects to escape @ characters.
-    # We should probably escape them in subst_braces(), and rename the
-    # function to subst_special() or subs_texi_special().  If we do that, we
-    # need to delay it until after subst_vars() in texi_format().
-    doc = subst_braces(doc).strip('\n')
-    return EXAMPLE_FMT(code=doc)
+    """Format example text"""
+    return """@verbatim
+{code}
+@end verbatim
+""".format(code=doc.strip('\n'))
 
 
 def texi_format(doc):
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 44098d7f1a..54a0012d5f 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -117,7 +117,7 @@
 # <- out
 # Examples:
 # - *verbatim*
-# - @at sign BUG: gets passed to Texinfo unescaped
+# - @at sign
 # - {braces}
 # Since: 2.10
 ##
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index b732b81119..a62d2d879c 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -138,7 +138,7 @@ Duis aute irure dolor
 <- out
     section=Examples
 - *verbatim*
-- @at sign BUG: gets passed to Texinfo unescaped
+- @at sign
 - {braces}
     section=Since
 2.10
diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
index 840a492249..3b77f2f675 100644
--- a/tests/qapi-schema/doc-good.texi
+++ b/tests/qapi-schema/doc-good.texi
@@ -201,17 +201,17 @@ Ut enim ad minim veniam
 Duis aute irure dolor
 
 @b{Example:}
-@example
+@verbatim
 -> in
 <- out
-@end example
+@end verbatim
 
 @b{Examples:}
-@example
+@verbatim
 - *verbatim*
-- @at sign BUG: gets passed to Texinfo unescaped
-- @{braces@}
-@end example
+- @at sign
+- {braces}
+@end verbatim
 
 @b{Since:}
 2.10
@@ -227,11 +227,11 @@ If you're bored enough to read this, go see a video of boxed cats
 @b{Arguments:} the members of @code{Object}
 
 @b{Example:}
-@example
+@verbatim
 -> in
 
 <- out
-@end example
+@end verbatim
 
 @end deftypefn
 
-- 
2.13.6