From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769535; cv=none; d=zohomail.com; s=zohoarc; b=Cu0ulE7hfz0YDwOR0npZFE2wb3KDiGmI9VdrexhbNFFYo89J+1IkKdO5I7goxLpTnbsPbK8tkGn00aVp+j1gXnW+bqwxcMe8SewggcdxNux6JUVi236QQZMEt/gQLpeQ3lleSKofAYATu9jLR3p1mBs1u7DVhN/mGVZLqZKUD/U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769535; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=1Remaj1t9s0XTf3rYRZM/hkzDh6VUoyVKKSoDw94y+A=; b=oD3O1eldWufEVU0ts8Bx/ElEpOu0bXq/InzBKGEpAdfymWvUfa5DZr97Y75pmTXRz2oFpsUiFCCBh7ouN+MZCbBhP+Hz2whE3vyV9i+4qo/cm6n+SnUq830839kG7VVcgvQwd836k41vaQU0V4gZJX7GWrbc74cdOqsKOxWCxYY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769535424206.2798557187308; Mon, 9 Mar 2020 08:58:55 -0700 (PDT) Received: from localhost ([::1]:45851 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKnr-0007bd-NQ for importer@patchew.org; Mon, 09 Mar 2020 11:58:52 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40268) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZg-0001m9-QD for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:14 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZf-0001KZ-AZ for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:12 -0400 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:50571) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZf-0001K8-3p for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:11 -0400 Received: by mail-wm1-x344.google.com with SMTP id a5so21325wmb.0 for ; Mon, 09 Mar 2020 08:44:11 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=1Remaj1t9s0XTf3rYRZM/hkzDh6VUoyVKKSoDw94y+A=; b=dRqpiM4caG60iyZrtncaCBddMtHWW3mv2niLPgKLAV67o7tUGgBI4InBmBuMgPxED5 V7Bqt+Pl5dOCEJPU8+1NvahLjtZJ33sk7RTt2dJFv4lT4FSvKXKxYYTYc2jr+hCsnry5 y949b7AW+XhLzVan3g3tof55QhBGC+uatExgF1BsdyyabBl9z1kolwsEIeF3jipey3sf 4csG6ssMHHrwHUvVTItR4Qj9735mkbbGlmPemM8D3kmPH9WiML8CT1gL3cXKm0BirgPT CWn35jGnR1OrFJZ1ioT5nkYx6HQEELsrPMrKmWQp11Wt05bvGDHF0RIa/8otUp9zKz2m UqqA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=1Remaj1t9s0XTf3rYRZM/hkzDh6VUoyVKKSoDw94y+A=; b=ExEo5f13386040SeYK4T4WDDRwdnCtIIwzeYdMuvLFpoo5xUXnHA3ZBWQ4HKlRT254 eyWoE2qBAAbl5l6XAVYa9Ykg/xhSAY53KxiPMH002LIN1DpUzbsWLSwYqXhkPhk7IuKN yr3GKx5wtfyXylsjVjymtMPU4tFUtP/u1A6qjyPnXhF2pwJun8NE1GHbmPDNiuOOp054 NcRPS/TzUT0ml/0zysLRc2Zy9Pq3YjN82VllA0HMVocoCjbPoKudtE17b4N7SsHdvVgs SfWRrANDLzY4FB7z2pAQIJjUbjaM8P+5Y5o/kCZc0n2wNwV1IideUvhIsDBXPjN+GCjf lKDg== X-Gm-Message-State: ANhLgQ0nGPcSVxtejaQA9LbX0QOO6wZt0AgVPcJwwQKcvPLhZZxJK9/i 4n/0Rz933BUalbOzvAxlCHVHDUwWtUclxQ== X-Google-Smtp-Source: ADFU+vshtcbK4LjfVuVWhQ3zpobQzarx2FNs39Vdlq3BIElfuiQ5rlWQsIXVVxphfu/2U5Eckjgmcw== X-Received: by 2002:a1c:7419:: with SMTP id p25mr19878558wmc.129.1583768649533; Mon, 09 Mar 2020 08:44:09 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 01/18] qapi/migration.json: Fix indentation Date: Mon, 9 Mar 2020 15:43:48 +0000 Message-Id: <20200309154405.13548-2-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::344 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Commits 6a9ad1542065ca0bd54c6 and 9004db48c080632aef23 added some new text to qapi/migration.json which doesn't fit the stricter indentation requirements imposed by the rST documentation generator. Reindent those lines to the new standard. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster Reviewed-by: Richard Henderson --- qapi/migration.json | 60 ++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index d44d99cd786..53437636a37 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -606,18 +606,18 @@ # Defaults to none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 9, where 0 means no compression, 1 means the be= st +# compression speed, and 9 means best compression rat= io which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 20, where 0 means no compression, 1 means the b= est +# compression speed, and 20 means best compression ra= tio which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # Since: 2.4 ## @@ -726,18 +726,18 @@ # Defaults to none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 9, where 0 means no compression, 1 means the be= st +# compression speed, and 9 means best compression rat= io which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 20, where 0 means no compression, 1 means the b= est +# compression speed, and 20 means best compression ra= tio which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # Since: 2.4 ## @@ -881,18 +881,18 @@ # Defaults to none. (Since 5.0) # # @multifd-zlib-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 9, where 0 means no compression, 1 means the best -# compression speed, and 9 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 9, where 0 means no compression, 1 means the be= st +# compression speed, and 9 means best compression rat= io which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # @multifd-zstd-level: Set the compression level to be used in live -# migration, the compression level is an integer between 0 -# and 20, where 0 means no compression, 1 means the best -# compression speed, and 20 means best compression ratio which -# will consume more CPU. -# Defaults to 1. (Since 5.0) +# migration, the compression level is an integer betw= een 0 +# and 20, where 0 means no compression, 1 means the b= est +# compression speed, and 20 means best compression ra= tio which +# will consume more CPU. +# Defaults to 1. (Since 5.0) # # Since: 2.4 ## --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583768821; cv=none; d=zohomail.com; s=zohoarc; b=OWIcFpW5O2j2VyE3Qw9JZ+8LlcUDa5539YRF24FJrgRSEeKAWOCuU1p3XZ43a9ssxooUOe/QgqolPu4ckf5yeXxwdknUmb65Oog2bnApxmb9Ng5elbwFnYW2hM4MEuw3CMsc5sBmBg0e1hRZt5EG7eLJ95i7sWpgyU1OLVn8ciE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583768821; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=vZTPlHR8mq3OwOYR6l43zxathKAQyqG0FYbXCshk6J4=; b=nOKvLLiYvh3uNWvtYd3Aknl6UazfFzGAXY/2c3Ri/9wBui9PIb0JLGebrr0irrNdWbWYCEGCnDnxDFUf1rulGUhqAiNRryE8T561WzfoftUFlzC8JSGRgvhKOLbllwM6gvLarSWUr9aBfPWj3ob2OFNSUL/b/DGkDVfEzfeSIzE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583768821776103.46701756960476; Mon, 9 Mar 2020 08:47:01 -0700 (PDT) Received: from localhost ([::1]:45506 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKcO-0005Im-At for importer@patchew.org; Mon, 09 Mar 2020 11:47:00 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40284) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZi-0001mb-3q for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:15 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZg-0001L0-Af for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:13 -0400 Received: from mail-wr1-x42a.google.com ([2a00:1450:4864:20::42a]:45079) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZg-0001Kf-3r for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:12 -0400 Received: by mail-wr1-x42a.google.com with SMTP id m9so2818157wro.12 for ; Mon, 09 Mar 2020 08:44:12 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=vZTPlHR8mq3OwOYR6l43zxathKAQyqG0FYbXCshk6J4=; b=yV3O4T38GJ296jT2XsShcbCdHk899fUEXMWo7FekklplR/ot3/eE5vvlZYnIEueKlF wlZ0xwzOXlUKJPPyMpJoFtVMjru1KU8ZsglbnhpOeeJN6fg5mlBQGVY1X9H7F+eZOS2h hqF85/bGL4lYz4NAyEE00R1x5lHtAo85WC9rbULY1oVCR8liy67Q6xPqj9Vn0Vmez0BV dZpv31XXdMl4g8ylnf9r3MTIgD+pYAemW+GYXIDYOD48fGk6vH44C8ueLyDqScvtxAag eSAMAVu/BQIgdWl40LMkWCl8eNhOvfxDfE9tNwoszyFt0Hf/uA93iYGcliT8bl8ECdVq WAMg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=vZTPlHR8mq3OwOYR6l43zxathKAQyqG0FYbXCshk6J4=; b=CqdTG7uMcNQySydkWhOv3x0zroYNPfPwVjE/4Tv2R6MA/K+Yu/4Rxl+Lvr0hjQjyk+ aKwQqkUWCXAgIA63fdg05efMCB3vAm+z4/aMRAHL0xZOvb4UFqqYM/ENmlWniSSK7cUP A2h2Ae2+MBQQJ8reDycpU4OZ62T67g801auDoolIy4I3D4nT5uCY9fCmjM2FFRNcfYdB UsEWgAOTmdANkWHQKGYgJPovqUfmhIHoVCPTh9tnAMNQScI+5EOD6sMa4yGK9KAUqaI1 eX3cfYot6UtFwT4/X1P35M8ZzzXCim1YzUj0Tm4xd/nj0ekWiCzxsrvynevelt4bhAVl dJsg== X-Gm-Message-State: ANhLgQ3hOiHnHciv+uqCyHj8TiecqLAK1x33blHjFP2frJog+vVn8Me3 aeiYZGhauMK+e5SU6YxupWNAynNuio653A== X-Google-Smtp-Source: ADFU+vs+VjQHFDewRRTG/ppdbFhr7bwujgyvlvI/Np0Mph7oCfEEhb3ZWnQ7xYhiBr1Inff3RSC6JA== X-Received: by 2002:a5d:640e:: with SMTP id z14mr7287227wru.204.1583768650824; Mon, 09 Mar 2020 08:44:10 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 02/18] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Date: Mon, 9 Mar 2020 15:43:49 +0000 Message-Id: <20200309154405.13548-3-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42a X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Our current QAPI doc-comment markup allows section headers (introduced with a leading '=3D' or '=3D=3D') anywhere in any documentation comment. This works for texinfo because the texi generator simply prints a texinfo heading directive at that point in the output stream. For rST generation, since we're assembling a tree of docutils nodes, this is awkward because a new section implies starting a new section node at the top level of the tree and generating text into there. New section headings in the middle of the documentation of a command or event would be pretty nonsensical, and in fact we only ever output new headings using 'freeform' doc comment blocks whose only content is the single line of the heading, with two exceptions, which are in the introductory freeform-doc-block at the top of qapi/qapi-schema.json. Split that doc-comment up so that the heading lines are in their own doc-comment. This will allow us to tighten the specification to insist that heading lines are always standalone, rather than requiring the rST document generator to look at every line in a doc comment block and handle headings in odd places. This change makes no difference to the generated texi. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/qapi-schema.json | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index fe980ce4370..ff5aea59451 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -1,7 +1,9 @@ # -*- Mode: Python -*- ## # =3D Introduction -# +## + +## # This document describes all commands currently supported by QMP. # # Most of the time their usage is exactly the same as in the user Monitor,= this @@ -25,9 +27,13 @@ # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. -# +## + +## # =3D Stability Considerations -# +## + +## # The current QMP command set (described in this file) may be useful for a # number of use cases, however it's limited and several commands have bad # defined semantics, specially with regard to command completion. --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769798; cv=none; d=zohomail.com; s=zohoarc; b=J/XW5jz/7uGf3VvYvEHU50c0V0jvNFw/P5tTqUnJDAJUSwkwRTqUDLo6MD+wAJsUTHv3Y5kHv4I3DkurksszeRnpPQYOCeofxCLgaF8yTLPJqas2bTdCqzYctCWtxy5PJ9e1f2f7oqFVAMExqqpyvzUPHxtj3ySHcW+P2LDBNLg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769798; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=rbxvM6zBsEyzHKe8nAvY0XhamX4FQe6hP23LCjFR3Y0=; b=h4q3oEeUir6OHCweQhZMLGc8Iew5KBTNqj4HZqxz4mwU4S4sk+fJzoAJz8lx5A3Gp6MKMFG4rLDxTly5CweyWEEBA7oCDXVf73C+8xCQLX5jF7OrXXUA0Mv2s5hKZ2Jnk4mZQFT7X5xEJGSLypNZ/rFy5QVsn5Y8mOV2sLHY6eg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769798676213.74394867195326; Mon, 9 Mar 2020 09:03:18 -0700 (PDT) Received: from localhost ([::1]:46010 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKs9-00058a-6r for importer@patchew.org; Mon, 09 Mar 2020 12:03:17 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40302) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZj-0001oN-Ut for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZi-0001Lk-4o for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:15 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:43263) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZh-0001L8-TM for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:14 -0400 Received: by mail-wr1-x444.google.com with SMTP id v9so11801686wrf.10 for ; Mon, 09 Mar 2020 08:44:13 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.10 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=rbxvM6zBsEyzHKe8nAvY0XhamX4FQe6hP23LCjFR3Y0=; b=gCalxzOKcZIo2PLP2rf8J/e6wKLB/lOa9oJ9DT7ZR8GEnZs+lMBlStAVNRYoqApTSH FJvsil4DjT6Aist5+MEhfm/n/eLthC7gTpgdvqvSdTnEGjcN0MNJh2sgBf0LLbwTi0nf xnfyyT4w/iKmiRfx9PyRKFKvAR+efeX7q8CpDv57Vkcx8hRdFEGXqX+Cd4YO0iSAbvku makHky/Wls/RZOjIe0mU9rnii4QiehXPbsMSZ92mzpIcHHOnE6Bf7sV4CzC9+5lLFB65 FTmQahM+biEuKPbBV5XvLqD4jKrq0Q9U9u30xm/k9HCYiv+G7stZ021kII/1pY7f/iMA 6WJw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=rbxvM6zBsEyzHKe8nAvY0XhamX4FQe6hP23LCjFR3Y0=; b=mkGDuwOLuSutxaUlrDFR9Nh8J0bI3lou7UuOUMEK9cbDCnM99Z5YOJU677DJpNmL5h SwCIgWWjrVCKaeweMqcImwvoopObH+uv1+yNcADur37r8gHwonEPblDPZImMvvYfynlC KjtW9KFhyycleMr5xfD3avO3dDcoONXGzQuD7yVGHdZEVt3zJdcH2eo6qs1Ih29wViab krsZN+7IcQQXDvGwpIacmsgHDr0tozFFZEEy/ta4VdvIFvuviDMVGfIIpCjsQaE/G08v lbj6B3OcjiNzNtsAxfCOU3dVS71em87Jy/VTwfU1T3JeEacjPm3x1A3eSnmDtC93SN/C 80kg== X-Gm-Message-State: ANhLgQ0iyWa0ELStebY6CLbYkG5WLcdOMpoRsuDiFOY5146bZe18IttP OPzec4qeWCVv1LkDLiLUU3K8ksYDnMDOLg== X-Google-Smtp-Source: ADFU+vuWR2DlNsyb6fh83RJXvzdWdFh7wN1LQPOWkroPFEuQyRtxQvzDJdBYzb75eWRNs58Khc3q1A== X-Received: by 2002:a5d:6141:: with SMTP id y1mr20572150wrt.146.1583768651950; Mon, 09 Mar 2020 08:44:11 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 03/18] qapi/machine.json: Escape a literal '*' in doc comment Date: Mon, 9 Mar 2020 15:43:50 +0000 Message-Id: <20200309154405.13548-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" For rST, '*' is a kind of inline markup (for emphasis), so "*-softmmu" is a syntax error because of the missing closing '*'. Escape the '*' with a '\'. The texinfo document generator will leave the '\' in the output, which is not ideal, but that generator is going to go away in a subsequent commit. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/machine.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/machine.json b/qapi/machine.json index 6c11e3cf3a4..58580602524 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -12,7 +12,7 @@ # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and -# look for the *-softmmu targets near the "--target-list" option. The +# look for the \*-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. # --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769963; cv=none; d=zohomail.com; s=zohoarc; b=EdvtAvTElgfccOoW4upJNSShn8LJIejsmrag4AYceBWWwvZf6fTSZcEuu/qDGQUBRD6JjEFsSF3G4z4CtpKL3Iz2a/ZEn8mEcUVu10TZgv3XxyTUQM/AnpX9BjIkpbMGO1FY7HRT/zgaopCyGE1DjKQwIsOqSKs/Lg2NgCDTn9U= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769963; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=nWSMAlzi0oMRfWAEf8TA2pk4lWoUJVNUT6Q1IhJAJTw=; b=GmnFZwPuv7y+RaBA54v8aN4TvUYV5yq/iOpNoLwbbl7VjlOdnsok751h6b4h39gGZX1xDa08hwERxDiDhV/Vrc8S4IG0jcbP+TFz8LZUQH9eC2TsU8+eFAM0PgNSLVNeSxB3T+YCZQBAzeaHnTqeXtdn08bA+KzTWiPca2Zh160= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769963243381.7419558902948; Mon, 9 Mar 2020 09:06:03 -0700 (PDT) Received: from localhost ([::1]:46100 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKuo-0000dB-2r for importer@patchew.org; Mon, 09 Mar 2020 12:06:02 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40332) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZm-0001qD-05 for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:19 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZj-0001MY-V5 for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:17 -0400 Received: from mail-wr1-x42b.google.com ([2a00:1450:4864:20::42b]:44462) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZi-0001LV-DP for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:15 -0400 Received: by mail-wr1-x42b.google.com with SMTP id l18so1741016wru.11 for ; Mon, 09 Mar 2020 08:44:14 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=nWSMAlzi0oMRfWAEf8TA2pk4lWoUJVNUT6Q1IhJAJTw=; b=pQXkB1kMbN2sUFn1XurCnvTAozVEaogD8qp5qN7ePBOwmWb5VuQ87UjKNOpp0vb9Cx +SIvab09lKqIUM5UwLcZbMJU5EmDAu+/A1OANgMK1Ys52uSNgOl1cH6h5nf0IAlsM7wF mDHOOhoqZ60U2tNVSxXVaNK86Y3eaAnk2RlVr03DUmLKUgFqhYDnqLqS93cGnqP/HnU4 uAbDf3cwLlOVpC8ZsHjdi7EeZuLQCx5GjYLcBFSkD4o7IxtgyV69yTuNBBXdQEnGBRLi tR8qOL/rwLYPtUbuYPEeijrjvjp/UCcf4oo26iIbOsT3XdzAdnzkremtwgJiyd/MKzjB UqSw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=nWSMAlzi0oMRfWAEf8TA2pk4lWoUJVNUT6Q1IhJAJTw=; b=mU5oEurZ/N4/L9BN4PwXkjJLvdIlwVwfcJdPHe1cz5aQPhYfn441UDuQFrBeBOjjCT eCs7TXe2yF8z7gUmjL+FxR0s/FcfF/S5l47L0zyORJdyEcTammDpA1K3zu94EvF38U9e tqQmICXgS+SZXacQiitKM9KGIWQQ1CTY9zPjgE5W6KeKr6O09J7xecLBZ6s/pG/ZNovK NNr7zhJumwN5FF3HmBfoJr+0QBLhB+vegeSpuSdXi+hBgleIrFobT2zE8UxgHl4blA0S 9PgKGI2tmj4ffBi2UCbWaM42tExV5uaZRvBRRF0tsaUE21KdQ1bRYSw+NNP8Z1slZzwP CJ5w== X-Gm-Message-State: ANhLgQ1QeH0H3JfnLKxLk00vNd7udY078QyNNzmJvqX8NLmtYMNmaGa/ 8oMSz3jSZ/aKbxFypC9wnPryhj2h/P9ruw== X-Google-Smtp-Source: ADFU+vsSgHQI4g//WoEhtqdkOPMcFBWKNNEztsa+iIBET4BScmFsd2p/Z19QqH13T5Mkl4eCyEIg0Q== X-Received: by 2002:adf:b317:: with SMTP id j23mr21968013wrd.413.1583768653111; Mon, 09 Mar 2020 08:44:13 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 04/18] tests/qapi/doc-good.json: Clean up markup Date: Mon, 9 Mar 2020 15:43:51 +0000 Message-Id: <20200309154405.13548-5-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42b X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" doc-good.json tests some oddities of markup that we don't want to accept. Make them match the more restrictive rST syntax: * in a single list the bullet types must all match * lists must have leading and following blank lines * indentation is important * the '|' example syntax is going to go away entirely, so stop testing it This will avoid the tests spuriously breaking when we tighten up the parser code in the following commits. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster Reviewed-by: Richard Henderson --- New patch in v2 --- tests/qapi-schema/doc-good.json | 25 +++++++++++++------------ tests/qapi-schema/doc-good.out | 12 ++++++------ tests/qapi-schema/doc-good.texi | 12 +++--------- 3 files changed, 22 insertions(+), 27 deletions(-) diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.j= son index d992e713d97..a45dc22848c 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -10,25 +10,25 @@ # # *strong* _with emphasis_ # @var {in braces} +# # * List item one -# - Two, multiple +# * Two, multiple # lines # -# 3. Three -# Still in list +# * Three +# Still in list +# +# Not in list # -# Not in list # - Second list -# Note: still in list +# Note: still in list # # Note: not in list +# # 1. Third list # is numbered # -# - another item -# -# | example -# | multiple lines +# 2. another item # # Returns: the King # Since: the first age @@ -62,7 +62,7 @@ ## # @Base: # @base1: -# the first member +# the first member ## { 'struct': 'Base', 'data': { 'base1': 'Enum' } } =20 @@ -101,7 +101,7 @@ ## # @Alternate: # @i: an integer -# @b is undocumented +# @b is undocumented ## { 'alternate': 'Alternate', 'data': { 'i': 'int', 'b': 'bool' } } @@ -115,7 +115,7 @@ # @arg1: the first argument # # @arg2: the second -# argument +# argument # # Features: # @cmd-feat1: a feature @@ -124,6 +124,7 @@ # Returns: @Object # TODO: frobnicate # Notes: +# # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam # diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 4c9406a464d..9503a3a3178 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -68,25 +68,25 @@ doc freeform =20 *strong* _with emphasis_ @var {in braces} + * List item one -- Two, multiple +* Two, multiple lines =20 -3. Three +* Three Still in list =20 Not in list + - Second list Note: still in list =20 Note: not in list + 1. Third list is numbered =20 -- another item - -| example -| multiple lines +2. another item =20 Returns: the King Since: the first age diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.t= exi index d4b15dabf03..1e8063c8579 100644 --- a/tests/qapi-schema/doc-good.texi +++ b/tests/qapi-schema/doc-good.texi @@ -6,6 +6,7 @@ =20 @strong{strong} @emph{with emphasis} @code{var} @{in braces@} + @itemize @bullet @item List item one @@ -20,6 +21,7 @@ Still in list @end itemize =20 Not in list + @itemize @minus @item Second list @@ -28,6 +30,7 @@ Note: still in list @end itemize =20 Note: not in list + @enumerate @item Third list @@ -36,15 +39,6 @@ is numbered @item another item =20 -@example -example -@end example - -@example -multiple lines -@end example - - @end enumerate =20 Returns: the King --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583768952; cv=none; d=zohomail.com; s=zohoarc; b=gP7PRt2WACebQXY9zc2ioIGENS3bhlqjLed29b4juO33qqOs+Z5rocvw00QMa3G6lduhfAYYfs1HdS9OA0tZwxpIzz5c4VszUFgbaUQUh90kIjNd5y2HNijLzo1LhCb/Eb6B1yLXiCfUSAjEiLv61o0BYk8Ln+wtSKUjy+gDGgw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583768952; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=oanDNH9UXQs5SQ6FP6wfavjB/jgZbQ32aIl+6zF+rww=; b=cJ+fYB5hPknkZQ2t5rO9NIlKyR843mLicGojGO5uMohyy59N095OPgf3nE1YO6iUU0jQFOJZObwniEPYCEW9/wrLMzM3f8G3Nk/3Lyc1/sqOa41UHn366MTBuT3Af6Fhclbpruf9Gk7PT5CdcgqXlFz06nU0oo/4dT0Rm9RdmOI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 158376895219233.859981599532716; Mon, 9 Mar 2020 08:49:12 -0700 (PDT) Received: from localhost ([::1]:45540 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKeU-0007TT-Lv for importer@patchew.org; Mon, 09 Mar 2020 11:49:10 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40331) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZl-0001q8-Vu for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:19 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZk-0001Mp-4n for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:17 -0400 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]:33867) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZj-0001M8-Tc for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:16 -0400 Received: by mail-wr1-x433.google.com with SMTP id z15so11840587wrl.1 for ; Mon, 09 Mar 2020 08:44:15 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.13 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=oanDNH9UXQs5SQ6FP6wfavjB/jgZbQ32aIl+6zF+rww=; b=qlUf7rcUOo+B7pRTqJbWwSO4XrMFWR379eqyj4dOcmAgDRIRKZoFTNHyIeuXnWb+eq 75JYFNYTUu+ihXnW3PO1dWkj3xxOizLvgmEdV1VWTblIXqd396isIdtQYVJ3w1ruRAVr cAtc4E2MQzUC2vfIth+LauZQTzAhVy89yJzecxbyKzyYxT3FhsRs/yDEVRfcnR8U/SiH HZXHYCuVPjnVzxSjJK986n1drXEoUl6XOeKKv16yYIDGGJL0FZH1YL1N6WlnFxo/Eqp8 8qL7qeEPpGZnhYJZvcp5E2bJVN8erp0nLlAjCqW9ysfAGKLsiMVDUPwMWHQeCLqKtPCj jxuQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=oanDNH9UXQs5SQ6FP6wfavjB/jgZbQ32aIl+6zF+rww=; b=SS2+GE0gRh3q1y+81k1GmvBksJ5ftDSf7fmpdf2Vi+AcVBH3De/PWlm6X+Lv5H+9nB bhi9bNIoRb0tqnxBaM7OvG/IctbYelrAVnz90gsz7z4k26sLCaU7fwYSoB1vVfvzEhwi gs/Qu297C73SgHbknpITUM79HoQ2QxAA91/KwIM3GskDLVOMQ7hikwxmSBi9WjFztSya Ka/c1iNomRNTDDOvWpQsBdu/7QsZg3tNFInY8YkcdPYebgdt5sZth+s6m+mD/Of4SKwg sQSGVOMNYE8X/3rBPNWpQHpQevGa9dZ26nn/JWw30tTXTD1l/+bYjXbsjHwv8UfUqzkH dsNg== X-Gm-Message-State: ANhLgQ1m5mPOBF2ATzzXajVqEEQy/MloALHUO8NwPfWPxJMe1aG9Sd5Y uiFSenKHpxb5CHULH22FMLw8kC2UkE5wSQ== X-Google-Smtp-Source: ADFU+vtX1bt2+d7AlYq1ntuf4cQeuWTVy+gfDj813UE6/CBK26pfB7kUIFrIX9P6u3IKqP6aCgWAwg== X-Received: by 2002:a5d:518b:: with SMTP id k11mr22347036wrv.114.1583768654322; Mon, 09 Mar 2020 08:44:14 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 05/18] scripts/qapi: Move doc-comment whitespace stripping to doc.py Date: Mon, 9 Mar 2020 15:43:52 +0000 Message-Id: <20200309154405.13548-6-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::433 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" As we accumulate lines from doc comments when parsing the JSON, the QAPIDoc class generally strips leading and trailing whitespace using line.strip() when it calls _append_freeform(). This is fine for texinfo, but for rST leading whitespace is significant. We'd like to move to having the text in doc comments be rST format rather than a custom syntax, so move the removal of leading whitespace from the QAPIDoc class to the texinfo-specific processing code in texi_format() in qapi/doc.py. (Trailing whitespace will always be stripped by the rstrip() in Section::append regardless.) In a followup commit we will make the whitespace in the lines of doc comment sections more consistently follow the input source. There is no change to the generated .texi files before and after this commit. Because the qapi-schema test checks the exact values of the documentation comments against a reference, we need to update that reference to match the new whitespace. In the first four places this is now correctly checking that we did put in the amount of whitespace to pass a rST-formatted list to the backend; in the last two places the extra whitespace is 'wrong' and will go away again in the following commit. Signed-off-by: Peter Maydell Reviewed-by: Markus Armbruster Reviewed-by: Richard Henderson --- New in v2: update doc-good.out as noted in final para of commit msg --- scripts/qapi/doc.py | 1 + scripts/qapi/parser.py | 12 ++++-------- tests/qapi-schema/doc-good.out | 12 ++++++------ 3 files changed, 11 insertions(+), 14 deletions(-) diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py index 1787a53d91a..26cd1a1751e 100644 --- a/scripts/qapi/doc.py +++ b/scripts/qapi/doc.py @@ -79,6 +79,7 @@ def texi_format(doc): inlist =3D '' lastempty =3D False for line in doc.split('\n'): + line =3D line.strip() empty =3D line =3D=3D '' =20 # FIXME: Doing this in a single if / elif chain is diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index abadacbb0e8..7fae4478d34 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -417,10 +417,10 @@ class QAPIDoc: self._append_line =3D self._append_various_line self._append_various_line(line) else: - self._append_freeform(line.strip()) + self._append_freeform(line) else: # This is a free-form documentation block - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_args_line(self, line): """ @@ -453,7 +453,7 @@ class QAPIDoc: self._append_various_line(line) return =20 - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_features_line(self, line): name =3D line.split(' ', 1)[0] @@ -472,7 +472,7 @@ class QAPIDoc: self._append_various_line(line) return =20 - self._append_freeform(line.strip()) + self._append_freeform(line) =20 def _append_various_line(self, line): """ @@ -495,10 +495,6 @@ class QAPIDoc: line =3D line[len(name)+1:] self._start_section(name[:-1]) =20 - if (not self._section.name or - not self._section.name.startswith('Example')): - line =3D line.strip() - self._append_freeform(line) =20 def _start_symbol_section(self, symbols_dict, name): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 9503a3a3178..a65bce639ff 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -71,20 +71,20 @@ doc freeform =20 * List item one * Two, multiple -lines + lines =20 * Three -Still in list + Still in list =20 Not in list =20 - Second list -Note: still in list + Note: still in list =20 Note: not in list =20 1. Third list -is numbered + is numbered =20 2. another item =20 @@ -144,7 +144,7 @@ doc symbol=3DAlternate =20 arg=3Di an integer -@b is undocumented + @b is undocumented arg=3Db =20 doc freeform @@ -157,7 +157,7 @@ doc symbol=3Dcmd the first argument arg=3Darg2 the second -argument + argument arg=3Darg3 =20 feature=3Dcmd-feat1 --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769091; cv=none; d=zohomail.com; s=zohoarc; b=by6+akZ9sA6qbA9PMEILxJjUMm2VZ1v6LXWAg/sVsh3n7CRvKL88zNb4++zCIf8pUgOZ0oiLxy/efC4fcgsMH3kVkNwLmPkXpXF1f0b0kAy5qL4LGnh8lNBLWOM3PQooSc6PkjC3n4JBIBbE225pE2OXKU5bo3rIawht+3Y0jIE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769091; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=N6mQu6BRQc+d3wvjojXxmiJN8RUreVO9yrOtythNod4=; b=WL3kHAlvHae8AnMv2cqv/i8oUWhlC9f4kikmCjXsdTPsi2vMooW+fXzxyfiQdvDIzSwxEZ1VpvammMYuQyNm9AzjdF++d9r7Nwl5plkmakN4R6lD4Ms9jmmnmBWTckJcacvrO5OlnDnQ5MU8yR8ghx4WsJw5MGS5FN1EXWNuTBg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769091663260.6507375427718; Mon, 9 Mar 2020 08:51:31 -0700 (PDT) Received: from localhost ([::1]:45622 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKgk-00034P-3r for importer@patchew.org; Mon, 09 Mar 2020 11:51:30 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40359) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZp-0001ro-Cs for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:24 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZl-0001Np-UD for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:21 -0400 Received: from mail-wr1-x42d.google.com ([2a00:1450:4864:20::42d]:36916) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZl-0001N4-4K for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:17 -0400 Received: by mail-wr1-x42d.google.com with SMTP id 6so11824123wre.4 for ; Mon, 09 Mar 2020 08:44:17 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:15 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=N6mQu6BRQc+d3wvjojXxmiJN8RUreVO9yrOtythNod4=; b=fo7dRYZ9os3+a3d0+hUGbteCDtdwlVeO8VRf6wKssNLPL9M60o7gOAiZMuVyO04s2Q JVxlXF6+RhAZjaarSDTtSK4/j5kZ/2seQuwCe6vPRqRZCJLGS4Qbg4SUTdN5rcYFwD6k DDB/w9U1sOaoGVitqg3PVr/+QiSSCa/ZvnXyOZXENCu2wiw8nD7YRGDOCL57bHBSadEf EFK11rLwQzzgY8wVYNSFj1u+NO2Zf40xWyh18vz26ZkPk9FEwUeQbeqRafy6WXWW2nJc 5lrwT9OW9DF0ZP4XeRtZ1r4FbW0c5Fu9Gw8TxmUCr+egV+1RMEbI++t85kilWy9efEZX sYvA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=N6mQu6BRQc+d3wvjojXxmiJN8RUreVO9yrOtythNod4=; b=Y7SxmHx9mhr0jKJ6/Yka8/8fp0HsIAh71TXYPOhfoOxYjrVGHP0TOEMQZhfd9Lhxk4 r3/uqHeE+bs4rryt0ze2CtE2HZqe2enb4PM67wrD8ocQor/I4Lspp1pTqFETBwZD8r8a SlNBVmW/q/UDnbIhGCBLrQp5yJxi2XRxqgI67bXY9yIBBrvrOO3edi2bUBi3Elywz1o5 Ffcw2NbE47aSPe6XTSX4xMZnUUOC5UrzgnyiXT9kgHA/zZ10Ya4SkyWNFFupA/quLLJE hMurVi7vles1WO6oAUPyfuA6QTcXzMaMLcbsdJprb1Ze2Rlxg7WyrjNGk7r8wvALKBoH OuEg== X-Gm-Message-State: ANhLgQ0xczdxB9NqPiEdDY+6gPhzxjqus4kRSZCTlRj/d7bktwWehQBh Dh+CBfIGz3zPl9GC5gkFgu3MBU0jwZ6yZg== X-Google-Smtp-Source: ADFU+vsXGaUmFeqL/HdSTXNI5mI6FGVDRwdiAHsw8jH3cjccNy4hvbfBRJr31IWde338muOVT/exTA== X-Received: by 2002:adf:fd11:: with SMTP id e17mr20441757wrr.195.1583768655645; Mon, 09 Mar 2020 08:44:15 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 06/18] scripts/qapi/parser.py: improve doc comment indent handling Date: Mon, 9 Mar 2020 15:43:53 +0000 Message-Id: <20200309154405.13548-7-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42d X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Make the handling of indentation in doc comments more sophisticated, so that when we see a section like: Notes: some text some more text indented line 3 we save it for the doc-comment processing code as: some text some more text indented line 3 and when we see a section with the heading on its own line: Notes: some text some more text indented text we also accept that and save it in the same form. The exception is that we always retain indentation as-is for Examples sections, because these are literal text. If we detect that the comment document text is not indented as much as we expect it to be, we throw a parse error. (We don't complain about over-indented sections, because for rST this can be legitimate markup.) The golden reference for the doc comment text is updated to remove the two 'wrong' indents; these now form a test case that we correctly stripped leading whitespace from an indented multi-line argument definition. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- v1->v2: Update doc-good.out as per final para. --- scripts/qapi/parser.py | 81 +++++++++++++++++++++++++++------- tests/qapi-schema/doc-good.out | 4 +- 2 files changed, 67 insertions(+), 18 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 7fae4478d34..d9f11eadd96 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -308,18 +308,32 @@ class QAPIDoc: """ =20 class Section: - def __init__(self, name=3DNone): + def __init__(self, parser, name=3DNone, indent=3D0): + # parser, for error messages about indentation + self._parser =3D parser # optional section name (argument/member or section name) self.name =3D name # the list of lines for this section self.text =3D '' + # the expected indent level of the text of this section + self._indent =3D indent =20 def append(self, line): + # Strip leading spaces corresponding to the expected indent le= vel + # Blank lines are always OK. + if line: + spacecount =3D len(line) - len(line.lstrip(" ")) + if spacecount > self._indent: + spacecount =3D self._indent + if spacecount < self._indent: + raise QAPIParseError(self._parser, "unexpected de-inde= nt") + line =3D line[spacecount:] + self.text +=3D line.rstrip() + '\n' =20 class ArgSection(Section): - def __init__(self, name): - super().__init__(name) + def __init__(self, parser, name, indent=3D0): + super().__init__(parser, name, indent) self.member =3D None =20 def connect(self, member): @@ -333,7 +347,7 @@ class QAPIDoc: self._parser =3D parser self.info =3D info self.symbol =3D None - self.body =3D QAPIDoc.Section() + self.body =3D QAPIDoc.Section(parser) # dict mapping parameter name to ArgSection self.args =3D OrderedDict() self.features =3D OrderedDict() @@ -438,7 +452,18 @@ class QAPIDoc: =20 if name.startswith('@') and name.endswith(':'): line =3D line[len(name)+1:] - self._start_args_section(name[1:-1]) + if not line or line.isspace(): + # Line was just the "@arg:" header; following lines + # are not indented + indent =3D 0 + line =3D '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 1, and we + # pad out this first line so it is handled the same way + indent =3D len(name) + 1 + line =3D ' ' * indent + line + self._start_args_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line =3D self._append_various_line self._append_various_line(line) @@ -460,7 +485,17 @@ class QAPIDoc: =20 if name.startswith('@') and name.endswith(':'): line =3D line[len(name)+1:] - self._start_features_section(name[1:-1]) + if not line or line.isspace(): + # Line is just the "@name:" header, no ident for following= lines + indent =3D 0 + line =3D '' + else: + # Line is "@arg: first line of description"; following + # lines should be indented by len(name) + 3, and we + # pad out this first line so it is handled the same way + indent =3D len(name) + 1 + line =3D ' ' * indent + line + self._start_features_section(name[1:-1], indent) elif self._is_section_tag(name): self._append_line =3D self._append_various_line self._append_various_line(line) @@ -493,11 +528,23 @@ class QAPIDoc: % (name, self.sections[0].name)) if self._is_section_tag(name): line =3D line[len(name)+1:] - self._start_section(name[:-1]) + if not line or line.isspace(): + # Line is just "SectionName:", no indent for following lin= es + indent =3D 0 + line =3D '' + elif name.startswith("Example"): + # The "Examples" section is literal-text, so preserve + # all the indentation as-is + indent =3D 0 + else: + # Line is "SectionName: some text", indent required + indent =3D len(name) + 1 + line =3D ' ' * indent + line + self._start_section(name[:-1], indent) =20 self._append_freeform(line) =20 - def _start_symbol_section(self, symbols_dict, name): + def _start_symbol_section(self, symbols_dict, name, indent): # FIXME invalid names other than the empty string aren't flagged if not name: raise QAPIParseError(self._parser, "invalid parameter name") @@ -506,21 +553,21 @@ class QAPIDoc: "'%s' parameter name duplicated" % name) assert not self.sections self._end_section() - self._section =3D QAPIDoc.ArgSection(name) + self._section =3D QAPIDoc.ArgSection(self._parser, name, indent) symbols_dict[name] =3D self._section =20 - def _start_args_section(self, name): - self._start_symbol_section(self.args, name) + def _start_args_section(self, name, indent): + self._start_symbol_section(self.args, name, indent) =20 - def _start_features_section(self, name): - self._start_symbol_section(self.features, name) + def _start_features_section(self, name, indent): + self._start_symbol_section(self.features, name, indent) =20 - def _start_section(self, name=3DNone): + def _start_section(self, name=3DNone, indent=3D0): if name in ('Returns', 'Since') and self.has_section(name): raise QAPIParseError(self._parser, "duplicated '%s' section" % name) self._end_section() - self._section =3D QAPIDoc.Section(name) + self._section =3D QAPIDoc.Section(self._parser, name, indent) self.sections.append(self._section) =20 def _end_section(self): @@ -543,7 +590,7 @@ class QAPIDoc: def connect_member(self, member): if member.name not in self.args: # Undocumented TODO outlaw - self.args[member.name] =3D QAPIDoc.ArgSection(member.name) + self.args[member.name] =3D QAPIDoc.ArgSection(self._parser, me= mber.name) self.args[member.name].connect(member) =20 def connect_feature(self, feature): @@ -551,6 +598,8 @@ class QAPIDoc: raise QAPISemError(feature.info, "feature '%s' lacks documentation" % feature.name) + self.features[feature.name] =3D QAPIDoc.ArgSection(self._parse= r, + feature.name) self.features[feature.name].connect(feature) =20 def check_expr(self, expr): diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index a65bce639ff..0302ce0bde1 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -144,7 +144,7 @@ doc symbol=3DAlternate =20 arg=3Di an integer - @b is undocumented +@b is undocumented arg=3Db =20 doc freeform @@ -157,7 +157,7 @@ doc symbol=3Dcmd the first argument arg=3Darg2 the second - argument +argument arg=3Darg3 =20 feature=3Dcmd-feat1 --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769012; cv=none; d=zohomail.com; s=zohoarc; b=SsO70KglsJyibCfOjrT8NmN3xNAGrLnJe7nc+BHyJOAmWjk+YvdfP6d20nSBshPAUv4ivJ/GL3/6MiyuQqDXYM+mgJyohUU5bL/P23jqb9j855g5BieaD+vN2ey98o5b7yx+bRq1ztuTLFhmjJoYPnNQ709diXrg83iFulQAzpM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769012; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=OzpeqXmGwTCr3pNSFS/ceEjzB2+w8IvRp7XT0MgGdJM=; b=KYCsvsTNAlPdF/vzOwsQ8v5IVUENm+4Vi0EiChYPwV9KSL13x0lydkXXHSDmCoM4Hkp3u1urqmcEZ3PYuFG9Jftzmxs/UCUoBhXqSWnUFA4+Q+DuCFj9TaKGErUEzwqYoS2RQ3g7R9ihHzEc5V51TLspdGlsk7jbxaEcrcGRctY= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769012745211.16662663795648; Mon, 9 Mar 2020 08:50:12 -0700 (PDT) Received: from localhost ([::1]:45568 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKfT-0000ex-FM for importer@patchew.org; Mon, 09 Mar 2020 11:50:11 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40373) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZq-0001tB-Ij for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZn-0001Q1-OH for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:22 -0400 Received: from mail-wr1-x429.google.com ([2a00:1450:4864:20::429]:36731) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZm-0001O8-VM for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:19 -0400 Received: by mail-wr1-x429.google.com with SMTP id s5so7914364wrg.3 for ; Mon, 09 Mar 2020 08:44:18 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=OzpeqXmGwTCr3pNSFS/ceEjzB2+w8IvRp7XT0MgGdJM=; b=leEvIMK8XzUjfwM4kRShiuqek4l+OZMcOACrhZVlIv8HlC9SFxOn/gd8cwpQoI9uZo AJu18Om0DF9gh+9wuQfJ1n7nDth+0xjm49xwuPqXj91EKaW5z1BK4iY2m3rDUDotDq+P /gkRY9urVOBULtaj0kIyD7Q1glLU7sFfT/vkGCBXie9JFMIEsv8EBL/dF3Ko+jEiVUlb Wft4UtsTCsIRg3BjSI2ZTDpbaISweHTkqBhHzQrpYhVo9p/E7zRRUcHaUzuj1pEHEyO6 B+Qz1c4WdMuBn6dCDj9CjzstAjV/hWhaGXuwDr5DLbj0FvjjExg3FNRrbHmUZ60XXfRt fZcw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=OzpeqXmGwTCr3pNSFS/ceEjzB2+w8IvRp7XT0MgGdJM=; b=Pyi8hHIwq3RY8Ogu5i0We/zWayMosJ8UbnGTUhFuKqpJS9TYPixZj/gneMVxCr1YQ2 NpheKZiLWXlW8+D8Onv7wCRshzFRtGd6MtN9xudvp0iRZ14Gkpd/Bq3vH0afrETnPU9Z LWR/l3LO3+kSOdTYS1yM5SEwPbj16QGrNOH47gi7By/S6WqREvR8BsAEZta5+CQX9NLr wMIHFET/1aYiRPxGh8IHOVk6oxQAXECJZ4c+39sDjRXKPqG59ViDwmg/sguqtJvN6jcZ /PQBONDkdBPmto5515VrRvojlo2fTlKQI6YvN2cYyxy7CMzobYuLJsOa2P+GvRXPRdIf J93Q== X-Gm-Message-State: ANhLgQ0qxy3r9yOxu0BZPpUiVdHjQfMGTQEkAul25AwHuk7Itcj7Iehn 7ynXNLQJaejKWeruqtfBnORrijT02MNQFg== X-Google-Smtp-Source: ADFU+vvDcijNZsH2rMi8ovGnBmMU5C4C8E18ZmPr1ojDnLnrN3afmU0uMfkcOEAd6a7cVTx0FIeVtA== X-Received: by 2002:adf:f7c1:: with SMTP id a1mr21526447wrq.299.1583768657169; Mon, 09 Mar 2020 08:44:17 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 07/18] docs/sphinx: Add new qapi-doc Sphinx extension Date: Mon, 9 Mar 2020 15:43:54 +0000 Message-Id: <20200309154405.13548-8-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::429 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by: Peter Maydell --- MAINTAINERS | 1 + docs/conf.py | 6 +- docs/sphinx/qapidoc.py | 504 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 510 insertions(+), 1 deletion(-) create mode 100644 docs/sphinx/qapidoc.py diff --git a/MAINTAINERS b/MAINTAINERS index 36d0c6887a9..06a762b9dc4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2822,3 +2822,4 @@ M: Peter Maydell S: Maintained F: docs/conf.py F: docs/*/conf.py +F: docs/sphinx/ diff --git a/docs/conf.py b/docs/conf.py index 960043cb860..ac35922daf2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,10 @@ except NameError: # add these directories to sys.path here. If the directory is relative to = the # documentation root, use an absolute path starting from qemu_docdir. # +# Our extensions are in docs/sphinx; the qapidoc extension requires +# the QAPI modules from scripts/. sys.path.insert(0, os.path.join(qemu_docdir, "sphinx")) +sys.path.insert(0, os.path.join(qemu_docdir, "../scripts")) =20 =20 # -- General configuration ------------------------------------------------ @@ -64,7 +67,7 @@ needs_sphinx =3D '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions =3D ['kerneldoc', 'qmp_lexer', 'hxtool'] +extensions =3D ['kerneldoc', 'qmp_lexer', 'hxtool', 'qapidoc'] =20 # Add any paths that contain templates here, relative to this directory. templates_path =3D ['_templates'] @@ -238,3 +241,4 @@ texinfo_documents =3D [ kerneldoc_bin =3D os.path.join(qemu_docdir, '../scripts/kernel-doc') kerneldoc_srctree =3D os.path.join(qemu_docdir, '..') hxtool_srctree =3D os.path.join(qemu_docdir, '..') +qapidoc_srctree =3D os.path.join(qemu_docdir, '..') diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py new file mode 100644 index 00000000000..d0dd6e93d4c --- /dev/null +++ b/docs/sphinx/qapidoc.py @@ -0,0 +1,504 @@ +# coding=3Dutf-8 +# +# QEMU qapidoc QAPI file parsing extension +# +# Copyright (c) 2020 Linaro +# +# This work is licensed under the terms of the GNU GPLv2 or later. +# See the COPYING file in the top-level directory. +"""qapidoc is a Sphinx extension that implements the qapi-doc directive""" + +# The purpose of this extension is to read the documentation comments +# in QAPI JSON schema files, and insert them all into the current document. +# The conf.py file must set the qapidoc_srctree config value to +# the root of the QEMU source tree. +# Each qapi-doc:: directive takes one argument which is the +# path of the .json file to process, relative to the source tree. + +import os +import re + +from docutils import nodes +from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles +import sphinx +from qapi.gen import QAPISchemaVisitor +from qapi.schema import QAPIError, QAPISchema + +# Sphinx up to 1.6 uses AutodocReporter; 1.7 and later +# use switch_source_input. Check borrowed from kerneldoc.py. +Use_SSI =3D sphinx.__version__[:3] >=3D '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter + + +__version__ =3D '1.0' + +# Function borrowed from pydash, which is under the MIT license +def intersperse(iterable, separator): + """Like join, but for arbitrary iterables, notably arrays""" + iterable =3D iter(iterable) + yield next(iterable) + for item in iterable: + yield separator + yield item + +class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): + """A QAPI schema visitor which generates docutils/Sphinx nodes + + This class builds up a tree of docutils/Sphinx nodes corresponding + to documentation for the various QAPI objects. To use it, first create + a QAPISchemaGenRSTVisitor object, and call its visit_begin() method. + Then you can call one of the two methods 'freeform' (to add documentat= ion + for a freeform documentation chunk) or 'symbol' (to add documentation + for a QAPI symbol). These will cause the visitor to build up the + tree of document nodes. Once you've added all the documentation + via 'freeform' and 'symbol' method calls, you can call 'get_document_n= odes' + to get the final list of document nodes (in a form suitable for return= ing + from a Sphinx directive's 'run' method). + """ + def __init__(self, sphinx_directive): + self._cur_doc =3D None + self._sphinx_directive =3D sphinx_directive + self._top_node =3D nodes.section() + self._active_headings =3D [self._top_node] + + def _serror(self, msg): + """Raise an exception giving a user-friendly syntax error message"= "" + file =3D self._cur_doc.info.fname + line =3D self._cur_doc.info.line + raise ExtensionError('%s line %d: syntax error: %s' % (file, line,= msg)) + + def _make_dlitem(self, term, defn): + """Return a dlitem node with the specified term and definition. + + term should be a list of Text and literal nodes. + defn should be one of: + - a string, which will be handed to _parse_text_into_node + - a list of Text and literal nodes, which will be put into + a paragraph node + """ + dlitem =3D nodes.definition_list_item() + dlterm =3D nodes.term('', '', *term) + dlitem +=3D dlterm + if defn: + dldef =3D nodes.definition() + if isinstance(defn, list): + dldef +=3D nodes.paragraph('', '', *defn) + else: + self._parse_text_into_node(defn, dldef) + dlitem +=3D dldef + return dlitem + + def _make_section(self, title): + """Return a section node with optional title""" + section =3D nodes.section(ids=3D[self._sphinx_directive.new_serial= no()]) + if title: + section +=3D nodes.title(title, title) + return section + + def _nodes_for_ifcond(self, ifcond, with_if=3DTrue): + """Return list of Text, literal nodes for the ifcond + + Return a list which gives text like ' (If: cond1, cond2, cond3)', = where + the conditions are in literal-text and the commas are not. + If with_if is False, we don't return the "(If: " and ")". + """ + condlist =3D intersperse([nodes.literal('', c) for c in ifcond], + nodes.Text(', ')) + if not with_if: + return condlist + + nodelist =3D [nodes.Text(' ('), nodes.strong('', 'If: ')] + nodelist.extend(condlist) + nodelist.append(nodes.Text(')')) + return nodelist + + def _nodes_for_one_member(self, member): + """Return list of Text, literal nodes for this member + + Return a list of doctree nodes which give text like + 'name: type (optional) (If: ...)' suitable for use as the + 'term' part of a definition list item. + """ + term =3D [nodes.literal('', member.name)] + if member.type.doc_type(): + term.append(nodes.Text(': ')) + term.append(nodes.literal('', member.type.doc_type())) + if member.optional: + term.append(nodes.Text(' (optional)')) + if member.ifcond: + term.extend(self._nodes_for_ifcond(member.ifcond)) + return term + + def _nodes_for_variant_when(self, variants, variant): + """Return list of Text, literal nodes for variant 'when' clause + + Return a list of doctree nodes which give text like + 'when tagname is variant (If: ...)' suitable for use in + the 'variants' part of a definition list. + """ + term =3D [nodes.Text(' when '), + nodes.literal('', variants.tag_member.name), + nodes.Text(' is '), + nodes.literal('', '"%s"' % variant.name)] + if variant.ifcond: + term.extend(self._nodes_for_ifcond(variant.ifcond)) + return term + + def _nodes_for_members(self, doc, what, base=3DNone, variants=3DNone): + """Return doctree nodes for the table of members""" + dlnode =3D nodes.definition_list() + for section in doc.args.values(): + term =3D self._nodes_for_one_member(section.member) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn =3D section.text + elif (variants and variants.tag_member =3D=3D section.member + and not section.member.type.doc_type()): + values =3D section.member.type.member_names() + defn =3D [nodes.Text('One of ')] + defn.extend(intersperse([nodes.literal('', v) for v in val= ues], + nodes.Text(', '))) + else: + defn =3D [nodes.Text('Not documented')] + + dlnode +=3D self._make_dlitem(term, defn) + + if base: + dlnode +=3D self._make_dlitem([nodes.Text('The members of '), + nodes.literal('', base.doc_type()= )], + None) + + if variants: + for v in variants.variants: + if v.type.is_implicit(): + assert not v.type.base and not v.type.variants + for m in v.type.local_members: + term =3D self._nodes_for_one_member(m) + term.extend(self._nodes_for_variant_when(variants,= v)) + dlnode +=3D self._make_dlitem(term, None) + else: + term =3D [nodes.Text('The members of '), + nodes.literal('', v.type.doc_type())] + term.extend(self._nodes_for_variant_when(variants, v)) + dlnode +=3D self._make_dlitem(term, None) + + if not dlnode.children: + return None + + section =3D self._make_section(what) + section +=3D dlnode + return section + + def _nodes_for_enum_values(self, doc, what): + """Return doctree nodes for the table of enum values""" + seen_item =3D False + dlnode =3D nodes.definition_list() + for section in doc.args.values(): + termtext =3D [nodes.literal('', section.member.name)] + if section.member.ifcond: + termtext.extend(self._nodes_for_ifcond(section.member.ifco= nd)) + # TODO drop fallbacks when undocumented members are outlawed + if section.text: + defn =3D section.text + else: + defn =3D [nodes.Text('Not documented')] + + dlnode +=3D self._make_dlitem(termtext, defn) + seen_item =3D True + + if not seen_item: + return None + + section =3D self._make_section(what) + section +=3D dlnode + return section + + def _nodes_for_arguments(self, doc, boxed_arg_type): + """Return doctree nodes for the arguments section""" + if boxed_arg_type: + assert not doc.args + section =3D self._make_section('Arguments') + dlnode =3D nodes.definition_list() + dlnode +=3D self._make_dlitem( + [nodes.Text('The members of '), + nodes.literal('', boxed_arg_type.name)], + None) + section +=3D dlnode + return section + + return self._nodes_for_members(doc, 'Arguments') + + def _nodes_for_features(self, doc): + """Return doctree nodes for the table of features""" + seen_item =3D False + dlnode =3D nodes.definition_list() + for section in doc.features.values(): + dlnode +=3D self._make_dlitem([nodes.literal('', section.name)= ], + section.text) + seen_item =3D True + + if not seen_item: + return None + + section =3D self._make_section('Features') + section +=3D dlnode + return section + + def _nodes_for_example(self, exampletext): + """Return doctree nodes for a code example snippet""" + return nodes.literal_block(exampletext, exampletext) + + def _nodes_for_sections(self, doc, ifcond): + """Return doctree nodes for additional sections following argument= s""" + nodelist =3D [] + for section in doc.sections: + snode =3D self._make_section(section.name) + if section.name and section.name.startswith('Example'): + snode +=3D self._nodes_for_example(section.text) + else: + self._parse_text_into_node(section.text, snode) + nodelist.append(snode) + if ifcond: + snode =3D self._make_section('If') + snode +=3D self._nodes_for_ifcond(ifcond, with_if=3DFalse) + nodelist.append(snode) + if not nodelist: + return None + return nodelist + + def _add_doc(self, typ, sections): + """Add documentation for a command/object/enum... + + We assume we're documenting the thing defined in self._cur_doc. + typ is the type of thing being added ("Command", "Object", etc) + + sections is a list of nodes for sections to add to the definition. + """ + + doc =3D self._cur_doc + snode =3D nodes.section(ids=3D[self._sphinx_directive.new_serialno= ()]) + snode +=3D nodes.title('', '', *[nodes.literal(doc.symbol, doc.sym= bol), + nodes.Text(' (' + typ + ')')]) + self._parse_text_into_node(doc.body.text, snode) + for s in sections: + if s is not None: + snode +=3D s + self._add_node_to_current_heading(snode) + + def visit_enum_type(self, name, info, ifcond, members, prefix): + doc =3D self._cur_doc + self._add_doc('Enum', + [self._nodes_for_enum_values(doc, 'Values'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_object_type(self, name, info, ifcond, base, members, variant= s, + features): + doc =3D self._cur_doc + if base and base.is_implicit(): + base =3D None + self._add_doc('Object', + [self._nodes_for_members(doc, 'Members', base, varia= nts), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_alternate_type(self, name, info, ifcond, variants): + doc =3D self._cur_doc + self._add_doc('Alternate', + [self._nodes_for_members(doc, 'Members'), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_command(self, name, info, ifcond, arg_type, ret_type, gen, + success_response, boxed, allow_oob, allow_preconfig, + features): + doc =3D self._cur_doc + self._add_doc('Command', + [self._nodes_for_arguments(doc, + arg_type if boxed else No= ne), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def visit_event(self, name, info, ifcond, arg_type, boxed): + doc =3D self._cur_doc + self._add_doc('Event', + [self._nodes_for_arguments(doc, + arg_type if boxed else No= ne), + self._nodes_for_features(doc), + self._nodes_for_sections(doc, ifcond)]) + + def symbol(self, doc, entity): + """Add documentation for one symbol to the document tree + + This is the main entry point which causes us to add documentation + nodes for a symbol (which could be a 'command', 'object', 'event', + etc). We do this by calling 'visit' on the schema entity, which + will then call back into one of our visit_* methods, depending + on what kind of thing this symbol is. + """ + self._cur_doc =3D doc + entity.visit(self) + self._cur_doc =3D None + + def _start_new_heading(self, heading, level): + """Start a new heading at the specified heading level + + Create a new section whose title is 'heading' and which is placed + in the docutils node tree as a child of the most recent level-1 + heading. Subsequent document sections (commands, freeform doc chun= ks, + etc) will be placed as children of this new heading section. + """ + if len(self._active_headings) < level: + self._serror('Level %d subheading found outside a level %d hea= ding' + % (level, level - 1)) + snode =3D self._make_section(heading) + self._active_headings[level - 1] +=3D snode + self._active_headings =3D self._active_headings[:level] + self._active_headings.append(snode) + + def _add_node_to_current_heading(self, node): + """Add the node to whatever the current active heading is""" + self._active_headings[-1] +=3D node + + def freeform(self, doc): + """Add a piece of 'freeform' documentation to the document tree + + A 'freeform' document chunk doesn't relate to any particular + symbol (for instance, it could be an introduction). + + As a special case, if the freeform document is a single line + of the form '=3D Heading text' it is treated as a section or subse= ction + heading, with the heading level indicated by the number of '=3D' s= igns. + """ + + # QAPIDoc documentation says free-form documentation blocks + # must have only a body section, nothing else. + assert not doc.sections + assert not doc.args + assert not doc.features + self._cur_doc =3D doc + + if re.match(r'=3D+ ', doc.body.text): + # Section or subsection heading: must be the only thing in the= block + (heading, _, rest) =3D doc.body.text.partition('\n') + if rest !=3D '': + raise ExtensionError('%s line %s: section or subsection he= ading' + ' must be in its own doc comment bloc= k' + % (doc.info.fname, doc.info.line)) + (leader, _, heading) =3D heading.partition(' ') + self._start_new_heading(heading, len(leader)) + return + + node =3D self._make_section(None) + self._parse_text_into_node(doc.body.text, node) + self._add_node_to_current_heading(node) + self._cur_doc =3D None + + def _parse_text_into_node(self, doctext, node): + """Parse a chunk of QAPI-doc-format text into the node + + The doc comment can contain most inline rST markup, including + bulleted and enumerated lists. + As an extra permitted piece of markup, @var will be turned + into ``var``. + """ + + # Handle the "@var means ``var`` case + doctext =3D re.sub(r'@([\w-]+)', r'``\1``', doctext) + + rstlist =3D ViewList() + for line in doctext.splitlines(): + # The reported line number will always be that of the start li= ne + # of the doc comment, rather than the actual location of the e= rror. + # Being more precise would require overhaul of the QAPIDoc cla= ss + # to track lines more exactly within all the sub-parts of the = doc + # comment, as well as counting lines here. + rstlist.append(line, self._cur_doc.info.fname, + self._cur_doc.info.line) + self._sphinx_directive.do_parse(rstlist, node) + + def get_document_nodes(self): + """Return the list of docutils nodes which make up the document""" + return self._top_node.children + +class QAPIDocDirective(Directive): + """Extract documentation from the specified QAPI .json file""" + required_argument =3D 1 + optional_arguments =3D 1 + option_spec =3D { + 'qapifile': directives.unchanged_required + } + has_content =3D False + + def new_serialno(self): + """Return a unique new ID string suitable for use as a node's ID""" + env =3D self.state.document.settings.env + return 'qapidoc-%d' % env.new_serialno('qapidoc') + + def run(self): + env =3D self.state.document.settings.env + qapifile =3D env.config.qapidoc_srctree + '/' + self.arguments[0] + + # Tell sphinx of the dependency + env.note_dependency(os.path.abspath(qapifile)) + + try: + schema =3D QAPISchema(qapifile) + except QAPIError as err: + # Launder QAPI parse errors into Sphinx extension errors + # so they are displayed nicely to the user + raise ExtensionError(str(err)) + + vis =3D QAPISchemaGenRSTVisitor(self) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + + return vis.get_document_nodes() + + def do_parse(self, rstlist, node): + """Parse rST source lines and add them to the specified node + + Take the list of rST source lines rstlist, parse them as + rST, and add the resulting docutils nodes as children of node. + The nodes are parsed in a way that allows them to include + subheadings (titles) without confusing the rendering of + anything else. + """ + # This is from kerneldoc.py -- it works around an API change in + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use + # sphinx.util.nodes.nested_parse_with_titles() rather than the + # plain self.state.nested_parse(), and so we can drop the saving + # of title_styles and section_level that kerneldoc.py does, + # because nested_parse_with_titles() does that for us. + if Use_SSI: + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + else: + save =3D self.state.memo.reporter + self.state.memo.reporter =3D AutodocReporter(rstlist, + self.state.memo.rep= orter) + try: + nested_parse_with_titles(self.state, rstlist, node) + finally: + self.state.memo.reporter =3D save + +def setup(app): + """ Register qapi-doc directive with Sphinx""" + app.add_config_value('qapidoc_srctree', None, 'env') + app.add_directive('qapi-doc', QAPIDocDirective) + + return dict( + version=3D__version__, + parallel_read_safe=3DTrue, + parallel_write_safe=3DTrue + ) --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769008; cv=none; d=zohomail.com; s=zohoarc; b=UUebOFSKYwsVOQT5TIohYRC+sFQk0sJsrOCnCPUcYI449lTEWU4iZ0JgvroEpOgoav6AArAbmOs0qeo/6RVxAbmE32GaOYJfpBK+ucPTLXQvIeUife4aelt+UdAldJdyMqsreo0YggI1bm5m7uJB5wDSGX3MCpLVyFQFgb4nooU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769008; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=flCiToXzqdHlr8LDrJeYuluO1+ofPa9R4N/nLRKeLbw=; b=GCz8HFfTm6/DsSxRV58p5ZFClsBHIJ8/LmURiNpu4cKbi1uPqvKAI/Ik7FBypnk/XOU9YvdQEpNN0+hIuUYUBl5JZGGyBNCerpkQ3Qcn/rKc1kKRFwBpf/V9AXyaT9nmZpYKX0GCztNi5wO5jgNcDUe5MpQzSk0t+bCvWDR5b4s= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769008063491.08309932624275; Mon, 9 Mar 2020 08:50:08 -0700 (PDT) Received: from localhost ([::1]:45564 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKfO-0000Vo-M3 for importer@patchew.org; Mon, 09 Mar 2020 11:50:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40374) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZq-0001tC-Ii for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZo-0001QP-IL for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:22 -0400 Received: from mail-wr1-x42e.google.com ([2a00:1450:4864:20::42e]:39293) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZo-0001Pv-6t for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:20 -0400 Received: by mail-wr1-x42e.google.com with SMTP id r15so6770964wrx.6 for ; Mon, 09 Mar 2020 08:44:20 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:17 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=flCiToXzqdHlr8LDrJeYuluO1+ofPa9R4N/nLRKeLbw=; b=DrrG5/X4256hVN4HGItzx1UEs5Px2tgqafGMLRUTVxsG7KSvmtq0N+egDOLWN54buU whUt7qXnu/QiM9Lj2Xvb6+gkxTc/7sZef23az4jtNdVkGFGoyVpQzJGq3vEAJfNZNzJH LsuHtBpGMZWMTf/SgIpX0Sv85rveGX++e2rC1o30QF+r1haKqNXHgfBlbqJT9r9oQ9QU boUT/4kQnljQaYwijy9KUHleJDBUVAFZ7K8PMut2DbC3EzRsDd9Nc5q55fQZTstKFX/n JsJ5nPt1rmeE3xeNnWtIdZjKoVQ8mqVP9arh+KCmAOnEjp9MhF5NhW5fxMfefLvrdedn xfRw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=flCiToXzqdHlr8LDrJeYuluO1+ofPa9R4N/nLRKeLbw=; b=koKLr/vJcWln3Z78zrzyHoopqm8fLQdp+vfTSwKMTKbdwffjHH0VFI1Yk0qE9GeX7M wd+Z062xOGdDDRPpNtAod9OQSWjLX83dSL6zjVIBJa5M3SXnZCAjbntFzYmB42UuIkOw FwO7zmsJkfb+DrcrUJmUbYplE1wp/6bB3NEci9ZFv80Kfc8W772+liRibvvox15n0Xnn RfsCuoHkOEW9uFyybIGbWIJrHsmJZVfPCRUlbtoD3FGQ2v4pa1OBFAMN1lidh3IiaPWO At+9dPSambpJm3O4vAkEW0zp7Z33AOp0/zENb2IQxBWnN62QxMIk4xBOgDaSnbwjdv9f nPRw== X-Gm-Message-State: ANhLgQ1cLXN6MmMzFrWhst4jNHT58l3IlXCOXHCTgZGqi6qxre9iPnOL xn/5xeH+rsYw9oXVa17xpDjTtMjchLdgqQ== X-Google-Smtp-Source: ADFU+vskLE7CwMW4AmU3rLi/TRYmLAqNiNCR1JbhfzrtoGLqFzV72LQAyU0ZL/c85mopxoYC2LOUtQ== X-Received: by 2002:adf:b3d6:: with SMTP id x22mr21144248wrd.242.1583768658557; Mon, 09 Mar 2020 08:44:18 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 08/18] docs/interop: Convert qemu-ga-ref to rST Date: Mon, 9 Mar 2020 15:43:55 +0000 Message-Id: <20200309154405.13548-9-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42e X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Convert qemu-ga-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-ga-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. As the GA ref is now part of the Sphinx 'interop' manual, we can delete the direct link from index.html.in. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- Makefile | 41 ++++++++---------- MAINTAINERS | 2 +- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-ga-ref.rst | 4 ++ docs/interop/qemu-ga-ref.texi | 80 ----------------------------------- 7 files changed, 25 insertions(+), 106 deletions(-) create mode 100644 docs/interop/qemu-ga-ref.rst delete mode 100644 docs/interop/qemu-ga-ref.texi diff --git a/Makefile b/Makefile index 5847f8d41d9..14780878fad 100644 --- a/Makefile +++ b/Makefile @@ -353,7 +353,7 @@ DOCS+=3D$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 DOCS+=3Ddocs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/= interop/qemu-qmp-ref.7 -DOCS+=3Ddocs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/in= terop/qemu-ga-ref.7 +DOCS+=3D$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 DOCS+=3D$(MANUAL_BUILDDIR)/index.html ifdef CONFIG_VIRTFS @@ -771,11 +771,11 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-ga-qapi.texi docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 docs/interop/qemu-ga-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html + rm -f docs/interop/qemu-qmp-qapi.texi + rm -f docs/interop/qemu-qmp-ref.7 + rm -f docs/interop/qemu-qmp-ref.txt + rm -f docs/interop/qemu-qmp-ref.pdf + rm -f docs/interop/qemu-qmp-ref.html rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -830,7 +830,7 @@ endif # and also any sphinx-built manpages. define install-manual =3D for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "= $(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_= DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTAL= L_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done endef =20 # Note that we deliberately do not install the "devel" manual: it is @@ -865,9 +865,7 @@ ifdef CONFIG_TRACE_SYSTEMTAP endif ifneq (,$(findstring qemu-ga,$(TOOLS))) $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)= /man8" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 "$(DESTDIR)$(man= dir)/man7" endif endif ifdef CONFIG_VIRTFS @@ -1060,7 +1058,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) =20 -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_P= ATH)/qga/qapi-schema.json $(qapi-py) $(call build-manual,interop,html) =20 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1075,7 +1073,10 @@ $(MANUAL_BUILDDIR)/tools/index.html: $(call manual-d= eps,tools) $(SRC_PATH)/qemu- $(MANUAL_BUILDDIR)/user/index.html: $(call manual-deps,user) $(call build-manual,user,html) =20 -$(call define-manpage-rule,interop,qemu-ga.8) +$(call define-manpage-rule,interop,\ + qemu-ga.8 qemu-ga-ref.7,\ + $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ + $(qapi-py)) =20 $(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-mod= els.7) =20 @@ -1092,18 +1093,10 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/ind= ex.html.in qemu-version.h docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ =20 -docs/interop/qemu-ga-qapi.texi: qga/qapi-generated/qga-qapi-doc.texi - @cp -p $< $@ - -html: docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxd= ocs -info: docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info -pdf: docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf -txt: docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt - -docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ - docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \ - docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7: \ - docs/interop/qemu-ga-ref.texi docs/interop/qemu-ga-qapi.texi +html: docs/interop/qemu-qmp-ref.html sphinxdocs +info: docs/interop/qemu-qmp-ref.info +pdf: docs/interop/qemu-qmp-ref.pdf +txt: docs/interop/qemu-qmp-ref.txt =20 docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ diff --git a/MAINTAINERS b/MAINTAINERS index 06a762b9dc4..1f13db32d97 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2154,9 +2154,9 @@ M: Michael Roth S: Maintained F: qga/ F: docs/interop/qemu-ga.rst +F: docs/interop/qemu-ga-ref.rst F: scripts/qemu-guest-agent/ F: tests/test-qga.c -F: docs/interop/qemu-ga-ref.texi T: git https://github.com/mdroth/qemu.git qga =20 QOM diff --git a/docs/index.html.in b/docs/index.html.in index e9a160384cf..f180770b052 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -13,7 +13,6 @@
  • System Emulation Management= and Interoperability Guide
  • System Emulation Guest Hardwa= re Specifications
  • QMP Reference Manual
    • -
  • Guest Agent Protocol Referenc= e
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index 42ce7e3d365..e83632e0108 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -19,4 +19,6 @@ html_theme_options['description'] =3D u'System Emulation = Management and Interopera man_pages =3D [ ('qemu-ga', 'qemu-ga', u'QEMU Guest Agent', ['Michael Roth '], 8), + ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index 049387ac6de..f3af38dce17 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -18,5 +18,6 @@ Contents: live-block-operations pr-helper qemu-ga + qemu-ga-ref vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst new file mode 100644 index 00000000000..013eac0bb53 --- /dev/null +++ b/docs/interop/qemu-ga-ref.rst @@ -0,0 +1,4 @@ +QEMU Guest Agent Protocol Reference +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. qapi-doc:: qga/qapi-schema.json diff --git a/docs/interop/qemu-ga-ref.texi b/docs/interop/qemu-ga-ref.texi deleted file mode 100644 index ddb76ce1c2a..00000000000 --- a/docs/interop/qemu-ga-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-ga-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU Guest Agent Protocol Reference - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU Guest Agent Protocol reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-GA-Ref: (qemu-ga-ref). QEMU Guest Agent Protocol Reference -@end direntry - -@titlepage -@title Guest Agent Protocol Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU Guest Agent protocol reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qemu-ga-qapi.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769141; cv=none; d=zohomail.com; s=zohoarc; b=V5DQrjiGcXxl9n0XhUHWpITaIrjdEkRa9zus4bzqCEYRjwei/cNhfOAxFYblM6H503gWJCCsgQBufIixrwGLu+6YRXr/DBeiHHzg/q+9WSmuVNtZnOBvmX0snSLkdYoon7E3mm/vI2k3PKr19GrPqERQB05/BPXjzGHcs3I79ng= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769141; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=E/C3ETynTNluvhCBM4gicRKFu80GsFl4sti73t961ws=; b=AdVrLsit9RFJrX/+mF036NOOXcCjN7uGgi/TEvVMOD0aDFRVd41tvuE1+uf9GAuOpWnm6OBBxQJ437N6wryczUTvw6vx0waO61+8/iajuztB3mZeFETcR7D1WEj26LI2QnVEBiQjzprHb/FLgHzHuGW9P/SZbVw4aFI01JEUojM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 158376914149869.88798658922849; Mon, 9 Mar 2020 08:52:21 -0700 (PDT) Received: from localhost ([::1]:45634 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKhW-0004kD-V9 for importer@patchew.org; Mon, 09 Mar 2020 11:52:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40399) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZt-0001v3-38 for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:27 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZp-0001R3-Ua for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:24 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:36925) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZp-0001Qc-M2 for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:21 -0400 Received: by mail-wr1-x436.google.com with SMTP id 6so11824491wre.4 for ; Mon, 09 Mar 2020 08:44:21 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=E/C3ETynTNluvhCBM4gicRKFu80GsFl4sti73t961ws=; b=rZUTzOf8jSUjlLqYMgZ7Ywsb5zA6vtHfxdbEbSbyBtTqIuHTnbvwdWKbS3DMgxBUYw shXGLV7wFrWeW2jkRt7BG2mWoVmWsqiLEvw+eJlU+A5FFTIuxvqJXJ2pSsMWd/9Ks5nj 15zt9YVWn7ccxQ4+64v/uVrvTPHi61Dn31r0Z/v5kFAyrQHNm0kdV8BySHPbOQWd+b0t pCdPO2C60uLboTUsx86zyPjFYcdKGEMczgbgvtgqhqiTZdBFaTTpiGV/h3kI9GY8/aje ZzNVLn8AAX5DWYB93bat8zIaJu3KSZrrI4gbauQtLmhk2+1g125fGAEmdibMzDXJVUV5 dmlg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=E/C3ETynTNluvhCBM4gicRKFu80GsFl4sti73t961ws=; b=Yvk00+BDmfOsQcKJ9fbHMJWzGe273lEBNowgxYzFzVa+sjBRhMYj2L+8D7ApmgwwwF qb1N7Ib8u8eo4UpebNJTMwUSkSY0N3lz40akbPJOjbA3vOToxJeQd1C85u6eegyUhAz/ yPC+iOLxEOFQi2+OI5wRAeeYuGo9NtnTWtNPiKslOvnaysQ5zwgp2mGEMaEJbUab6lGi m9jO/GPZnDMgAnsbeqdpAiCfmZVXMKbaFUkdq8vtXY185O1zoSrK6q06UOS+TfL4v6Qu N8YViqUUXJzVWUjHt3Kw0/HaoDlKS8Xnuom5/LntTaSmBMzIcsJDtVJc9wdZNOaiLUJs F9KA== X-Gm-Message-State: ANhLgQ3AzRY1IjHKicspkp5oQlSWgtxsWYe410TO2m+Uj+jP8buV0HOE kGXCTQIfPaKU2N4GFZpQaRJcy2Osz6x9ZA== X-Google-Smtp-Source: ADFU+vv+KgM0RObT801fxNHKmb2YnGmEXRVoL+FLq7ihp653yMR+oqoHcyuCgn2duc5tv32gWa/JKg== X-Received: by 2002:a05:6000:185:: with SMTP id p5mr4832401wrx.155.1583768659994; Mon, 09 Mar 2020 08:44:19 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 09/18] docs/interop: Convert qemu-qmp-ref to rST Date: Mon, 9 Mar 2020 15:43:56 +0000 Message-Id: <20200309154405.13548-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::436 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Convert qemu-qmp-ref to rST format. This includes dropping the plain-text, pdf and info format outputs for this document; as with all our other Sphinx-based documentation, we provide HTML and manpage only. The qemu-qmp-ref.rst is somewhat more stripped down than the .texi was, because we do not (currently) attempt to generate indexes for the commands, events and data types being documented. Again, we drop the direct link from index.html.in now that the QMP ref is part of the interop manual. This commit removes the 'info', 'txt' and 'pdf' Makefile targets, because we no longer generate any documentation except for the Sphinx HTML manuals and the manpages. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- Makefile | 39 ++++------------- docs/index.html.in | 1 - docs/interop/conf.py | 2 + docs/interop/index.rst | 1 + docs/interop/qemu-qmp-ref.rst | 4 ++ docs/interop/qemu-qmp-ref.texi | 80 ---------------------------------- 6 files changed, 16 insertions(+), 111 deletions(-) create mode 100644 docs/interop/qemu-qmp-ref.rst delete mode 100644 docs/interop/qemu-qmp-ref.texi diff --git a/Makefile b/Makefile index 14780878fad..6dcc39efcee 100644 --- a/Makefile +++ b/Makefile @@ -126,7 +126,6 @@ GENERATED_QAPI_FILES +=3D qapi/qapi-events.h qapi/qapi-= events.c GENERATED_QAPI_FILES +=3D $(QAPI_MODULES:%=3Dqapi/qapi-events-%.h) GENERATED_QAPI_FILES +=3D $(QAPI_MODULES:%=3Dqapi/qapi-events-%.c) GENERATED_QAPI_FILES +=3D qapi/qapi-introspect.c qapi/qapi-introspect.h -GENERATED_QAPI_FILES +=3D qapi/qapi-doc.texi =20 generated-files-y +=3D $(GENERATED_QAPI_FILES) =20 @@ -352,7 +351,6 @@ ifeq ($(CONFIG_LINUX)$(CONFIG_SECCOMP)$(CONFIG_LIBCAP_N= G),yyy) DOCS+=3D$(MANUAL_BUILDDIR)/tools/virtiofsd.1 endif DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 -DOCS+=3Ddocs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/= interop/qemu-qmp-ref.7 DOCS+=3D$(MANUAL_BUILDDIR)/interop/qemu-ga-ref.7 DOCS+=3D$(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 DOCS+=3D$(MANUAL_BUILDDIR)/index.html @@ -628,8 +626,7 @@ $(SRC_PATH)/scripts/qapi-gen.py qga/qapi-generated/qga-qapi-types.c qga/qapi-generated/qga-qapi-types.h \ qga/qapi-generated/qga-qapi-visit.c qga/qapi-generated/qga-qapi-visit.h \ qga/qapi-generated/qga-qapi-commands.h qga/qapi-generated/qga-qapi-command= s.c \ -qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-in= it-commands.c \ -qga/qapi-generated/qga-qapi-doc.texi: \ +qga/qapi-generated/qga-qapi-init-commands.h qga/qapi-generated/qga-qapi-in= it-commands.c: \ qga/qapi-generated/qapi-gen-timestamp ; qga/qapi-generated/qapi-gen-timestamp: $(SRC_PATH)/qga/qapi-schema.json $(= qapi-py) $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ @@ -771,11 +768,6 @@ distclean: clean rm -f config.log rm -f linux-headers/asm rm -f docs/version.texi - rm -f docs/interop/qemu-qmp-qapi.texi - rm -f docs/interop/qemu-qmp-ref.7 - rm -f docs/interop/qemu-qmp-ref.txt - rm -f docs/interop/qemu-qmp-ref.pdf - rm -f docs/interop/qemu-qmp-ref.html rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -830,7 +822,7 @@ endif # and also any sphinx-built manpages. define install-manual =3D for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "= $(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-qmp-ref.*' ')' ); do $(INSTAL= L_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done +for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' -name '*.[0-9]= '); do $(INSTALL_DATA) "$(MANUAL_BUILDDIR)/$$f" "$(DESTDIR)$(qemu_docdir)/$= $f"; done endef =20 # Note that we deliberately do not install the "devel" manual: it is @@ -846,13 +838,11 @@ install-sphinxdocs: sphinxdocs install-doc: $(DOCS) install-sphinxdocs $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/index.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)" ifdef CONFIG_POSIX $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu.1 "$(DESTDIR)$(mandir)/man= 1" $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7" - $(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-qmp-ref.7 "$(DESTDIR)$(ma= ndir)/man7" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR= )$(mandir)/man7" $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-cpu-models.7 "$(DESTDIR)$(= mandir)/man7" ifeq ($(CONFIG_TOOLS),y) @@ -1058,7 +1048,7 @@ endef $(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) $(call build-manual,devel,html) =20 -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_P= ATH)/qga/qapi-schema.json $(qapi-py) +$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) $(SRC_P= ATH)/qga/qapi-schema.json $(qapi-modules) $(qapi-py) $(call build-manual,interop,html) =20 $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) @@ -1074,9 +1064,9 @@ $(MANUAL_BUILDDIR)/user/index.html: $(call manual-dep= s,user) $(call build-manual,user,html) =20 $(call define-manpage-rule,interop,\ - qemu-ga.8 qemu-ga-ref.7,\ + qemu-ga.8 qemu-ga-ref.7 qemu-qmp-ref.7,\ $(SRC_PATH)/qemu-img-cmds.hx $(SRC_PATH)/qga/qapi-schema.json \ - $(qapi-py)) + $(qapi-modules) $(qapi-py)) =20 $(call define-manpage-rule,system,qemu.1 qemu-block-drivers.7 qemu-cpu-mod= els.7) =20 @@ -1090,18 +1080,7 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/inde= x.html.in qemu-version.h $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \ "GEN","$@") =20 -docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi - @cp -p $< $@ - -html: docs/interop/qemu-qmp-ref.html sphinxdocs -info: docs/interop/qemu-qmp-ref.info -pdf: docs/interop/qemu-qmp-ref.pdf -txt: docs/interop/qemu-qmp-ref.txt - -docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-ref.html \ - docs/interop/qemu-qmp-ref.info docs/interop/qemu-qmp-ref.pdf \ - docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ - docs/interop/qemu-qmp-ref.texi docs/interop/qemu-qmp-qapi.texi +html: sphinxdocs =20 $(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl =20 @@ -1225,8 +1204,8 @@ endif @echo ' vm-help - Help about targets running tests inside VM' @echo '' @echo 'Documentation targets:' - @echo ' html info pdf txt' - @echo ' - Build documentation in specified format' + @echo ' html' + @echo ' - Build HTML documentation' ifdef CONFIG_GCOV @echo ' coverage-report - Create code coverage report' endif diff --git a/docs/index.html.in b/docs/index.html.in index f180770b052..b3dfb7a4611 100644 --- a/docs/index.html.in +++ b/docs/index.html.in @@ -12,7 +12,6 @@
  • Tools Guide
  • System Emulation Management= and Interoperability Guide
  • System Emulation Guest Hardwa= re Specifications
    • -
  • QMP Reference Manual
    • diff --git a/docs/interop/conf.py b/docs/interop/conf.py index e83632e0108..43de386d33d 100644 --- a/docs/interop/conf.py +++ b/docs/interop/conf.py @@ -21,4 +21,6 @@ man_pages =3D [ ['Michael Roth '], 8), ('qemu-ga-ref', 'qemu-ga-ref', u'QEMU Guest Agent Protocol Reference', [], 7), + ('qemu-qmp-ref', 'qemu-qmp-ref', u'QEMU QMP Reference Manual', + [], 7), ] diff --git a/docs/interop/index.rst b/docs/interop/index.rst index f3af38dce17..2cd97c6ff42 100644 --- a/docs/interop/index.rst +++ b/docs/interop/index.rst @@ -19,5 +19,6 @@ Contents: pr-helper qemu-ga qemu-ga-ref + qemu-qmp-ref vhost-user vhost-user-gpu diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst new file mode 100644 index 00000000000..e640903abaf --- /dev/null +++ b/docs/interop/qemu-qmp-ref.rst @@ -0,0 +1,4 @@ +QEMU QMP Reference Manual +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +.. qapi-doc:: qapi/qapi-schema.json diff --git a/docs/interop/qemu-qmp-ref.texi b/docs/interop/qemu-qmp-ref.texi deleted file mode 100644 index bb25758bd02..00000000000 --- a/docs/interop/qemu-qmp-ref.texi +++ /dev/null @@ -1,80 +0,0 @@ -\input texinfo -@setfilename qemu-qmp-ref.info - -@include version.texi - -@exampleindent 0 -@paragraphindent 0 - -@settitle QEMU QMP Reference Manual - -@iftex -@center @image{docs/qemu_logo} -@end iftex - -@copying -This is the QEMU QMP reference manual. - -Copyright @copyright{} 2016 The QEMU Project developers - -@quotation -This manual is free documentation: you can redistribute it and/or -modify it under the terms of the GNU General Public License as -published by the Free Software Foundation, either version 2 of the -License, or (at your option) any later version. - -This manual is distributed in the hope that it will be useful, but -WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this manual. If not, see http://www.gnu.org/licenses/. -@end quotation -@end copying - -@dircategory QEMU -@direntry -* QEMU-QMP-Ref: (qemu-qmp-ref). QEMU QMP Reference Manual -@end direntry - -@titlepage -@title QMP Reference Manual -@subtitle QEMU version @value{VERSION} -@page -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top -@top QEMU QMP reference -@end ifnottex - -@menu -* API Reference:: -* Commands and Events Index:: -* Data Types Index:: -@end menu - -@node API Reference -@chapter API Reference - -@c for texi2pod: -@c man begin DESCRIPTION - -@include qemu-qmp-qapi.texi - -@c man end - -@node Commands and Events Index -@unnumbered Commands and Events Index -@printindex fn - -@node Data Types Index -@unnumbered Data Types Index -@printindex tp - -@bye --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583770166; cv=none; d=zohomail.com; s=zohoarc; b=SmPcfCDkWptFT4i6yxmw7ZbTNYA5HfRcBETeRrORBoHoEFsT0ZK/VtTjynT000yWcBM3U4cgjGHQT/DeAekGvlGLdYeuBuzgV9zUosSPfZQi8oAWDvq1JPp4788Rwa3o+ZF7c6BzgXoBkrIys/xa+Mx0XyCMJ++PRj8osdYbuvQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583770166; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=MdwVWEG8hNJRFTkFaf2CNe1RBfSUpiMOo7qqDUbXW8o=; b=CAoi2dHELPKHBPT0NyPzDiOtNVrBCbbDzvLR7xBM1GRz50DNIgNrl7605y5FLWkYTmOG0CiZHZQQJBRvfGT/0pqy00MrMTTKm/Y99xz/x2bXkcBfhF3+6JPWXc1BCH/zWYqywTEJThbszAmbdB8TVPgo9LRT7X9xJizjcxnyk4U= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583770166171358.2491874496088; Mon, 9 Mar 2020 09:09:26 -0700 (PDT) Received: from localhost ([::1]:46140 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKwN-00033u-EY for importer@patchew.org; Mon, 09 Mar 2020 12:07:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40394) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZs-0001ub-Tv for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZq-0001Rb-Tm for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:23 -0400 Received: from mail-wr1-x434.google.com ([2a00:1450:4864:20::434]:39299) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZq-0001Qz-H1 for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:22 -0400 Received: by mail-wr1-x434.google.com with SMTP id r15so6771172wrx.6 for ; Mon, 09 Mar 2020 08:44:22 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.20 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=MdwVWEG8hNJRFTkFaf2CNe1RBfSUpiMOo7qqDUbXW8o=; b=gEKRq8iDoAqZkWTBvkuHXwNHCY68GM5AzQAThXtkGZWNiT4Y3xvqtEq9m7VFX/ZzBw wR13w7QPQyolMqockjEHsOvxRLU/Widh3owIt+YZUvt/WfFkLkeUabMFdO0oNZWFdDrP ImqIV2VFLJHya5g8I8UFCDgKWVc5QrcE59SXPRsgImT8tWtaQ6U/0g5RZbFTO0rMqHWx gkCv6yObbKfa6T1HEvZd6dXK1EYCGnZS8KP4TvctZ3FC2y5/TI79Wf82nzTwxiqUYWxT QooF+DSTD6XPt9/us2tAu/Egyja6VBLgmzkKRXZ7KUFdPOPaUkrheQed4W7LGwf9zipt 1Ysg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=MdwVWEG8hNJRFTkFaf2CNe1RBfSUpiMOo7qqDUbXW8o=; b=ErxjfL6zI3Siq9WvwkprXzKI7bk/RO43pg2bRYVwlbSAmrhfRSRbSiRqI7+FuJUGUe ukPqKRW7Pb38YLmsUR4cLIk/r8yfpDL//Awua9e0/G//PHZdwwp+kg065eRVWnCCaW86 BRTrlpRR3QJ6zX/RWG2er7e+z4X1IF3065/BEZPZY+7daldBYhadctt31/obOHQObBZR AhhpTAX7u6ERbpvPI+LjsYFaMmtv4d9XkEFB5/eyXfpp31lB6r8aQnuIV1OZeUDhKQXn aHw36wU3cNy77NZZe+u4voQ/MJ4ibMlir7OlpozddUcy6WGRT3i6Wm7HjUVxJ5RMsSHi FcWw== X-Gm-Message-State: ANhLgQ3nYfFDfWeBZHtxFCDotZDtRC+QJGjVtN9yvBeR2oAnXn1ygCF9 TYK+y1icYoeUVi/CUlQRPQ1qhLc2lP3t+w== X-Google-Smtp-Source: ADFU+vsgdDwT0ukFvqOXftOTGTRnFvkqi1ICSrDx80fDr/iOG58ZKccaCUv350y6IXTFHbch8rDUUQ== X-Received: by 2002:adf:e9c4:: with SMTP id l4mr9747058wrn.421.1583768661252; Mon, 09 Mar 2020 08:44:21 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 10/18] qapi: Use rST markup for literal blocks Date: Mon, 9 Mar 2020 15:43:57 +0000 Message-Id: <20200309154405.13548-11-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::434 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" There are exactly two places in our json doc comments where we use the markup accepted by the texi doc generator where a '|' in the first line of a doc comment means the line should be emitted as a literal block (fixed-width font, whitespace preserved). Since we use this syntax so rarely, instead of making the rST generator support it, instead just convert the two uses to rST-format literal blocks, which are indented and introduced with '::'. (The rST generator doesn't complain about the old style syntax, it just emits it with the '|' and with the whitespace not preserved, which looks odd, but means we can safely leave this change until after we've stopped generating texinfo.) Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qapi/block-core.json | 16 +++++++++------- qapi/qapi-schema.json | 6 ++++-- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 85e27bb61f4..0c9c21927f9 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -550,13 +550,15 @@ # For the example above, @bins may be something like [3, 1, 5, 2], # and corresponding histogram looks like: # -# | 5| * -# | 4| * -# | 3| * * -# | 2| * * * -# | 1| * * * * -# | +------------------ -# | 10 50 100 +# :: +# +# 5| * +# 4| * +# 3| * * +# 2| * * * +# 1| * * * * +# +------------------ +# 10 50 100 # # Since: 4.0 ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index ff5aea59451..440fece703f 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -22,8 +22,10 @@ # # Example: # -# | -> data issued by the Client -# | <- Server data response +# :: +# +# -> data issued by the Client +# <- Server data response # # Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for # detailed information on the Server command and response formats. --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583770151; cv=none; d=zohomail.com; s=zohoarc; b=M+UKFg7BlqLHvIUwskiAdeHYBcaQrRx6u6EitDuQhVLbinw0oHqVDHtVdWNU/HAVV2339vjSG36u4Xj69I1kb4lavdoDwxeVbDfn1qJC+9Ffe5DZEbzMY83KhBLn4dm8VdNcPXCot5N1+EQF7BLcFpSO0GxPJhKmOfNrLvHVscU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583770151; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=ct264XXsXB4Yfv0geBlQAhYKTLlUfdyjxR0wyex+U9E=; b=Qg5K+vZkOVkclp50gl37UNXuIdEd4iEw1OhNKacOfSuCPuad3u7jlFIcyzfAPiLTPU8VjCtcNencIw78k/lVAM3uaRdB29keC4mSSQliO+MDfY/JusewfMtmoLMhmrfnLb/LBELWLGMiMeBiXZKCqpBg7FYUro2nDaQasMOTrxg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583770151129879.2928829665556; Mon, 9 Mar 2020 09:09:11 -0700 (PDT) Received: from localhost ([::1]:46222 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKxp-0005V3-Re for importer@patchew.org; Mon, 09 Mar 2020 12:09:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40442) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZw-00023r-5V for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:29 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZr-0001S5-Pw for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:28 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:34024) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZr-0001Rh-Jb for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:23 -0400 Received: by mail-wr1-x444.google.com with SMTP id z15so11841245wrl.1 for ; Mon, 09 Mar 2020 08:44:23 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.21 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=ct264XXsXB4Yfv0geBlQAhYKTLlUfdyjxR0wyex+U9E=; b=evYc8kRjczeEQH2Qs21K6yiWdgRHCSLFFTg7G5An/ZueMmnxN6NYxn8rrBpSs5w5qi V4gFMh/g50lqoQ0JXvp4JHES/ijuxOqOEnuQhN1FZg9xYM2A5d7tO+uFSp/jRV6Tmiq9 FUmZWjUoMEYQJ0/0z0q8V0qnKRtNqSRx7jvs9AQlNlPbZ2lbD/mUE9+0DriYO+ywZCV+ aixZtGL/sC0ndqMdum5rUIFDxuJgu16Js/xQH+yLSji9JR6wGtV1alHJJtP08Ly/Opdb dB2Rg902mS3E7/gwWWfw2fc34+X2VBcVMlV1urcK8Y803KL8Ph2Ni8zyXmDFOkXoTRM/ sdtQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=ct264XXsXB4Yfv0geBlQAhYKTLlUfdyjxR0wyex+U9E=; b=QaBaOo8Ij4HE/9j3gFf9K/zzUC4f0/SfxP6V3V9WO0CpHC0EJT1Xo3MsPkj1YQ2KEb 2wQu28puYOwc45k2cdNG8vVn+wSqKyksdu87u2+Qk6DrqGmZTsXVRNT0Ve1b2QO/iUDu ye/f5hDE4xChFSv5KcQm38P+D04viUAqj+GZDLOGYs+qsX3kNW1IHWscgH7TX4ciBlSi rzJOWlcBmjwE34DvZFZTP7dePpjNMcxOCxyqrzWOhwWVu1l6tOFe7Iye30lUgrWl8VPe IbkKpiyw6uYRHV0poQSefCZfgrSNDtRBa/8jawQL/OeAgp2Do1m+FPY9It4SO5hSL2In 6ccQ== X-Gm-Message-State: ANhLgQ3RImsTXsUg9QYSHU7iclTscgmD9OO83V11EdblgKtCl58nW/nN wGZUXa/Z2MAvIgYJvQH+Y0/y21n7Ki9Fhw== X-Google-Smtp-Source: ADFU+vumDvYcQExR5DLOSsztmBV9p8Ir90H4ctmibCMxbrSd4vAYgERPM7aDqXId1wLKKhyQmFiFJg== X-Received: by 2002:a5d:640e:: with SMTP id z14mr7288051wru.204.1583768662427; Mon, 09 Mar 2020 08:44:22 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 11/18] qga/qapi-schema.json: Add some headings Date: Mon, 9 Mar 2020 15:43:58 +0000 Message-Id: <20200309154405.13548-12-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Add some section headings to the QGA json; this is purely so that we have some H1 headings, as otherwise each command ends up being visible in the interop/ manual's table of contents. In an ideal world there might be a proper 'Introduction' section the way there is in qapi/qapi-schema.json. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- qga/qapi-schema.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index f6fcb59f34b..d026f9478cf 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -1,14 +1,18 @@ # *-*- Mode: Python -*-* =20 ## -# -# General note concerning the use of guest agent interfaces: -# +# =3D General note concerning the use of guest agent interfaces +## + +## # "unsupported" is a higher-level error than the errors that individual # commands might document. The caller should always be prepared to receive # QERR_UNSUPPORTED, even if the given command doesn't specify it, or doesn= 't # document any failure mode at all. -# +## + +## +# =3D QEMU guest agent protocol commands and structs ## =20 { 'pragma': { 'doc-required': true } } --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769204; cv=none; d=zohomail.com; s=zohoarc; b=GeFEGIFvR8/ZkpoCYrOZM6vvGvO4Rhz1HuTggb8lbAfIZNf9kZ83Xc6oYqLQl+nYgYuSJi8+07mHhKsMw+88UeAxI0DeUda3dTxH+mk9nVW1e9SP6bQ2kzn2B1Ro0tXUoWa98PzNiXzwvg97JPJ4+jyAw5FZohjq9Tfa1OWwB6I= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769204; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=H28XFpk/HyenrbL5LCX9nx7SvUjsGeRUJq+J1pjN85k=; b=YbOe0l+5pYHR/3PhqDVGQJnENBsgBVSdyFntS3KJizkb6LUUEoF6MZ0agsGKeK5TDGMRqJ/pS5jh7jALbh675F47AuKEeBUm2xqaXVHwiAMoQOVksLc+aNMki3o8Na9TYJ2xIrpsZZ9c6926Xg8RRSWz2wfK5y+aagQr3loafl8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769204151752.7970381038041; Mon, 9 Mar 2020 08:53:24 -0700 (PDT) Received: from localhost ([::1]:45664 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKiY-0006fV-O5 for importer@patchew.org; Mon, 09 Mar 2020 11:53:22 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40452) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZw-00025L-MV for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:31 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZt-0001T1-Tj for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:28 -0400 Received: from mail-wr1-x443.google.com ([2a00:1450:4864:20::443]:44697) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZt-0001SP-Jz for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:25 -0400 Received: by mail-wr1-x443.google.com with SMTP id l18so1741909wru.11 for ; Mon, 09 Mar 2020 08:44:25 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.22 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=H28XFpk/HyenrbL5LCX9nx7SvUjsGeRUJq+J1pjN85k=; b=X87bvay2DXE8vVl4EQfMmr1sxBY7VCG3ht/OUqIOlYvgPvY1AbkNWKpAHV8dfnycu3 CocHSk4m4yr5mXEdQZMr8lkoXpAjEEPooc75h2lBuwAuXh7IgqgEbH7rcfbz4cGT80vy KO39P6RcMeVPROWzVZWeJOT+BXclVstgBgRji99oxy85PHu4eAYZkbATHt1P7LWGKifG iDaWDmj0DJUv6V3EFOf22KtOnbtIgNZt4seQ1+gRMJEgr1h4cCbZNogDm8GpswAQl3KP 5PPh5OvqbPWOsS/4jnhtIaecYK1qaqKWQMO7J7bqD7jDSJcA1kbLiEQU8E1gqUBH+B/q HlDw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=H28XFpk/HyenrbL5LCX9nx7SvUjsGeRUJq+J1pjN85k=; b=ke7pEleSO4jlVe4hatBGcOibqR4Wm0wrfiFLQ6FsZrzm/Wl1txUiV2fSAgSufd5sXc BVPlgU/f0jZPaBgS+iTIUCpowCu/pQMlyacLwTvcbduhpWefBz4vjZupNPAB0Ytq+4+u tyyFo9N74t6QkmrobCx9A3stSw895pUsSbetKFgcjxGFweshl2IvYOp+6u4VT0VgUiD6 zFbsGHDTPs5Q6oUHSIfrHy+0TDhcq70kBd24D6PTSSxWdjYi6QpAwRH5SBHkYYgPBdsI 935zQkbU8yvMvCllvzqn3YuWvIdoRABbMuJIjYcqJ9dpY7yv/kYitvKoFhL3mPlsbIzO cSNg== X-Gm-Message-State: ANhLgQ16ZRAnvAjuOYDqP9WCIMd5tCL2pbGaEPQQh1ZoaN/lCLBlMbLX DQoMDHtcRrbfrG25isv+/lY6XZlrx6MToA== X-Google-Smtp-Source: ADFU+vsktvpzLZoxLBJWOxvYPD84zs2HSBF+zkmPkZ/S+R12eGA8N5xg4kVCe9hnlOF+qxDctenR2Q== X-Received: by 2002:adf:fd11:: with SMTP id e17mr20442242wrr.195.1583768663905; Mon, 09 Mar 2020 08:44:23 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 12/18] scripts/qapi: Remove texinfo generation support Date: Mon, 9 Mar 2020 15:43:59 +0000 Message-Id: <20200309154405.13548-13-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::443 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We no longer use the generated texinfo format documentation, so delete the code that generates it, and the test case for the generation. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- Makefile | 1 - tests/Makefile.include | 15 +- scripts/qapi-gen.py | 2 - scripts/qapi/doc.py | 302 -------------------------------- scripts/qapi/gen.py | 7 - tests/qapi-schema/doc-good.texi | 281 ----------------------------- 6 files changed, 1 insertion(+), 607 deletions(-) delete mode 100644 scripts/qapi/doc.py delete mode 100644 tests/qapi-schema/doc-good.texi diff --git a/Makefile b/Makefile index 6dcc39efcee..98f58b84ef0 100644 --- a/Makefile +++ b/Makefile @@ -610,7 +610,6 @@ qemu-keymap$(EXESUF): QEMU_CFLAGS +=3D $(XKBCOMMON_CFLA= GS) qapi-py =3D $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ diff --git a/tests/Makefile.include b/tests/Makefile.include index edcbd475aa7..ee84107e1be 100644 --- a/tests/Makefile.include +++ b/tests/Makefile.include @@ -32,7 +32,6 @@ export SRC_PATH qapi-py =3D $(SRC_PATH)/scripts/qapi/__init__.py \ $(SRC_PATH)/scripts/qapi/commands.py \ $(SRC_PATH)/scripts/qapi/common.py \ -$(SRC_PATH)/scripts/qapi/doc.py \ $(SRC_PATH)/scripts/qapi/error.py \ $(SRC_PATH)/scripts/qapi/events.py \ $(SRC_PATH)/scripts/qapi/expr.py \ @@ -488,16 +487,8 @@ tests/test-qapi-gen-timestamp: \ $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ -o tests -p "test-" $<, \ "GEN","$(@:%-timestamp=3D%)") - @rm -f tests/test-qapi-doc.texi @>$@ =20 -tests/qapi-schema/doc-good.test.texi: $(SRC_PATH)/tests/qapi-schema/doc-go= od.json $(qapi-py) - $(call quiet-command,$(PYTHON) $(SRC_PATH)/scripts/qapi-gen.py \ - -o tests/qapi-schema -p "doc-good-" $<, \ - "GEN","$@") - @mv tests/qapi-schema/doc-good-qapi-doc.texi $@ - @rm -f tests/qapi-schema/doc-good-qapi-*.[ch] tests/qapi-schema/doc-good-= qmp-*.[ch] - tests/qtest/dbus-vmstate1.h tests/qtest/dbus-vmstate1.c: tests/qtest/dbus-= vmstate1-gen-timestamp ; tests/qtest/dbus-vmstate1-gen-timestamp: $(SRC_PATH)/tests/qtest/dbus-vmst= ate1.xml $(call quiet-command,$(GDBUS_CODEGEN) $< \ @@ -849,10 +840,6 @@ check-tests/qapi-schema/frontend: $(addprefix $(SRC_PA= TH)/, $(check-qapi-schema- PYTHONIOENCODING=3Dutf-8 $(PYTHON) $(SRC_PATH)/tests/qapi-schema/test-q= api.py $^, \ TEST, check-qapi-schema) =20 -.PHONY: check-tests/qapi-schema/doc-good.texi -check-tests/qapi-schema/doc-good.texi: tests/qapi-schema/doc-good.test.texi - @diff -u $(SRC_PATH)/tests/qapi-schema/doc-good.texi $< - .PHONY: check-decodetree check-decodetree: $(call quiet-command, \ @@ -900,7 +887,7 @@ check-acceptance: check-venv $(TESTS_RESULTS_DIR) # Consolidated targets =20 .PHONY: check-block check-qapi-schema check-qtest check-unit check check-c= lean -check-qapi-schema: check-tests/qapi-schema/frontend check-tests/qapi-schem= a/doc-good.texi +check-qapi-schema: check-tests/qapi-schema/frontend check-qtest: $(patsubst %,check-qtest-%, $(QTEST_TARGETS)) ifeq ($(CONFIG_TOOLS),y) check-block: $(patsubst %,check-%, $(check-block-y)) diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py index 4b03f7d53be..541e8c1f55d 100755 --- a/scripts/qapi-gen.py +++ b/scripts/qapi-gen.py @@ -10,7 +10,6 @@ import re import sys =20 from qapi.commands import gen_commands -from qapi.doc import gen_doc from qapi.events import gen_events from qapi.introspect import gen_introspect from qapi.schema import QAPIError, QAPISchema @@ -51,7 +50,6 @@ def main(argv): gen_commands(schema, args.output_dir, args.prefix) gen_events(schema, args.output_dir, args.prefix) gen_introspect(schema, args.output_dir, args.prefix, args.unmask) - gen_doc(schema, args.output_dir, args.prefix) =20 =20 if __name__ =3D=3D '__main__': diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py deleted file mode 100644 index 26cd1a1751e..00000000000 --- a/scripts/qapi/doc.py +++ /dev/null @@ -1,302 +0,0 @@ -# QAPI texi generator -# -# This work is licensed under the terms of the GNU LGPL, version 2+. -# See the COPYING file in the top-level directory. -"""This script produces the documentation of a qapi schema in texinfo form= at""" - -import re -from qapi.gen import QAPIGenDoc, QAPISchemaVisitor - - -MSG_FMT =3D """ -@deftypefn {type} {{}} {name} - -{body}{members}{features}{sections} -@end deftypefn - -""".format - -TYPE_FMT =3D """ -@deftp {{{type}}} {name} - -{body}{members}{features}{sections} -@end deftp - -""".format - -EXAMPLE_FMT =3D """@example -{code} -@end example -""".format - - -def subst_strong(doc): - """Replaces *foo* by @strong{foo}""" - return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) - - -def subst_emph(doc): - """Replaces _foo_ by @emph{foo}""" - return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) - - -def subst_vars(doc): - """Replaces @var by @code{var}""" - return re.sub(r'@([\w-]+)', r'@code{\1}', doc) - - -def subst_braces(doc): - """Replaces {} with @{ @}""" - return doc.replace('{', '@{').replace('}', '@}') - - -def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, = we - # need to delay it until after subst_vars() in texi_format(). - doc =3D subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=3Ddoc) - - -def texi_format(doc): - """ - Format documentation - - Lines starting with: - - |: generates an @example - - =3D: generates @section - - =3D=3D: generates @subsection - - 1. or 1): generates an @enumerate @item - - */-: generates an @itemize list - """ - ret =3D '' - doc =3D subst_braces(doc) - doc =3D subst_vars(doc) - doc =3D subst_emph(doc) - doc =3D subst_strong(doc) - inlist =3D '' - lastempty =3D False - for line in doc.split('\n'): - line =3D line.strip() - empty =3D line =3D=3D '' - - # 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), - # but a line with some *other* markup, such as a =3D title - # doesn't. - # - # Make sure to update section "Documentation markup" in - # docs/devel/qapi-code-gen.txt when fixing this. - if line.startswith('| '): - line =3D EXAMPLE_FMT(code=3Dline[2:]) - elif line.startswith('=3D '): - line =3D '@section ' + line[2:] - elif line.startswith('=3D=3D '): - line =3D '@subsection ' + line[3:] - elif re.match(r'^([0-9]*\.) ', line): - if not inlist: - ret +=3D '@enumerate\n' - inlist =3D 'enumerate' - ret +=3D '@item\n' - line =3D line[line.find(' ')+1:] - elif re.match(r'^[*-] ', line): - if not inlist: - ret +=3D '@itemize %s\n' % {'*': '@bullet', - '-': '@minus'}[line[0]] - inlist =3D 'itemize' - ret +=3D '@item\n' - line =3D line[2:] - elif lastempty and inlist: - ret +=3D '@end %s\n\n' % inlist - inlist =3D '' - - lastempty =3D empty - ret +=3D line + '\n' - - if inlist: - ret +=3D '@end %s\n\n' % inlist - return ret - - -def texi_body(doc): - """Format the main documentation body""" - return texi_format(doc.body.text) - - -def texi_if(ifcond, prefix=3D'\n', suffix=3D'\n'): - """Format the #if condition""" - if not ifcond: - return '' - return '%s@b{If:} @code{%s}%s' % (prefix, ', '.join(ifcond), suffix) - - -def texi_enum_value(value, desc, suffix): - """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n%s%s' % ( - value.name, desc, texi_if(value.ifcond, prefix=3D'@*')) - - -def texi_member(member, desc, suffix): - """Format a table of members item for an object type member""" - typ =3D member.type.doc_type() - membertype =3D ': ' + typ if typ else '' - return '@item @code{%s%s}%s%s\n%s%s' % ( - member.name, membertype, - ' (optional)' if member.optional else '', - suffix, desc, texi_if(member.ifcond, prefix=3D'@*')) - - -def texi_members(doc, what, base=3DNone, variants=3DNone, - member_func=3Dtexi_member): - """Format the table of members""" - items =3D '' - for section in doc.args.values(): - # TODO Drop fallbacks when undocumented members are outlawed - if section.text: - desc =3D texi_format(section.text) - elif (variants and variants.tag_member =3D=3D section.member - and not section.member.type.doc_type()): - values =3D section.member.type.member_names() - members_text =3D ', '.join(['@t{"%s"}' % v for v in values]) - desc =3D 'One of ' + members_text + '\n' - else: - desc =3D 'Not documented\n' - items +=3D member_func(section.member, desc, suffix=3D'') - if base: - items +=3D '@item The members of @code{%s}\n' % base.doc_type() - if variants: - for v in variants.variants: - when =3D ' when @code{%s} is @t{"%s"}%s' % ( - variants.tag_member.name, v.name, texi_if(v.ifcond, " (", = ")")) - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - items +=3D member_func(m, desc=3D'', suffix=3Dwhen) - else: - items +=3D '@item The members of @code{%s}%s\n' % ( - v.type.doc_type(), when) - if not items: - return '' - return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) - - -def texi_arguments(doc, boxed_arg_type): - if boxed_arg_type: - assert not doc.args - return ('\n@b{Arguments:} the members of @code{%s}\n' - % boxed_arg_type.name) - return texi_members(doc, 'Arguments') - - -def texi_features(doc): - """Format the table of features""" - items =3D '' - for section in doc.features.values(): - desc =3D texi_format(section.text) - items +=3D '@item @code{%s}\n%s' % (section.name, desc) - if not items: - return '' - return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items) - - -def texi_sections(doc, ifcond): - """Format additional sections following arguments""" - body =3D '' - for section in doc.sections: - if section.name: - # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body +=3D '\n@b{%s:}\n' % section.name - if section.name and section.name.startswith('Example'): - body +=3D texi_example(section.text) - else: - body +=3D texi_format(section.text) - body +=3D texi_if(ifcond, suffix=3D'') - return body - - -def texi_type(typ, doc, ifcond, members): - return TYPE_FMT(type=3Dtyp, - name=3Ddoc.symbol, - body=3Dtexi_body(doc), - members=3Dmembers, - features=3Dtexi_features(doc), - sections=3Dtexi_sections(doc, ifcond)) - - -def texi_msg(typ, doc, ifcond, members): - return MSG_FMT(type=3Dtyp, - name=3Ddoc.symbol, - body=3Dtexi_body(doc), - members=3Dmembers, - features=3Dtexi_features(doc), - sections=3Dtexi_sections(doc, ifcond)) - - -class QAPISchemaGenDocVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._prefix =3D prefix - self._gen =3D QAPIGenDoc(self._prefix + 'qapi-doc.texi') - self.cur_doc =3D None - - def write(self, output_dir): - self._gen.write(output_dir) - - def visit_enum_type(self, name, info, ifcond, members, prefix): - doc =3D self.cur_doc - self._gen.add(texi_type('Enum', doc, ifcond, - texi_members(doc, 'Values', - member_func=3Dtexi_enum_value= ))) - - def visit_object_type(self, name, info, ifcond, base, members, variant= s, - features): - doc =3D self.cur_doc - if base and base.is_implicit(): - base =3D None - self._gen.add(texi_type('Object', doc, ifcond, - texi_members(doc, 'Members', base, variant= s))) - - def visit_alternate_type(self, name, info, ifcond, variants): - doc =3D self.cur_doc - self._gen.add(texi_type('Alternate', doc, ifcond, - texi_members(doc, 'Members'))) - - def visit_command(self, name, info, ifcond, arg_type, ret_type, gen, - success_response, boxed, allow_oob, allow_preconfig, - features): - doc =3D self.cur_doc - self._gen.add(texi_msg('Command', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None)= )) - - def visit_event(self, name, info, ifcond, arg_type, boxed): - doc =3D self.cur_doc - self._gen.add(texi_msg('Event', doc, ifcond, - texi_arguments(doc, - arg_type if boxed else None)= )) - - def symbol(self, doc, entity): - if self._gen._body: - self._gen.add('\n') - self.cur_doc =3D doc - entity.visit(self) - self.cur_doc =3D None - - def freeform(self, doc): - assert not doc.args - if self._gen._body: - self._gen.add('\n') - self._gen.add(texi_body(doc) + texi_sections(doc, None)) - - -def gen_doc(schema, output_dir, prefix): - vis =3D QAPISchemaGenDocVisitor(prefix) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - vis.write(output_dir) diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py index 33690bfa3bd..acb97cd61e1 100644 --- a/scripts/qapi/gen.py +++ b/scripts/qapi/gen.py @@ -173,13 +173,6 @@ def ifcontext(ifcond, *args): arg.end_if() =20 =20 -class QAPIGenDoc(QAPIGen): - - def _top(self): - return (super()._top() - + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') - - class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor): =20 def __init__(self, prefix, what, blurb, pydoc): diff --git a/tests/qapi-schema/doc-good.texi b/tests/qapi-schema/doc-good.t= exi deleted file mode 100644 index 1e8063c8579..00000000000 --- a/tests/qapi-schema/doc-good.texi +++ /dev/null @@ -1,281 +0,0 @@ -@c AUTOMATICALLY GENERATED, DO NOT MODIFY - -@section Section - -@subsection Subsection - -@strong{strong} @emph{with emphasis} -@code{var} @{in braces@} - -@itemize @bullet -@item -List item one -@item -Two, multiple -lines - -@item -Three -Still in list - -@end itemize - -Not in list - -@itemize @minus -@item -Second list -Note: still in list - -@end itemize - -Note: not in list - -@enumerate -@item -Third list -is numbered - -@item -another item - -@end enumerate - -Returns: the King -Since: the first age -Notes: - -@enumerate -@item -Lorem ipsum dolor sit amet - -@item -Ut enim ad minim veniam - -@end enumerate - -Duis aute irure dolor - -Example: - --> in -<- out -Examples: -@itemize @minus -@item -@strong{verbatim} -@item -@{braces@} -@end itemize - - - -@deftp {Enum} Enum - - - -@b{Values:} -@table @asis -@item @code{one} -The @emph{one} @{and only@} -@*@b{If:} @code{defined(IFONE)} -@item @code{two} -Not documented -@end table -@code{two} is undocumented - -@b{If:} @code{defined(IFCOND)} -@end deftp - - - -@deftp {Object} Base - - - -@b{Members:} -@table @asis -@item @code{base1: Enum} -the first member -@end table - -@end deftp - - - -@deftp {Object} Variant1 - -A paragraph - -Another paragraph (but no @code{var}: line) - -@b{Members:} -@table @asis -@item @code{var1: string} -Not documented -@*@b{If:} @code{defined(IFSTR)} -@end table - -@b{Features:} -@table @asis -@item @code{variant1-feat} -a feature -@end table - -@end deftp - - - -@deftp {Object} Variant2 - - - -@end deftp - - - -@deftp {Object} Object - - - -@b{Members:} -@table @asis -@item The members of @code{Base} -@item The members of @code{Variant1} when @code{base1} is @t{"one"} -@item The members of @code{Variant2} when @code{base1} is @t{"two"} (@b{If= :} @code{IFTWO}) -@end table - -@end deftp - - - -@deftp {Object} SugaredUnion - - - -@b{Members:} -@table @asis -@item @code{type} -One of @t{"one"}, @t{"two"} -@item @code{data: Variant1} when @code{type} is @t{"one"} -@item @code{data: Variant2} when @code{type} is @t{"two"} (@b{If:} @code{I= FTWO}) -@end table - -@end deftp - - - -@deftp {Alternate} Alternate - - - -@b{Members:} -@table @asis -@item @code{i: int} -an integer -@code{b} is undocumented -@item @code{b: boolean} -Not documented -@end table - -@end deftp - - -@subsection Another subsection - - -@deftypefn Command {} cmd - - - -@b{Arguments:} -@table @asis -@item @code{arg1: int} -the first argument -@item @code{arg2: string} (optional) -the second -argument -@item @code{arg3: boolean} -Not documented -@end table - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Note:} -@code{arg3} is undocumented - -@b{Returns:} -@code{Object} - -@b{TODO:} -frobnicate - -@b{Notes:} -@itemize @minus -@item -Lorem ipsum dolor sit amet -@item -Ut enim ad minim veniam - -@end itemize - -Duis aute irure dolor - -@b{Example:} -@example --> in -<- out -@end example - -@b{Examples:} -@example -- *verbatim* -- @{braces@} -@end example - -@b{Since:} -2.10 - -@end deftypefn - - - -@deftypefn Command {} cmd-boxed - -If you're bored enough to read this, go see a video of boxed cats - -@b{Arguments:} the members of @code{Object} - -@b{Features:} -@table @asis -@item @code{cmd-feat1} -a feature -@item @code{cmd-feat2} -another feature -@end table - -@b{Example:} -@example --> in - -<- out -@end example - -@end deftypefn - - - -@deftypefn Event {} EVT-BOXED - - - -@b{Arguments:} the members of @code{Object} - -@end deftypefn - --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769132; cv=none; d=zohomail.com; s=zohoarc; b=b4w1JnZFdfNu3t9yWpSa/CWVSGQZh+I8kzUaSiupnxoxYkYWbBT6NxTQ0gkDZKUMS/J48sXVhk+5jUF6Dxx7gHrcYgdopQB3KS/+6z5vtjX2GqVPDtCVzZSK+x0KhYK9mHaoQSNfG1Yc6SzTDdCWeKA5iFmLx/G+GzpSIMu/sec= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769132; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=d66UtwcTx8sk1z+jnFdvKiE6e5kZa9mz22mT1Fj9pkNsVYtauTDLYgSvJMCeSi+2wDUKwQTmZyKl7WWnAS7Zu/rGbU8ZSoFmCsNELMj0QPNNR4yHjUR1DBUTIYCOgGLgSgT6UilgznhMNBW3DjzzzKqhe0Lw7KV65w7xD2y2NR4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769132814750.6278636306994; Mon, 9 Mar 2020 08:52:12 -0700 (PDT) Received: from localhost ([::1]:45630 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKhP-0004SP-GN for importer@patchew.org; Mon, 09 Mar 2020 11:52:11 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40454) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZw-00025V-Ov for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:30 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZv-0001Ts-3b for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:28 -0400 Received: from mail-wm1-x341.google.com ([2a00:1450:4864:20::341]:35210) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZu-0001T5-Sl for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:27 -0400 Received: by mail-wm1-x341.google.com with SMTP id m3so18490wmi.0 for ; Mon, 09 Mar 2020 08:44:26 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=TGoLeNuEJ/TkzEEkucpSjmr87po1trVzN4R2j50DSb4Hru8kMGvalx697qakamPQd2 5FXyUw8LXPqyjzsOMN+bpgQFLz5X4Shs+OXR5h/d4ORCyw3m5OJnSb/20blOUZGg+OAd J4EYKcgkjP69lvVpZbYGy77oKP1PZFv8Twroi8q8E/iK3KY90ND1PsSq1DQu1ih0Khv2 6rNW5xpmyrOg9trLjm2fQBJKc25b5ZZ4QcE8NtB2C17KrIcn4mvxZ/ANb/44mlJZptx6 2Xq9S22CuvZjQQQzekwsF7bIAc4oZjGfhwQKZblYsQIZqHd+mQG9NoTuTPxIJMeqnOE4 bGPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=AtxEKrKRqNjfOrT9JbNHlMjgTudjr9VoMdnqfaiOYHo=; b=ZtDEbGqrXB6il6Gz5N2NOKUByxOv24I/42t4c5VGWMVnq754zOQItcWtEvTgJSw52S KKfWEVp82B0lUP6pNRyF6WQerlNQ0gZC2/JH0jXDG79ba02iRNMmH7ctyJAk/oJS2XJV ZxdBaNi3R/GgpF/8Hq/k+HnRw6njRoeSv0lt3vLMxiTxOAZCbXnLwQ760D7aB0XkKxns APAKI8y1hLevssUfQiLEIHP5WczW8ezTih5OobL1tnOg2zWh33yYIOswVZPyFRen2mwv nIv74wz5oSi4YD6bFAN6XmOqKDgepKIbvxsV1cAfiSqDC3fCsy+EZVi23AEa7eZsLy2t BAQA== X-Gm-Message-State: ANhLgQ1FPEl+AWhTDBYwMo/Nb98rMw63HQ3yaWSF/c1PVgAtgYJU1Uuu obbkWqRSmi0TnqGf8akIZXZPTN39gOQ4dg== X-Google-Smtp-Source: ADFU+vuGhX+RwyBU5IWua38XiGPf4N2victvAnVK+6ufOjq79v0h38BjQfQ0PIHfc32OgHXXDRsZsw== X-Received: by 2002:a05:600c:22cd:: with SMTP id 13mr13157162wmg.186.1583768665188; Mon, 09 Mar 2020 08:44:25 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 13/18] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Date: Mon, 9 Mar 2020 15:44:00 +0000 Message-Id: <20200309154405.13548-14-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::341 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" Update the documentation of QAPI document comment syntax to match the new rST backend requirements. The principal changes are: * whitespace is now significant, and multiline definitions must have their second and subsequent lines indented to match the first line * general rST format markup is permitted, not just the small set of markup the old texinfo generator handled. For most things (notably bulleted and itemized lists) the old format is the same as rST was. * Specific things that might trip people up: - instead of *bold* and _italic_ rST has **bold** and *italic* - lists need a preceding and following blank line - a lone literal '*' will need to be backslash-escaped to avoid a rST syntax error * the old leading '|' for example (literal text) blocks is replaced by the standard rST '::' literal block. * headings and subheadings must now be in a freeform documentation comment of their own * we support arbitrary levels of sub- and sub-sub-heading, not just a main and sub-heading like the old texinfo generator Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------ 1 file changed, 61 insertions(+), 29 deletions(-) diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index 59d6973e1ec..688eb2a0237 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -795,21 +795,39 @@ See below for more on definition documentation. Free-form documentation may be used to provide additional text and structuring content. =20 +=3D=3D=3D=3D Headings and subheadings =3D=3D=3D=3D + +A free-form documentation comment containing a single line +which starts with some '=3D' symbols and then a space defines +a section heading: + + ## + # =3D This is a top level heading + ## + + ## + # This is a free-form comment which will go under the + # top level heading. + ## + + ## + # =3D=3D This is a second level heading + ## + +Section headings must always be correctly nested, so you can only +define a third-level heading inside a second-level heading, and so +on. The documentation generator will catch nesting mistakes and report +a syntax error. =20 =3D=3D=3D=3D Documentation markup =3D=3D=3D=3D =20 -Comment text starting with '=3D' is a section title: +Documentation comments can use most rST markup. In particular, +a '::' literal block can be used for examples: =20 - # =3D Section title - -Double the '=3D' for a subsection title: - - # =3D=3D Subsection title - -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines + # :: + # + # Text of the example, may span + # multiple lines =20 '*' starts an itemized list: =20 @@ -825,37 +843,35 @@ A decimal number followed by '.' starts a numbered li= st: # multiple lines # 2. Second item =20 -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. +The actual number doesn't matter. =20 -Lists can't be nested. Blank lines are currently not supported within -lists. +Lists of either kind must be preceded and followed by a blank line. +If a list item's text spans multiple lines, then the second and +subsequent lines must be correctly indented to line up with the +first character of the first line. =20 -Additional whitespace between the initial '#' and the comment text is -permitted. - -*foo* and _foo_ are for strong and emphasis styles respectively (they -do not work over multiple lines). @foo is used to reference a name in -the schema. +The usual '**strong**', '*emphasised*' and '``literal``' markup should +be used. If you need a single literal '*' you will need to backslash-escap= e it. +As an extension beyond the usual rST syntax, you can also +use '@foo' to reference a name in the schema; this is rendered +the same way as '``foo``'. =20 Example: =20 ## -# =3D Section -# =3D=3D Subsection -# -# Some text foo with *strong* and _emphasis_ +# Some text foo with **bol** and *emphasis* # 1. with a list # 2. like that # # And some code: -# | $ echo foo -# | -> do this -# | <- get that # +# :: +# +# $ echo foo +# -> do this +# <- get that ## =20 - =3D=3D=3D=3D Definition documentation =3D=3D=3D=3D =20 Definition documentation, if present, must immediately precede the @@ -870,6 +886,12 @@ commands and events), member (for structs and unions),= branch (for alternates), or value (for enums), and finally optional tagged sections. =20 +Descriptions of arguments can span multiple lines; if they +do then the second and subsequent lines must be indented +to line up with the first character of the first line of the +description. The parser will report a syntax error if there +is insufficient indentation. + FIXME: the parser accepts these things in almost any order. FIXME: union branches should be described, too. =20 @@ -883,6 +905,16 @@ The section ends with the start of a new section. A 'Since: x.y.z' tagged section lists the release that introduced the definition. =20 +The text of a section can start on a new line, in +which case it must not be indented at all. It can also start +on the same line as the 'Note:', 'Returns:', etc tag. In this +case if it spans multiple lines then second and subsequent +lines must be indented to match the first. + +An 'Example' or 'Examples' section is automatically rendered +entirely as literal fixed-width text. In other sections, +the text is formatted, and rST markup can be used. + For example: =20 ## --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769269; cv=none; d=zohomail.com; s=zohoarc; b=OCoIk9ad5egFTV1U5SgC5SxkER64gTALrLvhZpyKmy4YSL6acKpToJGzKCm6YaHp60eq9YWbF0/DJJKU8PKr4bGeX76UdrcD5MPxWRMAmUfTNRZxqJwNMqOKlCjs98QuToFUZIWa95RNJ7Mn4ZYcyT4L+6+qplg2pMRherEAbyE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769269; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=xNFVrqrgv4Q6fMRbpldg27PAr4NFe+ct3Bp7b377yzc=; b=nBBUgVkhqch4qRk+5Sv2xsCqiHAtH/bk59G1Pi00uey3sdIeRRaHOR7yQCtcIWpU0Y6arpNX9JgWY388G3KsrcIRO/WdhgRgMPAqzHyCn8OvFlMBkg778WFCBud8rhUxp6sSoNOJrtsOCtxvcefuVPYUeM7RzhBgV9eAAYdmpI4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769269484413.3735831426418; Mon, 9 Mar 2020 08:54:29 -0700 (PDT) Received: from localhost ([::1]:45698 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKjc-00005J-Aq for importer@patchew.org; Mon, 09 Mar 2020 11:54:28 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40482) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKZx-00027r-MH for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:31 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZw-0001V3-3O for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:29 -0400 Received: from mail-wr1-x443.google.com ([2a00:1450:4864:20::443]:40359) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZv-0001U2-Rz for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:28 -0400 Received: by mail-wr1-x443.google.com with SMTP id p2so11015255wrw.7 for ; Mon, 09 Mar 2020 08:44:27 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:25 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=xNFVrqrgv4Q6fMRbpldg27PAr4NFe+ct3Bp7b377yzc=; b=m2jlWF/94JET/z9oJjviUIgEbcRO2EagzBLwqW4xFn8j33UQ/Meixbu7zzt1elTpw6 Jq6NiZgL0nUoyngKm/BOkTbt0ugwoS+8iUvceAJFGO0mXf1Y1w3L/A0mD7FpWy/newag Km6S3SLurzo6i4TBlskTMwVoWoQ5iYlohb1DU7PlmPGe68xRR4b0LbWdznRT4tD6Dh7D YE2QtZWVGhh99TRWUNBtCXUAVaaR1/V7THnJqqzzaWHTcJuGJUAyaH7+4UfJI8w6vU2x 73kCc/iyzzsNHQqtRWQd40p5493i2fVPGt/0bB3L9CFI5pXMveebECIeM5jSfiskvXU8 PYSg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=xNFVrqrgv4Q6fMRbpldg27PAr4NFe+ct3Bp7b377yzc=; b=cEJ/dh1Fw6B3bQjc3PiIN65kEogDdA89UT/+aPO3RL7eQN4cIXZjenn+TxG1U8JOyj kqBCF1d+grZ5tqWdfH2iL7MEIoACG2r+FzisOHEbF69G94lb6GisMbcAlMgDG9WTL3m3 nTkbucjuNv79E7jeH51Xf05NWcOdpp8mZBTQNO5f8NQzrF4PBF+I3iGxx2yxZ4qiCsdp buRwwvzTeT0HElZsAtNAqCZ7HOY2IHz/ZpaR2a6KiufoVEpY+XjtTMarQmc3rYOPDlQ1 o1uuF99ZGbgAn88YITB79Djluj6ACEhRRCM8iaL1B/zkU26k+5OqMVAW3wLfpLEpemOf vG/A== X-Gm-Message-State: ANhLgQ32Bed/NRtflW1fBkUu24QAXS8eAwFUxp15y+Au+uOokieYFG5N wrGzqgWEI5zDaquWZOVDG5mtpW9ECf1p6g== X-Google-Smtp-Source: ADFU+vsfM5f2wLk1VSe1Vi7MgxjbEtoWjgmH6saOXNW+kPrY3qii6r2FH63C8mio9104KwfMc/5y/w== X-Received: by 2002:a5d:4386:: with SMTP id i6mr12854243wrq.412.1583768666516; Mon, 09 Mar 2020 08:44:26 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 14/18] Makefile: Remove redundant Texinfo related rules Date: Mon, 9 Mar 2020 15:44:01 +0000 Message-Id: <20200309154405.13548-15-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::443 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We now don't build anything from Texinfo, so we can remove some redundant Makefile pattern rules and the rule for generating the version.texi file that used to be included from many Texinfo source files. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- Makefile | 31 +------------------------------ rules.mak | 14 +------------- 2 files changed, 2 insertions(+), 43 deletions(-) diff --git a/Makefile b/Makefile index 98f58b84ef0..36fe8d6e641 100644 --- a/Makefile +++ b/Makefile @@ -732,8 +732,7 @@ clean: recurse-clean ! -path ./roms/edk2/BaseTools/Source/Python/UPT/Dll/sqlite3.dll \ -exec rm {} + rm -f $(edk2-decompressed) - rm -f $(filter-out %.tlb,$(TOOLS)) $(HELPERS-y) TAGS cscope.* *.pod *~ */= *~ - rm -f fsdev/*.pod scsi/*.pod + rm -f $(filter-out %.tlb,$(TOOLS)) $(HELPERS-y) TAGS cscope.* *~ */*~ rm -f qemu-img-cmds.h rm -f ui/shader/*-vert.h ui/shader/*-frag.h @# May not be present in generated-files-y @@ -766,7 +765,6 @@ distclean: clean rm -f qemu-plugins-ld.symbols qemu-plugins-ld64.symbols rm -f config.log rm -f linux-headers/asm - rm -f docs/version.texi rm -rf .doctrees $(call clean-manual,devel) $(call clean-manual,interop) @@ -987,31 +985,6 @@ ui/shader.o: $(SRC_PATH)/ui/shader.c \ ui/shader/texture-blit-frag.h =20 # documentation -MAKEINFO=3Dmakeinfo -MAKEINFOINCLUDES=3D -I docs -I $( $@,"GEN","$@") - -%.html: %.texi docs/version.texi - $(call quiet-command,LC_ALL=3DC $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers= \ - --html $< -o $@,"GEN","$@") - -%.info: %.texi docs/version.texi - $(call quiet-command,$(MAKEINFO) $(MAKEINFOFLAGS) $< -o $@,"GEN","$@") - -%.txt: %.texi docs/version.texi - $(call quiet-command,LC_ALL=3DC $(MAKEINFO) $(MAKEINFOFLAGS) --no-headers= \ - --plaintext $< -o $@,"GEN","$@") - -%.pdf: %.texi docs/version.texi - $(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@") =20 # Sphinx builds all its documentation at once in one invocation # and handles "don't rebuild things unless necessary" itself. @@ -1081,8 +1054,6 @@ $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index= .html.in qemu-version.h =20 html: sphinxdocs =20 -$(filter %.1 %.7 %.8,$(DOCS)): scripts/texi2pod.pl - # Reports/Analysis =20 %/coverage-report.html: diff --git a/rules.mak b/rules.mak index e39b073d464..00d323a071a 100644 --- a/rules.mak +++ b/rules.mak @@ -144,7 +144,7 @@ cc-option =3D $(if $(shell $(CC) $1 $2 -S -o /dev/null = -xc /dev/null \ cc-c-option =3D $(if $(shell $(CC) $1 $2 -c -o /dev/null -xc /dev/null \ >/dev/null 2>&1 && echo OK), $2, $3) =20 -VPATH_SUFFIXES =3D %.c %.h %.S %.cc %.cpp %.m %.mak %.texi %.sh %.rc Kconf= ig% %.json.in +VPATH_SUFFIXES =3D %.c %.h %.S %.cc %.cpp %.m %.mak %.sh %.rc Kconfig% %.j= son.in set-vpath =3D $(if $1,$(foreach PATTERN,$(VPATH_SUFFIXES),$(eval vpath $(P= ATTERN) $1))) =20 # install-prog list, dir @@ -381,18 +381,6 @@ define unnest-vars $(eval $v :=3D $(filter-out %/,$($v)))) endef =20 -TEXI2MAN =3D $(call quiet-command, \ - perl -Ww -- $(SRC_PATH)/scripts/texi2pod.pl $(TEXI2PODFLAGS) $< $@.pod &&= \ - $(POD2MAN) --section=3D$(subst .,,$(suffix $@)) --center=3D" " --release= =3D" " $@.pod > $@, \ - "GEN","$@") - -%.1: - $(call TEXI2MAN) -%.7: - $(call TEXI2MAN) -%.8: - $(call TEXI2MAN) - GEN_SUBST =3D $(call quiet-command, \ sed -e "s!@libexecdir@!$(libexecdir)!g" < $< > $@, \ "GEN","$@") --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769321; cv=none; d=zohomail.com; s=zohoarc; b=jEQTkm2zf7RjBDJRPDRJmug1DBVCTBCftFIhU+YVfim62rhDin4ZEwve9mCMsVw+jMZZj6fOOxN5inzENiYUrwR43HeEPp4vRSvY7Kvowg1+H5K6YYZNbuJqV0L3uYEplO0AsEqr5kVLBVZDEofOz2zJ2I5/P3BlmcEND6trFls= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769321; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=TwUFslsYRAq6DQ8EhJ3Ic/biPCQDulRhcZjvZY+KwEE=; b=hceVi9Rvd36xzrDZOj8EW+BaTFOSztPj/GjWDDiXXCP+0R1AKJ/0vF35RbGPYAubmt4VpmNb3PpZWTpLwHdbI2PrN4mnpqkxpURJrBSNzZR2gFt/eztozjujGDprJxihc5MlH6rbUSot/m/dsiO4p+E0AMNMXQAh+PtJPDF5s7Y= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 158376932194095.71966531929911; Mon, 9 Mar 2020 08:55:21 -0700 (PDT) Received: from localhost ([::1]:45724 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKkS-0001v3-Jn for importer@patchew.org; Mon, 09 Mar 2020 11:55:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40527) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKa1-0002Gl-5o for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:35 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKZy-0001XR-Il for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:33 -0400 Received: from mail-wr1-x436.google.com ([2a00:1450:4864:20::436]:40191) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKZy-0001X0-AO for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:30 -0400 Received: by mail-wr1-x436.google.com with SMTP id p2so11015445wrw.7 for ; Mon, 09 Mar 2020 08:44:30 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:27 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=TwUFslsYRAq6DQ8EhJ3Ic/biPCQDulRhcZjvZY+KwEE=; b=VY0KyOIrExZq//d/UaGlzKnDRTdY3iC/vWsnYbmTDza/+OoVezNJJ4FTQGmjaVWMGh LmtNTeF4k5+RM+RWGERuVi1DA9vvL0kFwlb5eGi7mOrZ+KnLlI2U5F5UTNxUMc+m+JZl 5hL9Z0Z3ssRIhIiaoPj/n3MiwvuB1wDAtA7BaJnCQBwfdlZkju1JFm/ce3EBBknuQtEW mXMP3yoHltXfAaTwCLsi7D82jU5l6ekw0x8WnewkO8zEdRflxEOWR5QXR/HYp/ALu+Eu WpCYcIKtSkIW/sAe2uH8yiJusJXzEYPUNJhPzTSWLtGg/KYxvMS43mkxzrnIcg5CzZVN TCkg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=TwUFslsYRAq6DQ8EhJ3Ic/biPCQDulRhcZjvZY+KwEE=; b=ID9gYTBrgtW0Bq9AGQoMQFn5m0Y/oi5tisr8cZjGzWPUkOqiGeQgHgN4jNJOH6aZvX mOTNyxFjjt3WuCEpsespQ2vbF/Vu++hC9wRxnsHw4VyJsfmQMzistVpmESY0LpqpvTtQ JAWpldH0XLvPugVJbiX901dBVwWzKAQ6GHwlfhyHsk0iYMA1MF+CyvBtguMEb8JLg3Xx EXIgZmgNBlsr5dRB0aSBuhSnJc8pk/v3sB0nRs5tjQyUmQ3orCwV4V1LkK7E4lph0WLv 3roWM4Y2MXdlopIy0axtYFVjrGASb5rAIpDeunWURwg1dz2nPY35wjSrUMrPDEtsInTi 7HHw== X-Gm-Message-State: ANhLgQ0EQhfEUFW8ZwPTRgfSPcAjyA31IJ2gQQ2/XYZTvUxjbVr3rfLT gUGdYkhsZaRv3njanbxVAJlU1I5ZkETcjA== X-Google-Smtp-Source: ADFU+vvbN+bCrnmQClfqbduFTBqnT0HRmQYFv9oJZvmnSW3f6OITCcxHioLd9wKBJDo21SJ+WLk+gg== X-Received: by 2002:a5d:6a8d:: with SMTP id s13mr18667066wru.260.1583768668214; Mon, 09 Mar 2020 08:44:28 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 15/18] scripts/texi2pod: Delete unused script Date: Mon, 9 Mar 2020 15:44:02 +0000 Message-Id: <20200309154405.13548-16-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::436 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We no longer need the texi2pod script, so we can delete it, and the special-casing it had in the checkpatch script. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- scripts/checkpatch.pl | 2 +- scripts/texi2pod.pl | 536 ------------------------------------------ 2 files changed, 1 insertion(+), 537 deletions(-) delete mode 100755 scripts/texi2pod.pl diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index b27e4ff5e95..701f76a6ccc 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -1631,7 +1631,7 @@ sub process { # tabs are only allowed in assembly source code, and in # some scripts we imported from other projects. next if ($realfile =3D~ /\.(s|S)$/); - next if ($realfile =3D~ /(checkpatch|get_maintainer|texi2pod)\.pl$/); + next if ($realfile =3D~ /(checkpatch|get_maintainer)\.pl$/); =20 if ($rawline =3D~ /^\+.*\t/) { my $herevet =3D "$here\n" . cat_vet($rawline) . "\n"; diff --git a/scripts/texi2pod.pl b/scripts/texi2pod.pl deleted file mode 100755 index 8bfc6f6f4c4..00000000000 --- a/scripts/texi2pod.pl +++ /dev/null @@ -1,536 +0,0 @@ -#! /usr/bin/env perl - -# Copyright (C) 1999, 2000, 2001, 2003 Free Software Foundation, Inc. - -# This file is part of GCC. - -# GCC is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) -# any later version. - -# GCC is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. - -# You should have received a copy of the GNU General Public License -# along with GCC; see the file COPYING. If not, -# see . - -# This does trivial (and I mean _trivial_) conversion of Texinfo -# markup to Perl POD format. It's intended to be used to extract -# something suitable for a manpage from a Texinfo document. - -use warnings; - -$output =3D 0; -$skipping =3D 0; -%sects =3D (); -$section =3D ""; -@icstack =3D (); -@endwstack =3D (); -@skstack =3D (); -@instack =3D (); -$shift =3D ""; -%defs =3D (); -$fnno =3D 1; -$inf =3D ""; -$ibase =3D ""; -@ipath =3D (); -$encoding =3D undef; -@args =3D (); - -while ($_ =3D shift) { - if (/^-D(.*)$/) { - if ($1 ne "") { - $flag =3D $1; - } else { - $flag =3D shift; - } - $value =3D ""; - ($flag, $value) =3D ($flag =3D~ /^([^=3D]+)(?:=3D(.+))?/); - die "no flag specified for -D\n" - unless $flag ne ""; - die "flags may only contain letters, digits, hyphens, dashes and undersco= res\n" - unless $flag =3D~ /^[a-zA-Z0-9_-]+$/; - $defs{$flag} =3D $value; - } elsif (/^-I(.*)$/) { - if ($1 ne "") { - $flag =3D $1; - } else { - $flag =3D shift; - } - push (@ipath, $flag); - } elsif (/^-/) { - usage(); - } else { - $in =3D $_, next unless defined $in; - $out =3D $_, next unless defined $out; - usage(); - } -} - -if (defined $in) { - $inf =3D gensym(); - open($inf, "<$in") or die "opening \"$in\": $!\n"; - $ibase =3D $1 if $in =3D~ m|^(.+)/[^/]+$|; -} else { - $inf =3D \*STDIN; -} - -if (defined $out) { - open(STDOUT, ">$out") or die "opening \"$out\": $!\n"; -} - -while(defined $inf) { -while(<$inf>) { - # Certain commands are discarded without further processing. - /^\@(?: - [a-z]+index # @*index: useful only in complete manual - |need # @need: useful only in printed manual - |(?:end\s+)?group # @group .. @end group: ditto - |page # @page: ditto - |node # @node: useful only in .info file - |(?:end\s+)?ifnottex # @ifnottex .. @end ifnottex: use contents - )\b/x and next; - - chomp; - - # Look for filename and title markers. - /^\@setfilename\s+([^.]+)/ and $fn =3D $1, next; - /^\@settitle\s+([^.]+)/ and $tl =3D postprocess($1), next; - - # Look for document encoding - /^\@documentencoding\s+([^.]+)/ and do { - $encoding =3D $1 unless defined $encoding; - next; - }; - - # Identify a man title but keep only the one we are interested in. - /^\@c\s+man\s+title\s+([A-Za-z0-9-]+)\s+(.+)/ and do { - if (exists $defs{$1}) { - $fn =3D $1; - $tl =3D postprocess($2); - } - next; - }; - - # Look for blocks surrounded by @c man begin SECTION ... @c man end. - # This really oughta be @ifman ... @end ifman and the like, but such - # would require rev'ing all other Texinfo translators. - /^\@c\s+man\s+begin\s+([A-Z]+)\s+([A-Za-z0-9-]+)/ and do { - $output =3D 1 if exists $defs{$2}; - $sect =3D $1; - next; - }; - /^\@c\s+man\s+begin\s+([A-Z]+)/ and $sect =3D $1, $output =3D 1, next; - /^\@c\s+man\s+end/ and do { - $sects{$sect} =3D "" unless exists $sects{$sect}; - $sects{$sect} .=3D postprocess($section); - $section =3D ""; - $output =3D 0; - next; - }; - - # handle variables - /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and do { - $defs{$1} =3D $2; - next; - }; - /^\@clear\s+([a-zA-Z0-9_-]+)/ and do { - delete $defs{$1}; - next; - }; - - # Single line command handlers. - - /^\@include\s+(.+)$/ and do { - push @instack, $inf; - $inf =3D gensym(); - $file =3D postprocess($1); - - # Try cwd and $ibase, then explicit -I paths. - $done =3D 0; - foreach $path ("", $ibase, @ipath) { - $mypath =3D $file; - $mypath =3D $path . "/" . $mypath if ($path ne ""); - open($inf, "<" . $mypath) and ($done =3D 1, last); - } - die "cannot find $file" if !$done; - next; - }; - - next unless $output; - - # Discard comments. (Can't do it above, because then we'd never see - # @c man lines.) - /^\@c\b/ and next; - - # End-block handler goes up here because it needs to operate even - # if we are skipping. - /^\@end\s+([a-z]+)/ and do { - # Ignore @end foo, where foo is not an operation which may - # cause us to skip, if we are presently skipping. - my $ended =3D $1; - next if $skipping && $ended !~ /^(?:ifset|ifclear|ignore|menu|iftex|copyi= ng)$/; - - die "\@end $ended without \@$ended at line $.\n" unless defined $endw; - die "\@$endw ended by \@end $ended at line $.\n" unless $ended eq $endw; - - $endw =3D pop @endwstack; - - if ($ended =3D~ /^(?:ifset|ifclear|ignore|menu|iftex)$/) { - $skipping =3D pop @skstack; - next; - } elsif ($ended =3D~ /^(?:example|smallexample|display - |quotation|deftp|deftypefn)$/x) { - $shift =3D ""; - $_ =3D ""; # need a paragraph break - } elsif ($ended =3D~ /^(?:itemize|enumerate|[fv]?table)$/) { - $_ =3D "\n=3Dback\n"; - $ic =3D pop @icstack; - } elsif ($ended eq "multitable") { - $_ =3D "\n=3Dback\n"; - } else { - die "unknown command \@end $ended at line $.\n"; - } - }; - - # We must handle commands which can cause skipping even while we - # are skipping, otherwise we will not process nested conditionals - # correctly. - /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw =3D "ifset"; - $skipping =3D 1 unless exists $defs{$1}; - next; - }; - - /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw =3D "ifclear"; - $skipping =3D 1 if exists $defs{$1}; - next; - }; - - /^\@(ignore|menu|iftex|copying)\b/ and do { - push @endwstack, $endw; - push @skstack, $skipping; - $endw =3D $1; - $skipping =3D 1; - next; - }; - - next if $skipping; - - # Character entities. First the ones that can be replaced by raw text - # or discarded outright: - s/\@copyright\{\}/(c)/g; - s/\@dots\{\}/.../g; - s/\@enddots\{\}/..../g; - s/\@([.!? ])/$1/g; - s/\@[:-]//g; - s/\@bullet(?:\{\})?/*/g; - s/\@TeX\{\}/TeX/g; - s/\@pounds\{\}/\#/g; - s/\@minus(?:\{\})?/-/g; - s/\\,/,/g; - - # Now the ones that have to be replaced by special escapes - # (which will be turned back into text by unmunge()) - s/&/&/g; - s/\@\{/{/g; - s/\@\}/}/g; - s/\@\@/&at;/g; - - # Inside a verbatim block, handle @var specially. - if ($shift ne "") { - s/\@var\{([^\}]*)\}/<$1>/g; - } - - # POD doesn't interpret E<> inside a verbatim block. - if ($shift eq "") { - s//>/g; - } else { - s//>/g; - } - - /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ - and $_ =3D "\n=3Dhead2 $1\n"; - /^\@subsection\s+(.+)$/ - and $_ =3D "\n=3Dhead3 $1\n"; - /^\@subsubsection\s+(.+)$/ - and $_ =3D "\n=3Dhead4 $1\n"; - - # Block command handlers: - /^\@itemize(?:\s+(\@[a-z]+|\*|-))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic =3D $1; - } else { - $ic =3D '*'; - } - $_ =3D "\n=3Dover 4\n"; - $endw =3D "itemize"; - }; - - /^\@enumerate(?:\s+([a-zA-Z0-9]+))?/ and do { - push @endwstack, $endw; - push @icstack, $ic; - if (defined $1) { - $ic =3D $1 . "."; - } else { - $ic =3D "1."; - } - $_ =3D "\n=3Dover 4\n"; - $endw =3D "enumerate"; - }; - - /^\@multitable\s.*/ and do { - push @endwstack, $endw; - $endw =3D "multitable"; - $_ =3D "\n=3Dover 4\n"; - }; - - /^\@([fv]?table)\s+(\@[a-z]+)/ and do { - push @endwstack, $endw; - push @icstack, $ic; - $endw =3D $1; - $ic =3D $2; - $ic =3D~ s/\@(?:samp|strong|key|gcctabopt|option|env)/B/; - $ic =3D~ s/\@(?:code|kbd)/C/; - $ic =3D~ s/\@(?:dfn|var|emph|cite|i)/I/; - $ic =3D~ s/\@(?:file)/F/; - $ic =3D~ s/\@(?:asis)//; - $_ =3D "\n=3Dover 4\n"; - }; - - /^\@((?:small)?example|display)/ and do { - push @endwstack, $endw; - $endw =3D $1; - $shift =3D "\t"; - $_ =3D ""; # need a paragraph break - }; - - /^\@item\s+(.*\S)\s*$/ and $endw eq "multitable" and do { - @columns =3D (); - for $column (split (/\s*\@tab\s*/, $1)) { - # @strong{...} is used a @headitem work-alike - $column =3D~ s/^\@strong\{(.*)\}$/$1/; - push @columns, $column; - } - $_ =3D "\n=3Ditem ".join (" : ", @columns)."\n"; - }; - - /^\@(quotation)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw =3D $1; - $_ =3D "\n$2:" - }; - - /^{(.*)}$|^(.*)$/ and $#args > 0 and do { - $kind =3D $args[0]; - $arguments =3D $1 // ""; - if ($endw eq "deftypefn") { - $ret =3D $args[1]; - $fname =3D "B<$args[2]>"; - $_ =3D $ret ? "$ret " : ""; - $_ .=3D "$fname $arguments ($kind)"; - } else { - $_ =3D "B<$args[1]> ($kind)\n\n$arguments"; - } - @args =3D (); - }; - - /^\@(deftp)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw =3D $1; - $arg =3D $2; - $arg =3D~ s/{([^}]*)}/$1/g; - $arg =3D~ s/\@$//; - @args =3D split (/ /, $arg); - $_ =3D ""; - }; - - /^\@(deftypefn)\s*(.+)?$/ and do { - push @endwstack, $endw; - $endw =3D $1; - $arg =3D $2; - $arg =3D~ s/{([^}]*)}/$1/g; - $arg =3D~ s/\@$//; - @args =3D split (/ /, $arg); - $_ =3D ""; - }; - - /^\@itemx?\s*(.+)?$/ and do { - if (defined $1) { - if ($ic eq "") { - $_ =3D "\n=3Ditem $1\n"; - } else { - # Entity escapes prevent munging by the <> processing belo= w. - $_ =3D "\n=3Ditem $ic\<$1\>\n"; - } - } else { - $_ =3D "\n=3Ditem $ic\n"; - $ic =3D~ y/A-Ya-y/B-Zb-z/; - $ic =3D~ s/(\d+)/$1 + 1/eg; - } - }; - - $section .=3D $shift.$_."\n"; -} -# End of current file. -close($inf); -$inf =3D pop @instack; -} - -die "No filename or title\n" unless defined $fn && defined $tl; - -print "=3Dencoding $encoding\n\n" if defined $encoding; - -$sects{NAME} =3D "$fn \- $tl\n"; -$sects{FOOTNOTES} .=3D "=3Dback\n" if exists $sects{FOOTNOTES}; - -for $sect (qw(NAME SYNOPSIS DESCRIPTION OPTIONS ENVIRONMENT FILES - BUGS NOTES FOOTNOTES EXAMPLES SEEALSO AUTHOR COPYRIGHT)) { - if(exists $sects{$sect}) { - $head =3D $sect; - $head =3D~ s/SEEALSO/SEE ALSO/; - print "=3Dhead1 $head\n\n"; - print scalar unmunge ($sects{$sect}); - print "\n"; - } -} - -sub usage -{ - die "usage: $0 [-D toggle...] [infile [outfile]]\n"; -} - -sub postprocess -{ - local $_ =3D $_[0]; - - # @value{foo} is replaced by whatever 'foo' is defined as. - while (m/(\@value\{([a-zA-Z0-9_-]+)\})/g) { - if (! exists $defs{$2}) { - print STDERR "Option $2 not defined\n"; - s/\Q$1\E//; - } else { - $value =3D $defs{$2}; - s/\Q$1\E/$value/; - } - } - - # Formatting commands. - # Temporary escape for @r. - s/\@r\{([^\}]*)\}/R<$1>/g; - s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; - s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; - s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<= $1>/g; - s/\@sc\{([^\}]*)\}/\U$1/g; - s/\@file\{([^\}]*)\}/F<$1>/g; - s/\@w\{([^\}]*)\}/S<$1>/g; - s/\@t\{([^\}]*)\}/$1/g; - s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; - - # keep references of the form @ref{...}, print them bold - s/\@(?:ref)\{([^\}]*)\}/B<$1>/g; - - # Change double single quotes to double quotes. - s/''/"/g; - s/``/"/g; - - # Cross references are thrown away, as are @noindent and @refill. - # (@noindent is impossible in .pod, and @refill is unnecessary.) - # @* is also impossible in .pod; we discard it and any newline that - # follows it. Similarly, our macro @gol must be discarded. - - s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; - s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; - s/;\s+\@pxref\{(?:[^\}]*)\}//g; - s/\@noindent\s*//g; - s/\@refill//g; - s/\@gol//g; - s/\@\*\s*\n?//g; - - # Anchors are thrown away - s/\@anchor\{(?:[^\}]*)\}//g; - - # @uref can take one, two, or three arguments, with different - # semantics each time. @url and @email are just like @uref with - # one argument, for our purposes. - s/\@(?:uref|url|email)\{([^\},]*)\}/<B<$1>>/g; - s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; - s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; - - # Un-escape <> at this point. - s/<//g; - - # Now un-nest all B<>, I<>, R<>. Theoretically we could have - # indefinitely deep nesting; in practice, one level suffices. - 1 while s/([BIR])<([^<>]*)([BIR])<([^<>]*)>/$1<$2>$3<$4>$1 with bare ...; eliminate empty markup, B<>; - # shift white space at the ends of [BI]<...> expressions outside - # the expression. - s/R<([^<>]*)>/$1/g; - s/[BI]<>//g; - s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g; - s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g; - - # Extract footnotes. This has to be done after all other - # processing because otherwise the regexp will choke on formatting - # inside @footnote. - while (/\@footnote/g) { - s/\@footnote\{([^\}]+)\}/[$fnno]/; - add_footnote($1, $fnno); - $fnno++; - } - - return $_; -} - -sub unmunge -{ - # Replace escaped symbols with their equivalents. - local $_ =3D $_[0]; - - s/</E/g; - s/>/E/g; - s/{/\{/g; - s/}/\}/g; - s/&at;/\@/g; - s/&/&/g; - return $_; -} - -sub add_footnote -{ - unless (exists $sects{FOOTNOTES}) { - $sects{FOOTNOTES} =3D "\n=3Dover 4\n\n"; - } - - $sects{FOOTNOTES} .=3D "=3Ditem $fnno.\n\n"; $fnno++; - $sects{FOOTNOTES} .=3D $_[0]; - $sects{FOOTNOTES} .=3D "\n\n"; -} - -# stolen from Symbol.pm -{ - my $genseq =3D 0; - sub gensym - { - my $name =3D "GEN" . $genseq++; - my $ref =3D \*{$name}; - delete $::{$name}; - return $ref; - } -} --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769371; cv=none; d=zohomail.com; s=zohoarc; b=JFPnVDkz44Bmvqy0CULrpWfmheJ14tK8YrUUzFRIHvrzk/4TiV/RqjzYrTdG7aECNShpr+1QRYqzCQ84KX/J6RLs187Hd2CvgPX0tuPRO+sDPCcht++mQUVhKc9ZREl1bZW3/RZcMl+41lvTCRJT29m3l9fqZDAwPZP7Lm/ZN2E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769371; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=hy1+wvhnmgnT9CuRfCiRbzAqA7FrWPViwFJZB+FlhcY=; b=Gn8qcA1QdVNsBqi3ODGNLr+VpD1G30h9/xTQ6Ncm2tO6LRbKt+UXt27IjLtjHzf1SdCDAv/6z0GB551mppUfAbff24ZFgJRtVrqqCUD5WPNHMoFuG/W7PXq8u5gmcxT3KNUPZvHBaRbCv3BiUikT3SSoIJIR1eMZogC56ssdJxA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 15837693718375.896328773450136; Mon, 9 Mar 2020 08:56:11 -0700 (PDT) Received: from localhost ([::1]:45762 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKlG-0003bV-L9 for importer@patchew.org; Mon, 09 Mar 2020 11:56:10 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40549) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKa4-0002ON-0q for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:37 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKa2-0001Zq-Ss for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:35 -0400 Received: from mail-wm1-x331.google.com ([2a00:1450:4864:20::331]:53117) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKa2-0001ZO-Me for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:34 -0400 Received: by mail-wm1-x331.google.com with SMTP id p9so3995wmc.2 for ; Mon, 09 Mar 2020 08:44:34 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.28 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:28 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=hy1+wvhnmgnT9CuRfCiRbzAqA7FrWPViwFJZB+FlhcY=; b=X66+vyV5Dr+7CKUEqZ7h2mIqDYdP/0hAgIQbere4X4Z3q/4eFrGbRa/OMbc8Ga1XR0 DlCl5F76NL6RTLN811AZT7ZHkE6lhr7nc5LLCCLMLQyIbS+hsS9bJbSDvrH8Es8qV44R 6f/Ft0dsmGyh9M8OpdXqJ85F4JDhIqLpETjgtfbOt58aal4OZw6QgpP3EZT5PSilXPRr 24qE4esjw6kVp4O88d2P416tCZO3JgYNi+g2CA7OaXkADfnpcIJyjdqBMBKIVB264SOm vE3iJRlCxcJ+mtuA4U0nqG47EWl4uXrupy15+2Ub6K6LMm+caqCp4fLJi+QJFwA64h6M 1O9w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=hy1+wvhnmgnT9CuRfCiRbzAqA7FrWPViwFJZB+FlhcY=; b=Fbu9gbXDAAy72Y7wgTaqW6jrhJt6tFoyldcS/ZnlJ4qHMhKK3vX84Cg9Xn42phEf5p cOJ+N9G/lU45iemB4PwfpwQL0GD/mVQMlRZyYTp9+wII2ANiz9KxQLWmxBeZVcc63lXX 0Pribax2M51SBQlLT0cD3tksXb28IjXR2O8sZl8sadAn19pq1MWC/x9rh655YeeWq6/y wskG2HayvFi87wexZbjIfT1UJmpiKSdJUgVW1OByjFBFkqUcig++54OIIBhJVobnYA+0 Ok7tbEsJ6JEqYyGKAWELyHQ77y+n/iZz4UkLE4KNU2Q4jLi7+65BTTwa7csS5GmHjQ3U y77w== X-Gm-Message-State: ANhLgQ3rTHL5CxJlE3PvvKUxk8hYxn+rGLxWtPBn/B6Go1AGaUpjbJXq YpHcInQlh7LSVcVElgp3RnXXJvdj8h7c0Q== X-Google-Smtp-Source: ADFU+vvN3WG78SjdwJGMDhrCXSsJkSHg10neJgChQtlI1fezEWAhrDMxyvNB2oiJYgG4VbiBpDtSIg== X-Received: by 2002:a1c:48c1:: with SMTP id v184mr20502805wma.5.1583768670356; Mon, 09 Mar 2020 08:44:30 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 16/18] Remove Texinfo related files from .gitignore and git.orderfile Date: Mon, 9 Mar 2020 15:44:03 +0000 Message-Id: <20200309154405.13548-17-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::331 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We don't use Texinfo any more; we can remove the references to the .texi source files and the generated output files from our .gitignore and git.orderfile. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- .gitignore | 15 --------------- scripts/git.orderfile | 1 - 2 files changed, 16 deletions(-) diff --git a/.gitignore b/.gitignore index 0c5af83aa74..920d523f40d 100644 --- a/.gitignore +++ b/.gitignore @@ -45,20 +45,15 @@ /qapi/qapi-visit-*.[ch] !/qapi/qapi-visit-core.c /qapi/qapi-visit.[ch] -/qapi/qapi-doc.texi /qemu-edid /qemu-img /qemu-nbd /qemu-options.def -/qemu-options.texi -/qemu-img-cmds.texi /qemu-img-cmds.h /qemu-io /qemu-ga /qemu-bridge-helper /qemu-keymap -/qemu-monitor.texi -/qemu-monitor-info.texi /qemu-version.h /qemu-version.h.tmp /module_block.h @@ -82,7 +77,6 @@ *.ky *.log *.pdf -*.pod *.cps *.fns *.kys @@ -124,15 +118,6 @@ /pc-bios/s390-ccw/s390-ccw.elf /pc-bios/s390-ccw/s390-ccw.img /docs/built -/docs/interop/qemu-ga-qapi.texi -/docs/interop/qemu-ga-ref.html -/docs/interop/qemu-ga-ref.info* -/docs/interop/qemu-ga-ref.txt -/docs/interop/qemu-qmp-qapi.texi -/docs/interop/qemu-qmp-ref.html -/docs/interop/qemu-qmp-ref.info* -/docs/interop/qemu-qmp-ref.txt -/docs/version.texi /contrib/vhost-user-gpu/50-qemu-gpu.json *.tps .stgit-* diff --git a/scripts/git.orderfile b/scripts/git.orderfile index 7cf22e0bf54..f69dff07dbc 100644 --- a/scripts/git.orderfile +++ b/scripts/git.orderfile @@ -11,7 +11,6 @@ =20 # Documentation docs/* -*.texi =20 # build system configure --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769290; cv=none; d=zohomail.com; s=zohoarc; b=HyTK2yg1X2lmDoSFkcppE/av/iuu+TZfq4FwEPKR18W/uy46B6XUkqob5sZVFYXZTW78C6IBXZbBZ32hUL74JxGKIRiQz3x8ALr9ngJKd+nfKY2rks9pbOi78FTCabfsePRXQ0C7WL0pxoK+peISeqw723hrogYYn15P0oz6O7A= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769290; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=qaePRTDVUqiKI0GPXX/XP44aWtRXgQAztnFoJ62x+fU=; b=g2EQXscyMla/TOpyPq9EU+TAmICPmfBeq6Cl9LY4lDH6CYWWzBRxq+4h7k7zsbKtDoU8UF44grbo9OAD5gNPDccF+cisGvmEax6ER1I7LEuKCa0aQGHUX65M8AYiMrSr7+EJSaOfYkJditzVNuSbWjkPyYfTZn9TmgCIIkn7lvM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769290632572.5143948113029; Mon, 9 Mar 2020 08:54:50 -0700 (PDT) Received: from localhost ([::1]:45708 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKjx-0000yO-4Z for importer@patchew.org; Mon, 09 Mar 2020 11:54:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40567) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKa5-0002T9-RB for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:38 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKa4-0001c7-R3 for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:37 -0400 Received: from mail-wm1-x32b.google.com ([2a00:1450:4864:20::32b]:40071) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKa4-0001ba-Kb for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:36 -0400 Received: by mail-wm1-x32b.google.com with SMTP id e26so10089917wme.5 for ; Mon, 09 Mar 2020 08:44:36 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.34 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=qaePRTDVUqiKI0GPXX/XP44aWtRXgQAztnFoJ62x+fU=; b=jNOlks/Dgt/ock/7nTRQTj3mYYaXzwoe2DVSy/WXPPqdE55coeVguewIDqq9lT/8+N O5fUE1UhBe1BL2VOGQl0IUMgMxxmazm0pSheH3bz6QHdko8PAv9aFlSHS0NuptuXDLND 597nv1wX8QPJCoWqvMzK0oq48k+fYxUGxKq4wVhEbx9rQ+rzLfOvXWR+PDlJnA2sDg0m BR7raLn3X30LQUFNO+10+r0nx0I3+U1lEq0RdPv2AArr0kWWH4uSNmaa16S2dZ8hifsx pB1Tu5lKbFnWrRvNgQeUpIkOqXVyckfM+/Q8TbSDGo8s/Ou+dVQ1eYBwN4G7TEarHIjz S33g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=qaePRTDVUqiKI0GPXX/XP44aWtRXgQAztnFoJ62x+fU=; b=kad2NcLuGOV2KllZ0Er/3UNaUvRBHGnGyqItAf2QkBrKeMeoXSlJ8IY302xfs4XCRt oQsoGk0gOJM5OPaCOByT4NLtURvkFriJsiCUPCn5s13UD7XUXw3TM4HuumMSIJWtH8J4 LVWsCYwYTC2dwjMXL9wz195jjnIoVfJqPkceddvqrEo2sR9jUgPWBqkuRmOkQMjK8aRP ljmwRGdi3VvsMFHX73e7DG3JjagKnupJLKr3rxBkiRyeHanjfQnnmYjxx4C30m0Bpw8D 8lJzlklDQiqZlBQuzsK04+B8wvrvBASc8RRjjny15/hBT+CnwwIThdUTsbGIVrs3/sJ8 9oKw== X-Gm-Message-State: ANhLgQ2gV5pPMGmuFbBq/862XkCZEwaEowJ77LVJQiUttY1zRkPvsCIo pIfw30mfbBoU0TIllBRGwxLVejQRdMpoRQ== X-Google-Smtp-Source: ADFU+vuH4twHShWG6tz19R0ZEBxWgCrcJDHcDZfiq9V1T0wTloArYlWNdmw9ChwsIzQzIj4UdHcybQ== X-Received: by 2002:a1c:a384:: with SMTP id m126mr20634123wme.84.1583768675315; Mon, 09 Mar 2020 08:44:35 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 17/18] configure: Drop texinfo requirement Date: Mon, 9 Mar 2020 15:44:04 +0000 Message-Id: <20200309154405.13548-18-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32b X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We don't need the texinfo and pod2man programs to build our documentation any more, so remove them from configure's tests. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- configure | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/configure b/configure index fab6281eb70..3b642136211 100755 --- a/configure +++ b/configure @@ -4888,14 +4888,14 @@ if test "$docs" !=3D "no" ; then else sphinx_ok=3Dno fi - if has makeinfo && has pod2man && test "$sphinx_ok" =3D "yes"; then + if test "$sphinx_ok" =3D "yes"; then docs=3Dyes else if test "$docs" =3D "yes" ; then if has $sphinx_build && test "$sphinx_ok" !=3D "yes"; then echo "Warning: $sphinx_build exists but it is either too old or us= es too old a Python version" >&2 fi - feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a= Python 3 version of python-sphinx" + feature_not_found "docs" "Install a Python 3 version of python-sphin= x" fi docs=3Dno fi @@ -6273,13 +6273,6 @@ if test "$solaris" =3D "no" ; then fi fi =20 -# test if pod2man has --utf8 option -if pod2man --help | grep -q utf8; then - POD2MAN=3D"pod2man --utf8" -else - POD2MAN=3D"pod2man" -fi - # Use ASLR, no-SEH and DEP if available if test "$mingw32" =3D "yes" ; then for flag in --dynamicbase --no-seh --nxcompat; do @@ -7672,7 +7665,6 @@ echo "LDFLAGS_SHARED=3D$LDFLAGS_SHARED" >> $config_ho= st_mak echo "LIBS_QGA+=3D$libs_qga" >> $config_host_mak echo "TASN1_LIBS=3D$tasn1_libs" >> $config_host_mak echo "TASN1_CFLAGS=3D$tasn1_cflags" >> $config_host_mak -echo "POD2MAN=3D$POD2MAN" >> $config_host_mak if test "$gcov" =3D "yes" ; then echo "CONFIG_GCOV=3Dy" >> $config_host_mak echo "GCOV=3D$gcov_tool" >> $config_host_mak --=20 2.20.1 From nobody Thu Nov 13 23:29:50 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1583769440; cv=none; d=zohomail.com; s=zohoarc; b=ZH02Hm0WKYMVfmHSZiuovdHioUXJMyGI6AJq4uvnjE0TTmraNL8FJCSQVF1lPpc/WtXRAK4JJuNQhiSIcTg6QWBL+NYB+sGB1YKmKzWDmBbM5lsXYah+rt2GOWSIPEv0Fyyj3eDeN71v0dSaFR6vGA2KkI4/kcvRJw0BVuVb7rs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583769440; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=RXakKGJYlD5Zmh6y1LTMLfkcNLUz/wF1gxWzZbqUBNA=; b=IdMK1GXTxmeHlr3D2sYBPj0PWCsZq6RHPOOxyzhnxt5cYl2zDXa/a4p8wo4GvGQtcnhgfA3EPB9L/yaI0gBQA2GuZGJVLSHHCzogKXMui2Lt9vokTj8uhej7Q6a6XSEblSt2SV+eG+iaUImv9tSIt1E0DQ3RvhCsMXemGaZoYhA= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583769440551176.59833981894394; Mon, 9 Mar 2020 08:57:20 -0700 (PDT) Received: from localhost ([::1]:45792 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKmN-0005B3-DU for importer@patchew.org; Mon, 09 Mar 2020 11:57:19 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:40587) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jBKa8-0002Yw-3S for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:41 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jBKa5-0001dm-Vb for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:39 -0400 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:38211) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jBKa5-0001cu-PE for qemu-devel@nongnu.org; Mon, 09 Mar 2020 11:44:37 -0400 Received: by mail-wr1-x435.google.com with SMTP id t11so11833753wrw.5 for ; Mon, 09 Mar 2020 08:44:37 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id d63sm25932166wmd.44.2020.03.09.08.44.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 09 Mar 2020 08:44:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=RXakKGJYlD5Zmh6y1LTMLfkcNLUz/wF1gxWzZbqUBNA=; b=otYy7aEpmcxrRr0o4Scr9n6HF2Twn7NHHLbhUIwbx0q1jYIULomKRBzi4d0EZHK8Jb WEAsXzXA4c/jy30PGkeSH/T2DabRjilp5jSg13ZPB7llpiemEHcjlbUHJD3WHOcoRp0k SD1v3k3Lj0ZJhVQTGJuXwsX8PkcQm6E3jB+1ulpvIkGhiHXL4day8EdauvQCBo5ETiwa 8SCstrFDBGpFgfK39MQKrM1aKtaAA3PDNrqYwxgrRn+DyVU7SOYYU/eFpoRGbaDl/77T n6TSDXwxgltCMYUsP9cwBFZGVyKEYnAmKE7Drl6bWiv1Ekb5KFNJvchVgZvROcueJDU9 S1Vw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=RXakKGJYlD5Zmh6y1LTMLfkcNLUz/wF1gxWzZbqUBNA=; b=cXTtXOG4KfuEur8tpqPDWqpiKkD6bSyhfSjld0AzdV89jV4vVFVX6HDHTJTieF4krN 7OLicWZJ153bDoho9sTdoda0jQxA6jX/0kNNuhjNZOUJeEFBQQXzURxtwxPQidZp9TRM lDCRIWeLQ3tgjc8jqhfV8M0+szp5bwawuiM0+QGrvO8gSYaRk6lWfza0iYIOz0rVwHOu /r4K0qrxgbf7E6mG58Dvz7JWUCaxID7/gL8rxUXdBFFKG+KfMW6PVx+YFcBQeOqbLROu dUupU3XQzufE2kGdDbGuISLMY3IuDHz17B2/UYrwCdJhZS9/0kg9UbBWjyzJoJztowf6 xfJg== X-Gm-Message-State: ANhLgQ0/HLJXDctAWIdo9Igf5nP26HkexhgO864O8vg6g6dc94ds7hd1 k/oe30bZ/9aq2OD4zDvxf7/E48uWAynJZA== X-Google-Smtp-Source: ADFU+vvoRkeygxkFNjKVMvHhxJivHz2FCCZWZMwjQKXICghLrWUWx1bDp87/zqTpeqccwdSoDYm36g== X-Received: by 2002:adf:e9c4:: with SMTP id l4mr9748038wrn.421.1583768676506; Mon, 09 Mar 2020 08:44:36 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH v4 18/18] Remove texinfo dependency from docker and CI configs Date: Mon, 9 Mar 2020 15:44:05 +0000 Message-Id: <20200309154405.13548-19-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200309154405.13548-1-peter.maydell@linaro.org> References: <20200309154405.13548-1-peter.maydell@linaro.org> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::435 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Markus Armbruster , Michael Roth , Stefan Hajnoczi , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" We don't need texinfo to build the docs any more, so we can drop that dependency from our docker and other CI configs. Signed-off-by: Peter Maydell Reviewed-by: Richard Henderson --- .travis.yml | 1 - tests/docker/dockerfiles/debian10.docker | 1 - tests/docker/dockerfiles/debian9.docker | 1 - tests/docker/dockerfiles/fedora.docker | 1 - tests/docker/dockerfiles/ubuntu.docker | 1 - tests/docker/dockerfiles/ubuntu1804.docker | 1 - 6 files changed, 6 deletions(-) diff --git a/.travis.yml b/.travis.yml index b92798ac3b9..71bee8d631c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -197,7 +197,6 @@ jobs: apt: packages: - python3-sphinx - - texinfo - perl =20 =20 diff --git a/tests/docker/dockerfiles/debian10.docker b/tests/docker/docker= files/debian10.docker index 5de79ae5527..f2744e18e5a 100644 --- a/tests/docker/dockerfiles/debian10.docker +++ b/tests/docker/dockerfiles/debian10.docker @@ -29,5 +29,4 @@ RUN apt update && \ psmisc \ python3 \ python3-sphinx \ - texinfo \ $(apt-get -s build-dep qemu | egrep ^Inst | fgrep '[all]' | cut -d= \ -f2) diff --git a/tests/docker/dockerfiles/debian9.docker b/tests/docker/dockerf= iles/debian9.docker index 8cbd742bb5f..f08442a436a 100644 --- a/tests/docker/dockerfiles/debian9.docker +++ b/tests/docker/dockerfiles/debian9.docker @@ -28,5 +28,4 @@ RUN apt update && \ psmisc \ python3 \ python3-sphinx \ - texinfo \ $(apt-get -s build-dep qemu | egrep ^Inst | fgrep '[all]' | cut -d= \ -f2) diff --git a/tests/docker/dockerfiles/fedora.docker b/tests/docker/dockerfi= les/fedora.docker index a6522228c02..db38d5e4c4a 100644 --- a/tests/docker/dockerfiles/fedora.docker +++ b/tests/docker/dockerfiles/fedora.docker @@ -86,7 +86,6 @@ ENV PACKAGES \ systemd-devel \ systemtap-sdt-devel \ tar \ - texinfo \ usbredir-devel \ virglrenderer-devel \ vte291-devel \ diff --git a/tests/docker/dockerfiles/ubuntu.docker b/tests/docker/dockerfi= les/ubuntu.docker index b6c7b41dddd..cfc55ed01c0 100644 --- a/tests/docker/dockerfiles/ubuntu.docker +++ b/tests/docker/dockerfiles/ubuntu.docker @@ -63,7 +63,6 @@ ENV PACKAGES flex bison \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=3Dnoninteractive apt-get -y install $PACKAGES diff --git a/tests/docker/dockerfiles/ubuntu1804.docker b/tests/docker/dock= erfiles/ubuntu1804.docker index 1efedeef995..c265a952530 100644 --- a/tests/docker/dockerfiles/ubuntu1804.docker +++ b/tests/docker/dockerfiles/ubuntu1804.docker @@ -49,7 +49,6 @@ ENV PACKAGES flex bison \ python3-yaml \ python3-sphinx \ sparse \ - texinfo \ xfslibs-dev RUN apt-get update && \ DEBIAN_FRONTEND=3Dnoninteractive apt-get -y install $PACKAGES --=20 2.20.1