[Qemu-devel] [RFC PATCH 06/32] qapi2texi: Drop | example markup

[Markus Armbruster <armbru@redhat.com>]

Doc comment lines starting with '|' are examples.  qapi2texi.py puts
each line in its own @example environment, which is wrong.
Fortunately, this kind of example markup is used in just one place
outside tests.  Replace it by Texinfo markup, and drop the '|'
feature.

tests/qapi-schema/doc-good.texi changes, because unlike the '|'
markup, !texinfo terminates lists.  See the FIXME in texi_format().

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.txt    | 10 ----------
 qapi-schema.json                |  8 ++++++--
 scripts/qapi2texi.py            |  9 +--------
 tests/qapi-schema/doc-good.json |  8 ++++++--
 tests/qapi-schema/doc-good.out  |  8 ++++++--
 tests/qapi-schema/doc-good.texi | 10 +++-------
 6 files changed, 22 insertions(+), 31 deletions(-)

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 0334ef37ef..579807f6a5 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -65,11 +65,6 @@ Double the '=' for a subsection title:
 
     # == Subection title
 
-'|' denotes examples:
-
-    # | Text of the example, may span
-    # | multiple lines
-
 '*' starts an itemized list:
 
     # * First item, may span
@@ -110,11 +105,6 @@ Example:
 # 1. with a list
 # 2. like that
 #
-# And some code:
-# | $ echo foo
-# | -> do this
-# | <- get that
-#
 # Texinfo markup:
 # !texinfo
 # @table @samp
diff --git a/qapi-schema.json b/qapi-schema.json
index 3490a5edaf..a6ef550fd5 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -20,8 +20,12 @@
 #
 # Example:
 #
-# | -> data issued by the Client
-# | <- Server data response
+# !texinfo
+# @verbatim
+# -> data issued by the Client
+# <- Server data response
+# @end verbatim
+# !end texinfo
 #
 # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
 # detailed information on the Server command and response formats.
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
index e356f911bb..bfd1c676e1 100755
--- a/scripts/qapi2texi.py
+++ b/scripts/qapi2texi.py
@@ -25,11 +25,6 @@ TYPE_FMT = """
 
 """.format
 
-EXAMPLE_FMT = """@example
-{code}
-@end example
-""".format
-
 
 def subst_strong(doc):
     """Replaces *foo* by @strong{foo}"""
@@ -103,9 +98,7 @@ def texi_format(doc):
         #
         # Make sure to update section "Documentation markup" in
         # docs/devel/qapi-code-gen.txt when fixing this.
-        if line.startswith('| '):
-            line = EXAMPLE_FMT(code=line[2:])
-        elif line.startswith('= '):
+        if line.startswith('= '):
             line = '@section ' + line[2:]
         elif line.startswith('== '):
             line = '@subsection ' + line[3:]
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 5fcca8dc85..d3ddf828ef 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -28,8 +28,12 @@
 #
 # - another item
 #
-# | example
-# | multiple lines
+# !texinfo
+# @verbatim
+# example
+# multiple lines
+# @end verbatim
+# !end texinfo
 #
 # !texinfo
 # @table @samp
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 7c4aecbaa2..f0ba51db4b 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -56,8 +56,12 @@ is numbered
 
 - another item
 
-| example
-| multiple lines
+!texinfo
+@verbatim
+example
+multiple lines
+@end verbatim
+!end texinfo
 
 !texinfo
 @table @samp
diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
index b7171ff6d1..4a9162c2a2 100644
--- a/tests/qapi-schema/doc-good.texi
+++ b/tests/qapi-schema/doc-good.texi
@@ -35,13 +35,11 @@ is numbered
 @item
 another item
 
-@example
+@verbatim
 example
-@end example
-
-@example
 multiple lines
-@end example
+@end verbatim
+@end enumerate
 
 
 @table @samp
@@ -52,8 +50,6 @@ This is the text for
 @item bar
 Text for @samp{bar}.
 @end table
-@end enumerate
-
 
 Returns: the King
 Since: the first age
-- 
2.13.6