From nobody Tue Feb 10 16:22:44 2026 Delivered-To: importer@patchew.org Received-SPF: temperror (zoho.com: Error in retrieving data from DNS) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@gnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=temperror (zoho.com: Error in retrieving data from DNS) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@gnu.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1506959250152210.987433653194; Mon, 2 Oct 2017 08:47:30 -0700 (PDT) Received: from localhost ([::1]:52916 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dz2w6-0001aF-Am for importer@patchew.org; Mon, 02 Oct 2017 11:47:14 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:38927) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dz2bh-00083B-UG for qemu-devel@nongnu.org; Mon, 02 Oct 2017 11:26:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dz2ba-0007vr-H1 for qemu-devel@nongnu.org; Mon, 02 Oct 2017 11:26:09 -0400 Received: from mx1.redhat.com ([209.132.183.28]:49480) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dz2ba-0007ul-6O for qemu-devel@nongnu.org; Mon, 02 Oct 2017 11:26:02 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 0F9F781E15; Mon, 2 Oct 2017 15:26:01 +0000 (UTC) Received: from blackfin.pond.sub.org (ovpn-116-91.ams2.redhat.com [10.36.116.91]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 04F155C544; Mon, 2 Oct 2017 15:25:58 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 91E42115626F; Mon, 2 Oct 2017 17:25:52 +0200 (CEST) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 0F9F781E15 Authentication-Results: ext-mx01.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx01.extmail.prod.ext.phx2.redhat.com; spf=fail smtp.mailfrom=armbru@redhat.com From: Markus Armbruster To: qemu-devel@nongnu.org Date: Mon, 2 Oct 2017 17:25:25 +0200 Message-Id: <20171002152552.27999-6-armbru@redhat.com> In-Reply-To: <20171002152552.27999-1-armbru@redhat.com> References: <20171002152552.27999-1-armbru@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.25]); Mon, 02 Oct 2017 15:26:01 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [RFC PATCH 05/32] qapi2texi: Provide access to Texinfo markup X-BeenThere: qemu-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: marcandre.lureau@redhat.com, mdroth@linux.vnet.ibm.com Errors-To: qemu-devel-bounces+importer=patchew.org@gnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_6 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 --- 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. =20 +You can also embed Texinfo markup. '!texinfo' switches to Texinfo, +and '!end texinfo' switches back. + Example: =20 ## @@ -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 ## =20 =20 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 =3D '' - doc =3D subst_special(doc) - doc =3D subst_emph(doc) - doc =3D subst_strong(doc) inlist =3D '' + intexi =3D False lastempty =3D False + for line in doc.split('\n'): empty =3D line =3D=3D '' =20 + if not intexi and line =3D=3D '!texinfo': + intexi =3D True + continue + if intexi and line =3D=3D '!end texinfo': + intexi =3D False + continue + if intexi: + ret +=3D line + '\n' + continue + + line =3D subst_special(line) + line =3D subst_emph(line) + line =3D 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.j= son 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 =20 +!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.t= exi 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 =20 =20 +@table @samp +@item foo +This is the text for +@samp{foo}. + +@item bar +Text for @samp{bar}. +@end table @end enumerate =20 + Returns: the King Since: the first age Notes: --=20 2.13.6