[Qemu-devel] [RFC PATCH 05/32] qapi2texi: Provide access to Texinfo markup

[Markus Armbruster <armbru@redhat.com>]

qapi2texi supports very limited formatting markup reminiscent of
MarkDown, which it translates to Texinfo.  It's basically defined by
example, and has multiple issues, in particular with lists.
Nevertheless, it has served our (modest) needs so far.

However, our needs are about to grow: I'm going to move command line
documentation from qemu-options.hx into schema doc comments, similar
to how we moved QMP documentation in merge commit 23eb9e6.  The QMP
documentation was plain text, and the markup was created to make it
look decent in generated Texinfo with minimal change.  The command
line documentation is already in Texinfo.  Dumbing it down to what
qapi2texi supports would be a lot of work, for a sad result.  Making
qapi2texi sufficiently powerful for a non-sad result would also be a
lot of work, and stupid; the world doesn't need more text markup
languages.  Not even more text markup language implementations.

Supporting Texinfo in doc comments would be ideal.  Can't do, since we
blew the '@' character on schema name references.  Instead, let's try
the stupidest solution that could possibly work: provide an escape to
Texinfo.  Looks like this:

    # !texinfo
    # @c This is Texinfo
    # @appendix Tips and Tricks
    # !end texinfo

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.txt    | 13 +++++++++++++
 scripts/qapi2texi.py            | 19 ++++++++++++++++---
 tests/qapi-schema/doc-good.json | 11 +++++++++++
 tests/qapi-schema/doc-good.out  | 11 +++++++++++
 tests/qapi-schema/doc-good.texi |  9 +++++++++
 5 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index f04c63fe82..0334ef37ef 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -97,6 +97,9 @@ permitted.
 do not work over multiple lines). @foo is used to reference a name in
 the schema.
 
+You can also embed Texinfo markup.  '!texinfo' switches to Texinfo,
+and '!end texinfo' switches back.
+
 Example:
 
 ##
@@ -112,6 +115,16 @@ Example:
 # | -> do this
 # | <- get that
 #
+# Texinfo markup:
+# !texinfo
+# @table @samp
+# @item foo
+# This is the text for
+# @samp{foo}.
+# @item bar
+# Text for @samp{bar}.
+# @end table
+# !end texinfo
 ##
 
 
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
index cfcd8a19f0..e356f911bb 100755
--- a/scripts/qapi2texi.py
+++ b/scripts/qapi2texi.py
@@ -74,14 +74,27 @@ def texi_format(doc):
     - */-: generates an @itemize list
     """
     ret = ''
-    doc = subst_special(doc)
-    doc = subst_emph(doc)
-    doc = subst_strong(doc)
     inlist = ''
+    intexi = False
     lastempty = False
+
     for line in doc.split('\n'):
         empty = line == ''
 
+        if not intexi and line == '!texinfo':
+            intexi = True
+            continue
+        if intexi and line == '!end texinfo':
+            intexi = False
+            continue
+        if intexi:
+            ret += line + '\n'
+            continue
+
+        line = subst_special(line)
+        line = subst_emph(line)
+        line = subst_strong(line)
+
         # FIXME: Doing this in a single if / elif chain is
         # problematic.  For instance, a line without markup terminates
         # a list if it follows a blank line (reaches the final elif),
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 274004a8b6..5fcca8dc85 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -31,6 +31,17 @@
 # | example
 # | multiple lines
 #
+# !texinfo
+# @table @samp
+# @item foo
+# This is the text for
+# @samp{foo}.
+#
+# @item bar
+# Text for @samp{bar}.
+# @end table
+# !end texinfo
+#
 # Returns: the King
 # Since: the first age
 # Notes:
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 46261d5010..7c4aecbaa2 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -59,6 +59,17 @@ is numbered
 | example
 | multiple lines
 
+!texinfo
+@table @samp
+@item foo
+This is the text for
+@samp{foo}.
+
+@item bar
+Text for @samp{bar}.
+@end table
+!end texinfo
+
 Returns: the King
 Since: the first age
 Notes:
diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.texi
index 8777cbb7fb..b7171ff6d1 100644
--- a/tests/qapi-schema/doc-good.texi
+++ b/tests/qapi-schema/doc-good.texi
@@ -44,8 +44,17 @@ multiple lines
 @end example
 
 
+@table @samp
+@item foo
+This is the text for
+@samp{foo}.
+
+@item bar
+Text for @samp{bar}.
+@end table
 @end enumerate
 
+
 Returns: the King
 Since: the first age
 Notes:
-- 
2.13.6