[{"id":3682018,"web_url":"http://patchwork.ozlabs.org/comment/3682018/","msgid":"<87mrysr08h.fsf@pond.sub.org>","list_archive_url":null,"date":"2026-04-24T12:50:22","subject":"Re: [PATCH 00/12] qapi: add formal \"intro\" section","submitter":{"id":2645,"url":"http://patchwork.ozlabs.org/api/people/2645/","name":"Markus Armbruster","email":"armbru@redhat.com"},"content":"John Snow writes:\n\n> Hiya, this is a series that explores a potential syntax for a\n> designated \"Intro\" section. Markus knows why I want this, but for\n> everyone else: a designated \"Introduction\" section is useful for the\n> desired \"inliner\" feature for the new QAPI doc system. Commits explain\n> a bit more. This is prep work and doesn't really change anything\n> tangibly except source code syntax for the QAPI docs.\n\nLet me elaborate a bit.\n\n1. Why \"intro\"?\n\nGenerated documentation often refers to types like this:\n\n Command announce-self (Since: 4.0)\n\n Trigger generation of broadcast RARP frames to update network\n switches. This can be useful when network bonds fail-over the\n active slave.\n\n Arguments:\n * The members of \"AnnounceParameters\".\n\n Example::\n\n -> { \"execute\": \"announce-self\",\n \"arguments\": {\n \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n <- { \"return\": {} }\n\nThe arguments are hidden behind link \"AnnounceParameters\". Following\nleads to:\n\n Object AnnounceParameters (Since: 4.0)\n\n Parameters for self-announce timers\n\n Members:\n * initial (\"int\") -- Initial delay (in ms) before sending\n the first GARP/RARP announcement\n\n * max (\"int\") -- Maximum delay (in ms) between GARP/RARP\n announcement packets\n\n * rounds (\"int\") -- Number of self-announcement attempts\n\n * step (\"int\") -- Delay increase (in ms) after each self-\n announcement attempt\n\n * interfaces (\"[string]\", *optional*) -- An optional list of\n interface names, which restricts the announcement to the\n listed interfaces. (Since 4.1)\n\n * id (\"string\", *optional*) -- A name to be used to identify\n an instance of announce-timers and to allow it to modified\n later. Not for use as part of the migration parameters.\n (Since 4.1)\n\nThis is bad UX. Especially when you have to chase multiple links.\n\nJohn's doc inliner inlines AnnounceParameters documentation into\nannounce-self documentation.\n\nHowever, we don't want to inline \"Parameters for self-announce timers\".\n\nDefinitions typically start with a short description of the thing being\ndefined. John calls this \"intro\". We don't want to inline these.\n\nSyntactically, a doc comment begins with optional plain paragraphs.\nThese end when something else begins: argument or member description,\ntagged section such as \"Returns:\", ...\n\nMost of the time, these initial paragraphs are exactly the \"intro\". But\nnot always.\n\nEven without the inliner, we often need to know where \"intro\" ends. In\nthe example above, \"Arguments:\" is auto-generated right after the\n\"intro\", and for that, the generator needs to know where \"intro\" ends.\n\nIn his \"qapi: enforce section ordering\" series, John proposed syntax to\nexplicitly end \"intro\": a line \"Details:\". He had to add it to roughly\none in 25 definition docs.\n\nI fear adding \"Details:\" when needed is easily forgotten when it's so\nrarely needed. And I don't even trust myself to catch it patch review.\nSo we looked for clearer syntax.\n\nThis series implements one: instead of letting intro end when something\nelse starts, use indentation like we do for descriptions and tagged\nsections.\n\nLet's have a look at the current doc source for announce-self:\n\n ##\n # @announce-self:\n #\n # Trigger generation of broadcast RARP frames to update network\n # switches. This can be useful when network bonds fail-over the\n # active slave.\n #\n # TODO: This line is a hack to separate the example from the body\n #\n # .. qmp-example::\n #\n # -> { \"execute\": \"announce-self\",\n # \"arguments\": {\n # \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n # \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n # <- { \"return\": {} }\n #\n # Since: 4.0\n ##\n\n\"Intro\" ends when something else starts, namely the TODO: section. We\nneed this hack so the doc generator inserts the \"Arguments:\" part where\nwe want it.\n\nJohn's \"qapi: enforce section ordering\" series replaces the TODO hack\nwith a \"Details:\" line.\n\nIn new syntax, this instead becomes:\n\n ##\n # @announce-self: Trigger generation of broadcast RARP frames to\n # update network switches. This can be useful when network bonds\n # fail-over the active slave.\n #\n # .. qmp-example::\n #\n # -> { \"execute\": \"announce-self\",\n # \"arguments\": {\n # \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n # \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n # <- { \"return\": {} }\n #\n # Since: 4.0\n ##\n\nNow \"intro\" is indented, and its end is obvious. Mistakes seem\nunlikely.\n\nWe could instead do:\n\n ##\n # @announce-self:\n # Trigger generation of broadcast RARP frames to update network\n # switches. This can be useful when network bonds fail-over the\n # active slave.\n #\n # .. qmp-example::\n #\n # -> { \"execute\": \"announce-self\",\n # \"arguments\": {\n # \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n # \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n # <- { \"return\": {} }\n #\n # Since: 4.0\n ##\n\nI think I like this a bit better.\n\n> It is designed so that this conversion can happen incrementally with\n> no actual difference to the rendered manuals, so each QAPI module can\n> be converted one at a time for easier review and merging in an\n> arbitrary order.\n\nWhy not wholesale conversion? As long as generated output stays the\nsame. It does in this series, except for harmless line breaks.\n\n> This series demonstrates conversion of just four modules; if I'm given\n> a thumbs up, I will convert the rest of QAPI, one module (or\n> maintainer stanza) per patch like how I handled adding\n> cross-references.","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@legolas.ozlabs.org","Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=BBb+cOzn;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists1p.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g2CWY64Dvz1yD5\n\tfor ; Fri, 24 Apr 2026 22:51:20 +1000 (AEST)","from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists1p.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from )\n\tid 1wGFzX-0004it-W8; Fri, 24 Apr 2026 08:50:45 -0400","from eggs.gnu.org ([2001:470:142:3::10])\n by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wGFzV-0004ij-RH\n for qemu-devel@nongnu.org; Fri, 24 Apr 2026 08:50:41 -0400","from us-smtp-delivery-124.mimecast.com ([170.10.129.124])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wGFzU-0005ie-2l\n for qemu-devel@nongnu.org; Fri, 24 Apr 2026 08:50:41 -0400","from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com\n (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by\n relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3,\n cipher=TLS_AES_256_GCM_SHA384) id us-mta-541-fZSPBJFkPPCY5m6kZxFJdg-1; Fri,\n 24 Apr 2026 08:50:28 -0400","from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com\n (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest\n SHA256)\n (No client certificate requested)\n by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS\n id 0497319560B4; Fri, 24 Apr 2026 12:50:26 +0000 (UTC)","from blackfin.pond.sub.org (unknown [10.44.22.30])\n by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with\n ESMTPS\n id 4664F180047F; Fri, 24 Apr 2026 12:50:25 +0000 (UTC)","by blackfin.pond.sub.org (Postfix, from userid 1000)\n id D132321E6A28; Fri, 24 Apr 2026 14:50:22 +0200 (CEST)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1777035037;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:content-type:content-type:\n in-reply-to:in-reply-to:references:references;\n bh=1mq4sHshCqBAlZJwGMlczxv6eprNBC2Y5bjdVsccY+w=;\n b=BBb+cOznFli2H9ynXGwRhppwybZpsM5LMCT5eC++SgEyarsc6AnelBawp+GT5Bj3PG00IS\n 05qbix9Xc61f/101KMjkclbn7asEzYrPtBviDBQFu7xsnXEpG8m7gZkVpX/3mqRUjkRcwW\n 5kPjY0rVxSm1pBKUZPsB+oAjeiVdIcg=","X-MC-Unique":"fZSPBJFkPPCY5m6kZxFJdg-1","X-Mimecast-MFC-AGG-ID":"fZSPBJFkPPCY5m6kZxFJdg_1777035026","From":"Markus Armbruster ","To":"John Snow ","Cc":"qemu-devel@nongnu.org, Igor Mammedov ,\n Mauro Carvalho Chehab ,\n \"Michael S. Tsirkin\" , Michael Roth ,\n Ani Sinha , Gerd Hoffmann ,\n Eric Blake ,\n Pierrick Bouvier , Philippe\n\t=?utf-8?q?Mathieu-Daud=C3=A9?= , =?utf-8?q?Marc-Andr?=\n\t=?utf-8?q?=C3=A9?= Lureau ,\n Richard Henderson ,\n Paolo Bonzini ,\n Peter Maydell ","Subject":"Re: [PATCH 00/12] qapi: add formal \"intro\" section","In-Reply-To":"<20260423220022.2180059-1-jsnow@redhat.com> (John Snow's message\n of \"Thu, 23 Apr 2026 18:00:09 -0400\")","References":"<20260423220022.2180059-1-jsnow@redhat.com>","Date":"Fri, 24 Apr 2026 14:50:22 +0200","Message-ID":"<87mrysr08h.fsf@pond.sub.org>","User-Agent":"Gnus/5.13 (Gnus v5.13)","MIME-Version":"1.0","Content-Type":"text/plain","X-Scanned-By":"MIMEDefang 3.4.1 on 10.30.177.111","Received-SPF":"pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com","X-Spam_score_int":"12","X-Spam_score":"1.2","X-Spam_bar":"+","X-Spam_report":"(1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001,\n RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001,\n SPF_PASS=-0.001 autolearn=no autolearn_force=no","X-Spam_action":"no action","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"qemu development ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org"}},{"id":3682019,"web_url":"http://patchwork.ozlabs.org/comment/3682019/","msgid":"","list_archive_url":null,"date":"2026-04-24T12:52:21","subject":"Re: [PATCH 00/12] qapi: add formal \"intro\" section","submitter":{"id":64343,"url":"http://patchwork.ozlabs.org/api/people/64343/","name":"John Snow","email":"jsnow@redhat.com"},"content":"On Fri, Apr 24, 2026, 8:50 AM Markus Armbruster wrote:\n\n> John Snow writes:\n>\n> > Hiya, this is a series that explores a potential syntax for a\n> > designated \"Intro\" section. Markus knows why I want this, but for\n> > everyone else: a designated \"Introduction\" section is useful for the\n> > desired \"inliner\" feature for the new QAPI doc system. Commits explain\n> > a bit more. This is prep work and doesn't really change anything\n> > tangibly except source code syntax for the QAPI docs.\n>\n> Let me elaborate a bit.\n>\n> 1. Why \"intro\"?\n>\n> Generated documentation often refers to types like this:\n>\n> Command announce-self (Since: 4.0)\n>\n> Trigger generation of broadcast RARP frames to update network\n> switches. This can be useful when network bonds fail-over the\n> active slave.\n>\n> Arguments:\n> * The members of \"AnnounceParameters\".\n>\n> Example::\n>\n> -> { \"execute\": \"announce-self\",\n> \"arguments\": {\n> \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n> \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n> <- { \"return\": {} }\n>\n> The arguments are hidden behind link \"AnnounceParameters\". Following\n> leads to:\n>\n> Object AnnounceParameters (Since: 4.0)\n>\n> Parameters for self-announce timers\n>\n> Members:\n> * initial (\"int\") -- Initial delay (in ms) before sending\n> the first GARP/RARP announcement\n>\n> * max (\"int\") -- Maximum delay (in ms) between GARP/RARP\n> announcement packets\n>\n> * rounds (\"int\") -- Number of self-announcement attempts\n>\n> * step (\"int\") -- Delay increase (in ms) after each self-\n> announcement attempt\n>\n> * interfaces (\"[string]\", *optional*) -- An optional list of\n> interface names, which restricts the announcement to the\n> listed interfaces. (Since 4.1)\n>\n> * id (\"string\", *optional*) -- A name to be used to identify\n> an instance of announce-timers and to allow it to modified\n> later. Not for use as part of the migration parameters.\n> (Since 4.1)\n>\n> This is bad UX. Especially when you have to chase multiple links.\n>\n> John's doc inliner inlines AnnounceParameters documentation into\n> announce-self documentation.\n>\n> However, we don't want to inline \"Parameters for self-announce timers\".\n>\n> Definitions typically start with a short description of the thing being\n> defined. John calls this \"intro\". We don't want to inline these.\n>\n> Syntactically, a doc comment begins with optional plain paragraphs.\n> These end when something else begins: argument or member description,\n> tagged section such as \"Returns:\", ...\n>\n> Most of the time, these initial paragraphs are exactly the \"intro\". But\n> not always.\n>\n> Even without the inliner, we often need to know where \"intro\" ends. In\n> the example above, \"Arguments:\" is auto-generated right after the\n> \"intro\", and for that, the generator needs to know where \"intro\" ends.\n>\n> In his \"qapi: enforce section ordering\" series, John proposed syntax to\n> explicitly end \"intro\": a line \"Details:\". He had to add it to roughly\n> one in 25 definition docs.\n>\n> I fear adding \"Details:\" when needed is easily forgotten when it's so\n> rarely needed. And I don't even trust myself to catch it patch review.\n> So we looked for clearer syntax.\n>\n> This series implements one: instead of letting intro end when something\n> else starts, use indentation like we do for descriptions and tagged\n> sections.\n>\n> Let's have a look at the current doc source for announce-self:\n>\n> ##\n> # @announce-self:\n> #\n> # Trigger generation of broadcast RARP frames to update network\n> # switches. This can be useful when network bonds fail-over the\n> # active slave.\n> #\n> # TODO: This line is a hack to separate the example from the body\n> #\n> # .. qmp-example::\n> #\n> # -> { \"execute\": \"announce-self\",\n> # \"arguments\": {\n> # \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n> # \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n> # <- { \"return\": {} }\n> #\n> # Since: 4.0\n> ##\n>\n> \"Intro\" ends when something else starts, namely the TODO: section. We\n> need this hack so the doc generator inserts the \"Arguments:\" part where\n> we want it.\n>\n> John's \"qapi: enforce section ordering\" series replaces the TODO hack\n> with a \"Details:\" line.\n>\n> In new syntax, this instead becomes:\n>\n> ##\n> # @announce-self: Trigger generation of broadcast RARP frames to\n> # update network switches. This can be useful when network bonds\n> # fail-over the active slave.\n> #\n> # .. qmp-example::\n> #\n> # -> { \"execute\": \"announce-self\",\n> # \"arguments\": {\n> # \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n> # \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n> # <- { \"return\": {} }\n> #\n> # Since: 4.0\n> ##\n>\n> Now \"intro\" is indented, and its end is obvious. Mistakes seem\n> unlikely.\n>\n> We could instead do:\n>\n> ##\n> # @announce-self:\n> # Trigger generation of broadcast RARP frames to update network\n> # switches. This can be useful when network bonds fail-over the\n> # active slave.\n> #\n> # .. qmp-example::\n> #\n> # -> { \"execute\": \"announce-self\",\n> # \"arguments\": {\n> # \"initial\": 50, \"max\": 550, \"rounds\": 10, \"step\": 50,\n> # \"interfaces\": [\"vn2\", \"vn3\"], \"id\": \"bob\" } }\n> # <- { \"return\": {} }\n> #\n> # Since: 4.0\n> ##\n>\n> I think I like this a bit better.\n>\n> > It is designed so that this conversion can happen incrementally with\n> > no actual difference to the rendered manuals, so each QAPI module can\n> > be converted one at a time for easier review and merging in an\n> > arbitrary order.\n>\n> Why not wholesale conversion? As long as generated output stays the\n> same. It does in this series, except for harmless line breaks.\n>\n\nWhen we last spoke, we weren't convinced this was the right approach and we\nboth wanted to see it. So I did enough to get a taste.\n\n\n> > This series demonstrates conversion of just four modules; if I'm given\n> > a thumbs up, I will convert the rest of QAPI, one module (or\n> > maintainer stanza) per patch like how I handled adding\n> > cross-references.\n>\n>","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@legolas.ozlabs.org","Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=ehDy0h4V;\n\tdkim=pass (2048-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=google header.b=sG9vNsXc;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists1p.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g2CYV12mMz1yD5\n\tfor ; Fri, 24 Apr 2026 22:53:02 +1000 (AEST)","from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists1p.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from )\n\tid 1wGG1X-00059w-4X; Fri, 24 Apr 2026 08:52:47 -0400","from eggs.gnu.org ([2001:470:142:3::10])\n by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wGG1T-00059R-Nv\n for qemu-devel@nongnu.org; Fri, 24 Apr 2026 08:52:45 -0400","from us-smtp-delivery-124.mimecast.com ([170.10.129.124])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wGG1R-0006DC-8d\n for qemu-devel@nongnu.org; Fri, 24 Apr 2026 08:52:43 -0400","from mail-yw1-f199.google.com (mail-yw1-f199.google.com\n [209.85.128.199]) by relay.mimecast.com with ESMTP with STARTTLS\n (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id\n us-mta-329-oyMPRGRlPWa8i05Wv8COTA-1; Fri, 24 Apr 2026 08:52:33 -0400","by mail-yw1-f199.google.com with SMTP id\n 00721157ae682-7a45cf7ff24so125017847b3.0\n for ; Fri, 24 Apr 2026 05:52:33 -0700 (PDT)"],"DKIM-Signature":["v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1777035160;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:content-type:content-type:\n in-reply-to:in-reply-to:references:references;\n bh=PvpqaD5pQprg8kQpCjG4/3zKp7IuXHWAAtigm1MC0zo=;\n b=ehDy0h4Vksul3dir3x5uVxSkwiZhoexqclgC7RihQntODytZMiWX1gvqYjubEN9B3em+7W\n L8pBGaAIYLvG7TmBOLZdxQXG4Tmw+Gq0UksxQX5XB8Y7NohOVp42SDZdeGmS4qUVDB2Pil\n Opa8TP7P7oW7DYK+LPu9AMQmPuurNlM=","v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=redhat.com; s=google; t=1777035153; x=1777639953; darn=nongnu.org;\n h=cc:to:subject:message-id:date:from:in-reply-to:references\n :mime-version:from:to:cc:subject:date:message-id:reply-to;\n bh=PvpqaD5pQprg8kQpCjG4/3zKp7IuXHWAAtigm1MC0zo=;\n b=sG9vNsXc5ZOS6HhUsJWxG8P0imwl9DTxDHUHtjCve8vwlBOjqJ65HQtbeJCOCm1YlR\n L2NLjWnx4YxyLAzt6sxMRo3x70Npx4+AFJ025XRZKf+rm6ertCM54gvKY59OQgu2g990\n Sdu67X1xgr3FP4CJxJM/TuTxYtCp37EAaoRfMpnXVEOtddZ+cLWyYp30Ev3pcN5EnFQZ\n a0/QXBFbxgdn/gQRa7LRqnrk7GSDlkN0a3JmifLK3zfD0sfdJXjePVcvmjMtG/qdowys\n ixigV3g6cSokOtWClg5OWcrjhS6MeAdzifbiESeI/dpIQ5hHEUaRDuRCJhEpYqx1rOro\n iuXw=="],"X-MC-Unique":"oyMPRGRlPWa8i05Wv8COTA-1","X-Mimecast-MFC-AGG-ID":"oyMPRGRlPWa8i05Wv8COTA_1777035153","ARC-Seal":"i=1; a=rsa-sha256; t=1777035153; cv=none;\n d=google.com; s=arc-20240605;\n b=gA7d2ZhEulf1kMSUAljdBq14NjqbTVUGXOPO+xmqylJUUsqWePNZOL3ykYZ031yNVB\n MeiO7OjAZvtQcEO/lUXARM5HFRRxL1ec18JZ9a8xAB7QF68JLJdTGDqx6ClnPeZjfbIt\n VWVCe3ZHQndDTAJUmKWtaFLGDVIO0L+xeJGTPY+jypNwPQRwRND+bIjTAH7bXjzuWDq5\n xjSLPVb2yYtFWIQZrHDx1SOz3+mn4RYRw0DWiCVUcpdNYxp9plCC7gSSNDZcby9+WlGM\n cEdlK4dsS6qX8DS+GSMBwiX6Yoto8eMKJATMxGt5HwHl1SldNgiCXO3JutixBXLt4cy0\n kMQg==","ARC-Message-Signature":"i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com;\n s=arc-20240605;\n h=cc:to:subject:message-id:date:from:in-reply-to:references\n :mime-version:dkim-signature;\n bh=PvpqaD5pQprg8kQpCjG4/3zKp7IuXHWAAtigm1MC0zo=;\n fh=FokTuDZJP0b72MuyfYB6pDu1SUcEvdw8SifBRO2CIB0=;\n b=FCnwLczuFiF7Vxn+ito0HWsC7FDQFmH0j87+3q3Z+RUZY6bSYXYoF3/l2mFi8M/pSQ\n m5FN48xi7WcgbhWb/0EpT9E23LmTkjCCno7J6hbUaEwtIWHpRJ2g73mX42uOHhD6xjv3\n smob4aiABOp2yH1RNuOsLs8gUscaRZyNdivJd2dtx2dcSXS8FuCLF8ZB4BtFTJIdfQHM\n Im06S4uFx4iBNNhLxJ9+QJXnX3czPy+ZNT+j8emi+NkhXqxcrbXJiJC3X/lRfEfHZXHk\n g4jFif7a+9N6c1P3aiZ2c40TxALqxZ0SvT+kBlPJqiW3Cv241oZsogOIb6F8y6GQJa26\n zt9Q==; darn=nongnu.org","ARC-Authentication-Results":"i=1; mx.google.com; arc=none","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n d=1e100.net; s=20251104; t=1777035153; x=1777639953;\n h=cc:to:subject:message-id:date:from:in-reply-to:references\n :mime-version:x-gm-gg:x-gm-message-state:from:to:cc:subject:date\n :message-id:reply-to;\n bh=PvpqaD5pQprg8kQpCjG4/3zKp7IuXHWAAtigm1MC0zo=;\n b=gyVgUgGwOa9kwXpVmQ+2IYkjZ0WZduZTFYHT/nHOBZJOQMfpSs7gjytZQEKsK3ix10\n eEtcASlqhY+PgIvufodr4iHb7OCZQ0GrPT9W+CGDAMasbYJm1+vpLaMEOLGfG0KrTuJ3\n 5+ppMs0eImxdlZslYdKKaZF08jVgB1k28EbzIj+4H4wo3LFkptPxjb6ghFGNB4Hu3aAl\n xpb5vOoj9quomSUY2F7ku/wrEew6BCc4z54Rur9+uHuje5saCaNunXQ75/ErhIFmYVdV\n 3emcOFkk9JqOZd9IGw5f7nNZx6SyWp9Ll+pkvOHTZBxyVBWEEnHdFRUA2bm9TLGjZ7Zy\n gpRA==","X-Gm-Message-State":"AOJu0Yw6/s4AoD6836cMsRRkuGJvLumTDw9dT6JZYpBCFoB0nV3me24r\n IsUs2GlF24oIO7vusFjl7pjWTTA93wDJHv8vamMX1VGfQAeBm7BcIhnVa4+DGQqI/hlkZl+j/PL\n y6x7xBukNMEH9YxCPOMMyXgQCvuZUJtEmxUf9QPprQoVBbt/PpA1Zmv6zHXJf/LOrJR3oCaCW04\n HVIxG1QbGEeOy4NNCZ6K3pK59+ferA+AI=","X-Gm-Gg":"AeBDiev4ozOhimvGT/hppCDNRmoaOvA141v4pOUw/EFaruJwoiEej+6qRtYZb82yLR5\n QF4R/0gfXyXwiPxXCaX82yo4Rb7ujrYCH82i6RS7lPB8U1Hg5OQTJkeyv0CCg+cYlw465VkLOLd\n irdWQa+Pt5MaiRqcDLJbOtYQpMNYqeQfGCHIkinJ3XvB+CJtjiUQCqDU8nLW9zHpoSxA+VznWoG\n COssVECCbHKOn+y4SvtX4/GfeaccZQejRw/xpXwVg3437l9","X-Received":["by 2002:a05:690c:6612:b0:7ba:f712:95f6 with SMTP id\n 00721157ae682-7baf712b9abmr197749377b3.3.1777035153118;\n Fri, 24 Apr 2026 05:52:33 -0700 (PDT)","by 2002:a05:690c:6612:b0:7ba:f712:95f6 with SMTP id\n 00721157ae682-7baf712b9abmr197748987b3.3.1777035152543; Fri, 24 Apr 2026\n 05:52:32 -0700 (PDT)"],"MIME-Version":"1.0","References":"<20260423220022.2180059-1-jsnow@redhat.com>\n <87mrysr08h.fsf@pond.sub.org>","In-Reply-To":"<87mrysr08h.fsf@pond.sub.org>","From":"John Snow ","Date":"Fri, 24 Apr 2026 08:52:21 -0400","X-Gm-Features":"AQROBzAue56kt90Qnr7z4lUjKCYxd5V-YJRR_92zjlz9j06kiCP3YVjHG6mGrYg","Message-ID":"\n ","Subject":"Re: [PATCH 00/12] qapi: add formal \"intro\" section","To":"Markus Armbruster ","Cc":"qemu-devel , Igor Mammedov ,\n Mauro Carvalho Chehab ,\n \"Michael S. Tsirkin\" , Michael Roth ,\n Ani Sinha , Gerd Hoffmann ,\n Eric Blake ,\n Pierrick Bouvier , =?utf-8?q?Philippe_M?=\n\t=?utf-8?q?athieu-Daud=C3=A9?= , =?utf-8?q?Marc-Andr?=\n\t=?utf-8?q?=C3=A9_Lureau?= ,\n Richard Henderson ,\n Paolo Bonzini ,\n Peter Maydell ","Content-Type":"multipart/alternative; boundary=\"00000000000005e59e0650343d5f\"","Received-SPF":"pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com","X-Spam_score_int":"-20","X-Spam_score":"-2.1","X-Spam_bar":"--","X-Spam_report":"(-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001,\n RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001,\n SPF_PASS=-0.001 autolearn=ham autolearn_force=no","X-Spam_action":"no action","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"qemu development ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org"}},{"id":3682036,"web_url":"http://patchwork.ozlabs.org/comment/3682036/","msgid":"<87v7dgpjia.fsf@pond.sub.org>","list_archive_url":null,"date":"2026-04-24T13:37:01","subject":"Re: [PATCH 00/12] qapi: add formal \"intro\" section","submitter":{"id":2645,"url":"http://patchwork.ozlabs.org/api/people/2645/","name":"Markus Armbruster","email":"armbru@redhat.com"},"content":"John Snow writes:\n\n> On Fri, Apr 24, 2026, 8:50 AM Markus Armbruster wrote:\n>\n>> John Snow writes:\n>>\n>> > Hiya, this is a series that explores a potential syntax for a\n>> > designated \"Intro\" section. Markus knows why I want this, but for\n>> > everyone else: a designated \"Introduction\" section is useful for the\n>> > desired \"inliner\" feature for the new QAPI doc system. Commits explain\n>> > a bit more. This is prep work and doesn't really change anything\n>> > tangibly except source code syntax for the QAPI docs.\n\n[...]\n\n>> Why not wholesale conversion? As long as generated output stays the\n>> same. It does in this series, except for harmless line breaks.\n>>\n>\n> When we last spoke, we weren't convinced this was the right approach and we\n> both wanted to see it. So I did enough to get a taste.\n\nYes, and it makes sense.\n\n>> > This series demonstrates conversion of just four modules; if I'm given\n>> > a thumbs up, I will convert the rest of QAPI, one module (or\n>> > maintainer stanza) per patch like how I handled adding\n>> > cross-references.","headers":{"Return-Path":"","X-Original-To":"incoming@patchwork.ozlabs.org","Delivered-To":"patchwork-incoming@legolas.ozlabs.org","Authentication-Results":["legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=JHX7QzHa;\n\tdkim-atps=neutral","legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists1p.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)"],"Received":["from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4g2DYZ0S5Gz1yD5\n\tfor ; Fri, 24 Apr 2026 23:38:08 +1000 (AEST)","from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists1p.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from )\n\tid 1wGGia-0007vU-D2; Fri, 24 Apr 2026 09:37:16 -0400","from eggs.gnu.org ([2001:470:142:3::10])\n by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wGGiY-0007v1-Mf\n for qemu-devel@nongnu.org; Fri, 24 Apr 2026 09:37:14 -0400","from us-smtp-delivery-124.mimecast.com ([170.10.129.124])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from ) id 1wGGiX-0004kR-7B\n for qemu-devel@nongnu.org; Fri, 24 Apr 2026 09:37:14 -0400","from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com\n (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by\n relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3,\n cipher=TLS_AES_256_GCM_SHA384) id us-mta-149-iWA4fUueN8qinANrDlvkKA-1; Fri,\n 24 Apr 2026 09:37:09 -0400","from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com\n (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest\n SHA256)\n (No client certificate requested)\n by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS\n id 9B1D71800473; Fri, 24 Apr 2026 13:37:04 +0000 (UTC)","from blackfin.pond.sub.org (unknown [10.44.22.30])\n by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with\n ESMTPS\n id 219031944CED; Fri, 24 Apr 2026 13:37:04 +0000 (UTC)","by blackfin.pond.sub.org (Postfix, from userid 1000)\n id B503521E6A28; Fri, 24 Apr 2026 15:37:01 +0200 (CEST)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1777037830;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:content-type:content-type:\n content-transfer-encoding:content-transfer-encoding:\n in-reply-to:in-reply-to:references:references;\n bh=J/rxdQEsVEYOTcyQDB2reasoRaxL5y2hz9Y61d7i+zA=;\n b=JHX7QzHazA5HVscWZfzZVD2gIjavpeqG4AZvTqb2+67kf8pMpoNnmYlgfuOAA01/Wb6Dvf\n YwBgv+5pV5DhKxKYHv1yVQVJptndcGb5EtqYGXIgGffLn58mrGG7mlqC6KvqWUzWMQxQ9B\n WrD3U54EX4nV05xWCFI6RFJtk6VBFzk=","X-MC-Unique":"iWA4fUueN8qinANrDlvkKA-1","X-Mimecast-MFC-AGG-ID":"iWA4fUueN8qinANrDlvkKA_1777037824","From":"Markus Armbruster ","To":"John Snow ","Cc":"qemu-devel , Igor Mammedov ,\n Mauro Carvalho Chehab ,\n \"Michael S. Tsirkin\" , Michael Roth ,\n Ani Sinha , Gerd Hoffmann ,\n Eric Blake ,\n Pierrick Bouvier , Philippe\n\t=?utf-8?q?Mathieu-Daud=C3=A9?= , =?utf-8?q?Marc-Andr?=\n\t=?utf-8?q?=C3=A9?= Lureau ,\n Richard Henderson ,\n Paolo Bonzini ,\n Peter Maydell ","Subject":"Re: [PATCH 00/12] qapi: add formal \"intro\" section","In-Reply-To":"\n \n (John Snow's message of \"Fri, 24 Apr 2026 08:52:21 -0400\")","References":"<20260423220022.2180059-1-jsnow@redhat.com>\n <87mrysr08h.fsf@pond.sub.org>\n ","Date":"Fri, 24 Apr 2026 15:37:01 +0200","Message-ID":"<87v7dgpjia.fsf@pond.sub.org>","User-Agent":"Gnus/5.13 (Gnus v5.13)","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Transfer-Encoding":"quoted-printable","X-Scanned-By":"MIMEDefang 3.0 on 10.30.177.17","Received-SPF":"pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com","X-Spam_score_int":"-20","X-Spam_score":"-2.1","X-Spam_bar":"--","X-Spam_report":"(-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001,\n SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no","X-Spam_action":"no action","X-BeenThere":"qemu-devel@nongnu.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"qemu development ","List-Unsubscribe":",\n ","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n ","Errors-To":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org","Sender":"qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org"}}]