@@ -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
@@ -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.
@@ -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:]
@@ -28,8 +28,12 @@
#
# - another item
#
-# | example
-# | multiple lines
+# !texinfo
+# @verbatim
+# example
+# multiple lines
+# @end verbatim
+# !end texinfo
#
# !texinfo
# @table @samp
@@ -56,8 +56,12 @@ is numbered
- another item
-| example
-| multiple lines
+!texinfo
+@verbatim
+example
+multiple lines
+@end verbatim
+!end texinfo
!texinfo
@table @samp
@@ -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
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(-)