[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [RFC PATCH 06/32] qapi2texi: Drop | example markup
From: |
Markus Armbruster |
Subject: |
[Qemu-devel] [RFC PATCH 06/32] qapi2texi: Drop | example markup |
Date: |
Mon, 2 Oct 2017 17:25:26 +0200 |
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 <address@hidden>
---
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}
address@hidden 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
address@hidden
+example
+multiple lines
address@hidden 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
address@hidden
address@hidden
example
address@hidden example
-
address@hidden
multiple lines
address@hidden example
address@hidden verbatim
address@hidden enumerate
@table @samp
@@ -52,8 +50,6 @@ This is the text for
@item bar
Text for @samp{bar}.
@end table
address@hidden enumerate
-
Returns: the King
Since: the first age
--
2.13.6
- [Qemu-devel] [RFC PATCH 16/32] qapi: Factor out _make_implicit_wrapper_type(), (continued)
- [Qemu-devel] [RFC PATCH 16/32] qapi: Factor out _make_implicit_wrapper_type(), Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 01/32] tests/qapi-schema: Improve coverage of '@', Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 04/32] qapi2texi: Fix for '@' not followed by \w character, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 09/32] qapi: check_type() parameter allow_optional is now unused, drop, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 13/32] qapi: Use argparse to open schema file, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 06/32] qapi2texi: Drop | example markup,
Markus Armbruster <=
- [Qemu-devel] [RFC PATCH 29/32] qapi/options: QAPIfy --echr argument type, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 32/32] qapi/options: QAPIfy --add-fd argument type, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 22/32] qapi: New helper c_string(), Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 30/32] qapi/options: QAPIfy --watchdog-action argument type, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 08/32] qapi: Simplify check_name() parameters, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 10/32] qapi: Don't run generators twice, Markus Armbruster, 2017/10/02
- [Qemu-devel] [RFC PATCH 31/32] qapi/options: QAPIfy --blockdev argument type, Markus Armbruster, 2017/10/02